Hey, where'd the branch go?

When discussing the future of ConnectionManager with Rob yesterday, we thought ConnectionManager should have Protocol child objects, with:

* immutable properties for parameters, for this bug
* expected value of RequestableChannelClasses (split into "will be supported" / "might be supported" or something), for Bug #17312
* expected value of Interfaces (split similarly), for Bug #18172
* expected value of SimplePresence.Statuses (split similarly?), so we can tell whether we can/might be able to go invisible
* expected avatar requirements, for Bug #20775
* NormalizeContact(), for offline normalization
* IdentifyAccount(), for Bug #23131

For round-trip reduction, the ConnectionManager should have a property that is a map from the object path of each Protocol object (or the tail of the object path, or something) to a dict of its immutable properties.

I renamed the branch to wip-cm, sorry.

However, here's a better proposal, based on Comment #2:

ConnectionManager
=================

mapping Protocol_Properties_Map
    A map from protocol names to the immutable properties of the
    corresponding Protocol objects. The immutable properties appear
    in fully-qualified form, to allow Protocol to be extended.

    Protocol : s (Protocol)
        The name of a protocol. Its object path may be found by replacing
        hyphen/minus characters with underscores and prepending the
        ConnectionManager object path plus '/', as explained in the Protocol
        interface.

    Properties : a{sv} (Qualified_Property_Value_Map)
        The immutable properties of the corresponding Protocol object

readable property Protocols : a{sa{sv}} (Protocol_Properties_Map)
    A list of the protocols supported by this connection manager, together
    with the immutable properties of the corresponding Protocol objects.

    | Providing the immutable properties here means that in practice, most
    | clients will only need one D-Bus round trip to interrogate the
    | ConnectionManager about all its protocols.

deprecate ListProtocols in favour of Protocols
deprecate GetParameters in favour of Protocols

Protocol
========

An object representing a protocol for which this #ConnectionManager can
create #Connections.

Each Protocol object has the same well-known bus name as its parent
#ConnectionManager. Its object path is formed by taking the
#ConnectionManager's object path and appending '/', followed by the
protocol name with any hyphen/minus '-' converted to underscores '_'.

| This is the same as the representation of protocol names in Account object
| paths, and in Connection object paths and bus names. For instance,
| telepathy-gabble and telepathy-salut would implement objects at
| /org/freedesktop/Telepathy/ConnectionManager/gabble/jabber and
| /org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp,
| respectively.

readable property Interfaces : as (DBus_Interface[])
    A list of interfaces supported by this Protocol object.

    This property is immutable, and should not be confused with
    @GuaranteedInterfaces and @PossibleInterfaces, which refer to the
    interfaces of *connections* to this protocol.

    | For future expansion.

readable property Parameters : a(susv) (Param_Spec[])
    The parameters which must or may be provided to the @RequestConnection
    method when connecting to the given protocol. This property is immutable.

readable property GuaranteedInterfaces : as (DBus_Interface[])
    A list of interface names which will definitely be in the @Interfaces
    property of any Connection to this protocol.

    This property is immutable, and should not be confused with @Interfaces.

readable property PossibleInterfaces : as (DBus_Interface[])
    A list of interface names which might be in the @Interfaces
    property of a Connection to this protocol, or not, depending on server
    capabilities.

    This property is immutable, and should not be confused with @Interfaces.

readable property GuaranteedChannelClassses : a(a{sv}as)
    A list of channel classes which will be requestable from any Connection
    to this protocol (i.e. they are guaranteed to appear in the Connection's
    @RequestableChannelClasses property). This property is immutable.

readable property PossibleChannelClassses : a(a{sv}as)
    A list of channel classes which might be in the @RequestableChannelClasses
    property of a Connection to this protocol, or not, depending on capability
    discovery. This property is immutable.

method IdentifyAccount (a{sv}: Parameters -> s: Account_ID)
    Return a string which uniquely identifies the account to which the given
    parameters would connect.

    | For many protocols, this would return the well-known 'account'
    | parameter. However, for IRC the returned string would be composed from
    | the 'account' (i.e. nickname) and 'server' parameters. AccountManager
    | implementations can use this to form the account-specific part of an
    | #Account's object path.

    in Parameters : a{sv} (String_Variant_Map)
       A set of parameters as would be provided to RequestConnection

    out Account_ID : s
       An opaque string suitable for use as the account-specific part of
       an #Account's object path. This is not necessarily globally unique,
       but should represent a "best-effort" identification of the account.

       | For a pathological case, consider a user signing in as
       | 'me@example.com' with 'server' set to either jabber1.example.com
       | or jabber2.example.com. Both of these should result in me@example.com
       | being returned from this method, even if the user can actually be
       | signed in to those two servers simultaneously.

method NormalizeContacts (s: Contact_ID) -> s: Normalized_Contact_ID
    Attempt to normalize the given contact ID. Where possible, this SHOULD
    return the same thing that would be returned by
    InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected
    #Connection.

    If full normalization requires network activity or is otherwise impossible
    to do without a #Connection, this method SHOULD perform a best-effort
    normalization.

    [Bikeshedding: should this be plural, signature as -> a{ss}?]

    in Contact_ID : s
        The identifier of a contact in this protocol

    out Normalized_Contact_ID : s
        The identifier of a contact in this protocol, normalized as much
        as possible

[Bikeshedding: perhaps the following should be on a Protocol.Avatars interface]

readable property MinimumAvatarWidth : u
readable property MinimumAvatarHeight : u
readable property RecommendedAvatarWidth : u
readable property RecommendedAvatarHeight : u
readable property MaximumAvatarWidth : u
readable property MaximumAvatarHeight : u
readable property MaximumAvatarBytes : u
    If the @Avatars interface might be supported on connections to this
    protocol, the expected value of the corresponding property in that
    interface; otherwise, 0. This property is immutable.

readable property SupportedAvatarMIMETypes : as
    If the @Avatars interface might be supported on connections to this
    protocol, the expected value of the corresponding property in that
    interface; otherwise, an empty list. This property is immutable.

[Bikeshedding: perhaps the following should be on a Protocol.SimplePresence
interface]

readable property GuaranteedStatuses : a{s(ubb)} (Simple_Status_Spec_Map)
    If a #Connection to this protocol implements SimplePresence, a list of
    statuses which will be available from it (i.e. they are guaranteed to
    appear in the @Statuses property of any connection that supports
    SimplePresence). This property is immutable.

    | In XMPP, 'available' and 'away' would be among these statuses.

readable property PossibleStatuses : a{s(ubb)} (Simple_Status_Spec_Map)
    If a #Connection to this protocol implements SimplePresence, a list of
    statuses which may be available from it, or not (i.e. appear in the
    @Statuses property, or not), depending on capability discovery.
    This property is immutable.

    | In XMPP, 'invisible' would be among these statuses.

A serialization in the .manager file also needs to be defined. Everything's probably quite easy, except for the requestable channel classes which are Hard.

*** Bug 17312 has been marked as a duplicate of this bug. ***

Related to IdentifyAccount(), we should file a bug against Idle to have a CM parameter for 'network-name' (OFTC/Freenode/etc.), which Idle would then use in its IdentifyAccount() implementation and (for ease of debugging) its object paths, and otherwise ignore.

ValidateContacts() could take an 'as' and return an 'a{ss}', omitting anyone whose ID wasn't actually valid; ValidateContact() could take an 's' and return extensible error details? More bikeshedding required.

Other things that should be in here, from Bug #17836: the stuff that's in profiles at the moment:

* preferred/common vCard field for this protocol (e.g. x-jabber for XMPP)
* human-readable protocol name, defined to be in the C locale (UIs can gettext it with their own locale if necessary)
* default protocol icon name, overridable via presets

URI schemes and secondary vCard fields declared to be out of scope, see other bugs.

Untagging, needs more work.

I would also like:

  as: PossibleSidecars
  as: GuaranteedSidecars

Depending on the constraints we want to enforce, TpBaseConnectionManager might be able to synthesize Protocol objects for existing connection managers without the CM being changed. These Protocol objects wouldn't be particularly useful: Parameters would be populated, but Guaranteed*, Possible* would be empty, and  IdentifyAccount and NormalizeContact would both raise NotImplemented.

There are basically two ways we can go:

* Declare that these Protocol objects are legal, and clients have to cope with all the other properties being unpopulated. TpBaseConnectionManager can synthesize and export Protocol objects.

* Declare that these Protocol objects are not allowed, so TpBaseConnectionManager can't export them until CMs fill in the rest of the required information.

I think I prefer the latter, since TpConnectionManager needs a fallback path to ListProtocols/GetParameters anyway (to cope with older telepathy-python CMs).

> [Bikeshedding: perhaps the following should be on a Protocol.Avatars interface]

I think they should.

> [Bikeshedding: perhaps the following should be on a Protocol.SimplePresence
> interface]

I think they should.

(In reply to comment #8)
> I would also like:
> 
>   as: PossibleSidecars
>   as: GuaranteedSidecars

Those should probably be another interface too.

(In reply to comment #4)
> A serialization in the .manager file also needs to be defined. Everything's
> probably quite easy, except for the requestable channel classes which are Hard.

If we forbid RCCs with non-serializable fixed properties, it becomes considerably easier - we can adapt the serialization from .client files.

(In reply to comment #6)
> * preferred/common vCard field for this protocol (e.g. x-jabber for XMPP)

readable property VCardField: s

    The name of the most common vCard field used for this protocol's contact
    identifiers, normalized to lower case, or the empty string if there is
    no such field.

    | For instance, in XMPP this would be "x-jabber", and in telephony it
    | would be "tel".

> * human-readable protocol name, defined to be in the C locale (UIs can gettext
> it with their own locale if necessary)

readable property DisplayName: s

    The name of the protocol in a form suitable for display to users,
    such as "AIM" or "Yahoo!", or the empty string if none is available.

    This is effectively in the C locale (international English);
    user interfaces requiring a localized protocol name SHOULD look
    one up in their own message catalog based on either the Telepathy
    #Protocol name or this property, but SHOULD use this English version
    as a fallback if no translated version can be found.

    | Many protocols are named after a company or product which isn't
    | translated in non-English locales. This also provides a fallback
    | display name, for UIs with no prior knowledge of a particular protocol.

    If this property's value is empty, clients MAY fall back to using
    the Telepathy #Protocol name, possibly with its capitalization adjusted.

> * default protocol icon name, overridable via presets

readable property Icon: s

    The name of an icon in the system's icon theme, such as "im-msn", or
    the empty string.

    | This can be used as a default if the @Icon property is not set on an
    | #Account, or used by the #AccountManager to choose a default icon
    | if none is set during account creation.

    If this property's value is empty, clients MAY fall back to generating
    a name based on the #Protocol name.

http://people.freedesktop.org/~smcv/telepathy-spec-protocols/spec/

http://git.collabora.co.uk/?p=user/smcv/telepathy-spec-smcv.git;a=shortlog;h=refs/heads/protocols

This requires a couple of previous branches, propertify-connection (Bug #26842) and file-formats (for which I'll open a bug).

Errata based on implementation in telepathy-glib:

* In my spec branch, IdentifyAccount can raise NotImplemented. I think it should also be able to raise InvalidArgument.

* My spec branch doesn't implement the ConnectionManager enhancements that cause the round-trip reduction, to avoid doing the .FUTURE dance. They're in Comment #3 here.

Spec meeting notes!

Implementation details:

• the tp-glib implementation involves subclassing TpBaseProtocol. it
  supports CMs like haze which discover their own protocols at
  run-time, as well as CMs that have one or two staticly-determined
  protocols.

IdentifyAccount:

• This makes it possible for MC's account path to be sensible, and be
  the same if you delete and re-create account so that your old logs
  match up.
• Also solves the problem where you can create two accounts for the
  same JID and then can't actually connect them both at once, as Siraj
  mentioned on #telepathy today.
• We could add an "IRC Network" parameter which Idle ignores but uses
  to generate responses to this? This would mean that if you switch
  between two servers on the OFTC network, the account path could
  still be wjt@OFTC or something.

NormalizeContact:

• Needs explanation of why it's best-effort only, with reference to XMPP
  where foo@conference.bar/bong.hits would be normalized to
  foo@conference.bar by this method even though that's wrong.
• Why might it raise NotImplemented? Salut.

Guaranteed vs. Possible {Interfaces,ChannelClasses}:
• Why would you ever care about anything other than the union?
• Should we distinguish between channel classes that every contact will
  have, channel classes that some contacts may have, and channel
  classes that the whole connection might not even have when you sign
  in?
  · Again, what would the UI do differently in each case?
• Possible route: just have one list for each, we can reintroduce
  Guaranteed later if needed.

Agreed that presets such as settings for well-known SIP providers,
Google Talk, Ovi etc. don't live here; they should live outside the CM,
so that you can install extra files to describe (e.g.) your company's
SIP or XMPP service.

VCardField:
  · as a first step, if you have a vCard and it's got an x-jabber field
    and you want to know how you can contact this person, you can just
    go through your protocols and find them.
  · this is stolen directly from MC's profiles as used on Maemo 5, and
    is valuable there.
  · this is not for getting a contact out of a protocol and turning it
    into a vCard field, because a protocol might support several.
    Example: SIP supports tel and sip. this use case is further work.
  · nitpick, explain what "telephony" means, exactly: it's Ye Olde POTS,
    not IP Telephony.

DisplayName:
  · This is a really overloaded name; can we call it EnglishName?

Icon:
  · "system's icon theme" is a bit of a cop-out. can we say xdg icon
    spec names?

Protocol.Interface.Presence:
  · Maybe guaranteed vs. possible makes sense here?
  · Counter-argument: what's the UI meant to do if you say "you might
    be able to be invisible? i don't really know?"
  · Will reckons we should just make Gabble support invisible
    everywhere which removes the one case where possible ≠ guaranteed

Sidecars we'll ignore for now; the rest seems fine.

Updated branch:

smcv/protocols in git
http://people.freedesktop.org/~smcv/telepathy-spec-protocols/spec/
http://git.collabora.co.uk/?p=user/smcv/telepathy-spec-smcv.git;a=shortlog;h=refs/heads/protocols

It has been rebased to get rid of Sidecars: the last commit that has been reviewed is "fd.o #17836: Protocol: add VCardField, DisplayName and Icon".

(In reply to comment #12)
> IdentifyAccount:
> 
> • This makes it possible for MC's account path to be sensible, and be
>   the same if you delete and re-create account so that your old logs
>   match up.
> • Also solves the problem where you can create two accounts for the
>   same JID and then can't actually connect them both at once, as Siraj
>   mentioned on #telepathy today.
> • We could add an "IRC Network" parameter which Idle ignores but uses
>   to generate responses to this? This would mean that if you switch
>   between two servers on the OFTC network, the account path could
>   still be wjt@OFTC or something.

No action taken.

> NormalizeContact:
> • Needs explanation of why it's best-effort only

Done

> • Why might it raise NotImplemented? Salut.

Done

> Guaranteed vs. Possible {Interfaces,ChannelClasses}:
> • Why would you ever care about anything other than the union?

Flattened into ConnectionInterfaces and RequestableChannelClasses.

> • Should we distinguish between channel classes that every contact will
>   have, channel classes that some contacts may have, and channel
>   classes that the whole connection might not even have when you sign
>   in?
>   · Again, what would the UI do differently in each case?

Tentative resolution: no, we shouldn't.

> • Possible route: just have one list for each, we can reintroduce
>   Guaranteed later if needed.

Done.

> Agreed that presets such as settings for well-known SIP providers,
> Google Talk, Ovi etc. don't live here; they should live outside the CM,
> so that you can install extra files to describe (e.g.) your company's
> SIP or XMPP service.

No action taken.

> VCardField:
>   · as a first step, if you have a vCard and it's got an x-jabber field
>     and you want to know how you can contact this person, you can just
>     go through your protocols and find them.
>   · this is stolen directly from MC's profiles as used on Maemo 5, and
>     is valuable there.

Documented.

>   · this is not for getting a contact out of a protocol and turning it
>     into a vCard field, because a protocol might support several.
>     Example: SIP supports tel and sip. this use case is further work.

Documented.

>   · nitpick, explain what "telephony" means, exactly: it's Ye Olde POTS,
>     not IP Telephony.

Done (I called it "the PSTN", consistent with "tel" in the Protocol tp:simple-type).

> DisplayName:
>   · This is a really overloaded name; can we call it EnglishName?

Done.

> Icon:
>   · "system's icon theme" is a bit of a cop-out. can we say xdg icon
>     spec names?

If <http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html> is still the latest, then no, we can't - they're not there. :-(

No action taken. I copied the wording from Account.Icon.

> Protocol.Interface.Presence:
>   · Maybe guaranteed vs. possible makes sense here?
>   · Counter-argument: what's the UI meant to do if you say "you might
>     be able to be invisible? i don't really know?"
>   · Will reckons we should just make Gabble support invisible
>     everywhere which removes the one case where possible ≠ guaranteed

Flattened into Statuses.

One possible change here is to represent the Connection_Presence_Type by a string rather than an integer (the suffix of the enum value might be a good choice - Available, Extended_Away, Busy etc.).

> Sidecars we'll ignore for now; the rest seems fine.

I rebased the branch to re-order all the sidecars stuff to the end. smcv/protocols now contains everything except sidecars, and smcv/protocol-sidecars contains the sidecar interface.

*** Bug 18172 has been marked as a duplicate of this bug. ***

*** Bug 23131 has been marked as a duplicate of this bug. ***

After reviewing tp-glib impl and implemented support in tp-qt4 there are just 2 things that I don't think really fit here.

IMHO EnglishName and Icon are out of place here, we should probably add them to Profile. UIs can and will probably have localized versions of EnglishName and Icon can easily be parsed by the UI using the protocol name, as im-[protocolname].
But it won't hurt having them here, but I think it is not needed at all.

Does anyone have more to say about this D-Bus API? May I merge it as a draft?

Note that as currently written, this branch adds the following stable API:

* Protocol_Properties_Map is an a{sa{sv}} from protocol name to immutable properties

* ConnectionManager.Protocols is a Protocol_Properties_Map

I hope these are both uncontroversial, even if the precise details of Protocol need to remain in draft, but I could do the ConnectionManager.FUTURE dance if necessary.

(In reply to comment #16)
> After reviewing tp-glib impl and implemented support in tp-qt4 there are just 2
> things that I don't think really fit here.
> 
> IMHO EnglishName and Icon are out of place here, we should probably add them to
> Profile.

They should definitely be in profiles *as well*, but one of the goals of this work was that random connection managers (particularly, connection managers that aren't shipped by OS integrators, like the telepathy-extras on Maemo) should be usable without a profile, and that plugin-based connection managers that randomly grow new protocols (like telepathy-haze) aren't limited by a static set of profiles either.

If your desktop locale isn't English, it still seems better to have English names than (a mangled version of) Telepathy names ("MSN" or "Windows Live Messenger" are both better than "msn" or "Msn", even if you'd really prefer it to be "Windows Live メッセンジャー").

> UIs can and will probably have localized versions of EnglishName and
> Icon can easily be parsed by the UI using the protocol name, as
> im-[protocolname].
> But it won't hurt having them here, but I think it is not needed at all.

If im-foo was part of the Icon Naming spec I'd agree, but they're not, and when they are we'll still need a way to handle any mismatches between Telepathy and Icon Naming (e.g. Telepathy's 'jabber' should really be 'im-xmpp').

TpProtocol and TpAccount both fall back to im-$protocol if Icon is the empty string, and I'd suggest that telepathy-qt4 should do the same if it doesn't already.

Said so, I vote for merging it as a DRAFT.

AFAICT this was merged a while back.

I don't really have any opposition to undrafting this as it currently stands — I think the information it provides is useful and uncontroversial, and it's been implemented on both sides of the client/CM divide.

My only vague query is: would it matter if the format used for the replacement for profiles (bug 24897) were different? It's been suggested that XML would be a better choice—not least to more easily support nesting of data—and it might be a bit strange to use two different formats.

But of course the .manager files defining supported protocols are already keyfiles, and it'd be stupid to have two files defining different aspects of the protocols. So this is not really a real opposition.

Merged in 0.19.10.