[Telepathy] Account and AccountManager objects

[Alberto Mardegan]

ext Simon McVittie wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> OK, here's an API sketch. Currently missing are:
> * Account status! (next on my list)
> * Server capabilities
> * Change notification in presets (though we might not actually need that)
> and I'm wondering whether "everything is a profile" might actually
> simplify things, if we mandated that only MC would ever read .profile
> files and everyone else would always ask MC.

The methods of the AccountManager are also missing (FindAccounts, 
CreateAccount,...).

[...]
> org.freedesktop.Telepathy.AccountManager.Interface.Conditions
> =============================================================
> 
> Requires: org.freedesktop.Telepathy.AccountManager
> 
> This interface models the ability to connect to each account using a list of
> conditions. If all the conditions for an account with the auto-connect option
> set are satisfied, the account manager SHOULD connect that account.
> 
> If the conditions for an account become unsatisfied, the account manager
> SHOULD NOT disconnect it immediately, but MAY disconnect it after a
> reasonable delay.
> 
> Account manager implementations SHOULD have this interface.

Another thing you might want to specify is that if the conditions are 
not met the account connection won't even be attempted, even if a 
presence has been explicitly requested by the user.

> Simple types
> - ------------
> 
> Account_Condition: s
>   A condition that might be required for an account to be available.
>   These may be any UTF-8 string, but they SHOULD be short strings of ASCII
>   letters, digits, hyphen/minus characters and dots, starting with a letter
>   or digit.
> 
>   All conditions not containing a dot are reserved for the Telepathy
>   specification. Third-party conditions SHOULD be namespaced by a reversed
>   domain name, e.g. "com.example.vpn-enabled.head-office".
> 
>   The following well-known conditions are currently valid:
> 
>   ip-default-route
>     Either ipv4-default-route or ipv6-default-route is satisfied
>     (server-based connection managers which can use both IPv4 and IPv6 SHOULD
>     require this)
> 
>   ipv4-default-route
>     We have an IPv4 default route (i.e. are on a network, and possibly the
>     Internet)
>     (server-based connection managers which can only use IPv4 SHOULD
>     require this)
> 
>   ipv6-default-route
>     We have an IPv6 default route (i.e. are on a network, and possibly the
>     Internet)
>     (server-based connection managers which can only use IPv6, if such things
>     ever exist, SHOULD require this)

Though these AccountConditions are quite simple and indeed have their 
benefits, I would still prefer to see them in a "name":value form.
That's because it makes more sense for the connectivity plugins to emit 
signals whose arguments are dictionaries with meaningful data, such as
{
   "conn_type": "IP",
   "ip-addess": "192.168.1.3",
   "netmask": "255.255.255.0",
   "default-gw": "192.168.1.1",
   "AP-name": "Home",
}

so that the account conditions can make fully use of the information as 
it comes from the connectivity. Being that the values are variants, we 
would be free to introduce some special values: for instance we could 
allow a condition value them to be either a single value to be matched, 
or a list of values (can a DBus variant be an array?), or some wildcard 
to mean that we don't care about the value, as long as it's set.
An example of a condition could be this:

{
   "default-gw": "*",  # or just empty string
   "AP-name": ["Home", "Grandpa"],
}

I don't think this would sensibly increase complexity, while it brings 
to a lot of flexibility.

> Methods
> - -------
> 
> GetAutomaticConditions () -> as (Account_Condition[]): Automatic
>   Get a list of those account conditions that the Account Manager will
>   automatically detect. Clients do not need to call UpdateAccountConditions
>   for these, and the Account Manager MAY ignore attempts to update them.
> 
> UpdateAccountConditions (as (Account_Condition[]): Added,
>                          as (Account_Condition[]): Removed)
>   Tell the account manager that the account conditions in the set Added
>   are now met (accounts with those requirements may now attempt to connect),
>   and the account conditions in the set Removed are no longer met.
> 
>   If clients attempt to change automatic account conditions (as returned by
>   GetAutomaticConditions), the Account Manager MUST NOT raise an error, and
>   MUST change any non-automatic account conditions that are
>   changed at the same time, but it MAY ignore the attempt to change the
>   automatic account conditions.
> 
> GetAccountConditions () -> as (Account_Condition[]): Satisfied
>   Get a list of account conditions that are currently satisfied (accounts
>   whose requirements are all contained in the returned list may attempt
>   to connect).

I see your point. Maybe one should put a strong distinction between 
connectivity conditions and arbitrary client conditions. It makes sense 
for client conditions to be simple strings.
Connectivity conditions are a bit more tricky. BTW, I always forgot to 
mention that connectivity information provided by connectivity plugins 
could also affect the account parameters: for instance, the SIP CM 
accepts a "local-ip-address" parameter. We could make it so that if the 
connectivity parameter's name matches a protocol parameter, then it's 
passed to the CM. Slightly hackish, but cannot think of anything better ATM.

About your proposed methods, I'd remove GetAutomaticConditions() but 
leave the other two for arbitrary client conditions.

[...]
> org.freedesktop.Telepathy.AccountManager.Preset
> ===============================================
[...]
> (Rationale for having this on D-Bus: this interface makes localization
> transparent, avoids an explicit choice of file format, allows the account
> manager to synthesize presets automatically if required, and allows the
> account manager to implement change-notification for presets in future.)

I think we want to have an explicit choice of the file format, as we 
want it for the CMs, so that people know how to create them.
I don't see any advantage of having the presets exposed on DBus, but I 
don't mind it either -- I would make it an optional interface, though.
Anyway, if we want to expose the presets on DBus, we also need a method 
to list them.

[...]
> Capability pre-seeding? Other things that Profiles could have in the Nokia MC?

Yes, capabilities would be useful.

> Change notification for properties, parameters?

Seems to me unnecessary coolness.

> Should MC support arbitrary (namespaced) key/value attributes, which it
> doesn't understand but can just pass through?

Yes. Sticking to .desktop-style files, I'd allow them to have arbitrary 
[sections].

> Simple Types
> - ------------
> 
> Preset_Name: s
>   A non-empty string of ASCII letters, digits and underscores, starting with
>   a letter. In particular, "_" is not a valid preset name.
> 
>   (FIXME: or we could explicitly allow "_", and reserve it for vanilla
>   profiles)
> 
> Locale: s
>   lang[_COUNTRY][.ENCODING][@MODIFIER], or ""/"C"/"POSIX" (all equivalent)

I don't understand the meaning of the "Locale" type.

[...]
> org.freedesktop.Telepathy.Account
> =================================
[...]
> DesiredStatus: (uss), read/write
>   A struct (Connection_Presence_Type, CM-specific presence status, message)
>   indicating what status we'll want if we put this account online.
>   As a special case, hidden indicates "hidden if possible, else busy",
>   while offline indicates "hidden if possible, else offline".

Mmm... what is Connection_Presence_type?

BTW, I see that you moved most of the data into properties. Seems fine 
to me, but I have never used them and I'd like to be assured that they 
also emit signals when their value changes, and that these signals carry 
the new value (I couldn't find any mention to property signals in the 
DBus specs).

Ciao,
   Alberto

-- 
http://www.mardy.it <-- Geek in un lingua international!