Bug 13350

In progress. A draft was released in 0.17.18.

Hmm. I just discussed some issues with this spec with Marco and Sjoerd, and discovered an unmerged branch from the last time I discussed this with Marco. The spec branch is at <http://git.collabora.co.uk/?p=user/wjt/telepathy-spec-wjt.git;a=shortlog;h=refs/heads/contact-info-network-traffic> and HTML is at <http://people.freedesktop.org/~wjt/telepathy-spec-contact_info_network_traffic/spec/org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT.html>.

The current draft says that GetContactInfo() should pull stuff from the network if it doesn't have it cached locally. This makes it unsafe to call all the time on (say) XMPP.

Marco noted that if the address book (say) isn't running when you get connected, and you receive a bunch of vCards as a result of (say) the contact list getting people's avatars, the address book will miss all the Changed signals. But under the current draft, it can't safely call GetContactInfo() to get the cached stuff, because that'll make Gabble poke the network. So there's stuff which is in Gabble's in-memory cache (which as an implementation detail lasts about 20 seconds IIRC) which UIs can't get at safely.

The attached branch removes the requirement that GetContactInfo() cause network traffic for contacts whose vCards we don't have. The rationale is that it simplifies use of the interface:

• Always call GetContactInfo() for the contacts you care about;
• If Push is not set, call RequestContactInfo() to forcibly update your contacts' address book entries every few days/weeks/etc.

Also, Gabble could potentially cache vCards for longer/on disk.

Sjoerd also suggested adding tokens to ContactInfo, akin to avatar tokens. This would allow the CM to cache them forever without its memory usage expanding out of control. Also, a similar issue exists with clients being able to miss transient information exists on the EmailNotification interface; we could use a general solution.

(In reply to comment #2)
> Hmm. I just discussed some issues with this spec with Marco and Sjoerd, and
> discovered an unmerged branch from the last time I discussed this with Marco.
> The spec branch is at
> <http://git.collabora.co.uk/?p=user/wjt/telepathy-spec-wjt.git;a=shortlog;h=refs/heads/contact-info-network-traffic>

Looks good, except:

+        info to be updated, but MUST NOT do so without direct user action or to
+        refresh its own cache after a number of days.</p>

Do you mean that clients may refresh their caches automatically after a number of days, or that this is forbidden? The current text reads as though it's forbidden. Assuming you want to allow cache refreshes, how about this?

"... but MUST NOT do so unless this is either in response to direct user action, or to refresh its own cache after a number of days"

> Sjoerd also suggested adding tokens to ContactInfo, akin to avatar tokens. This
> would allow the CM to cache them forever without its memory usage expanding out
> of control. Also, a similar issue exists with clients being able to miss
> transient information exists on the EmailNotification interface; we could use a
> general solution.

How would tokens help, assuming a protocol like XMPP where we don't have protocol-level tokens?

Additional changes:

Marco has requested that the network-traffic-provoking part of GetContactInfo is replaced by something like a fire-and-forget RefreshContactInfo(au: Contacts) -> void, which polls all of those contacts' info and emits ContactInfoChanged signals. This seems easy to do.

Based on implementation experience in Gabble, I'd also like to suggest:

* SupportedFields and ContactInfoFlags should have the same semantics as SupportedAvatarMIMETypes and friends: they can change without notice during the Connection's early lifetime, but must be "frozen" by the time the Connection moves to CONNECTED state. (Rationale: Gabble can realise we're connected to a Google server, and omit most of its supported vCard fields; or it can realise we're connected to Facebook, and clear the Can_Set flag entirely)

* For interop, it would be nice to have a more elaborate example of ORG: perhaps the Wee Ninja should have "ORG:Collabora, Ltd.;Management Division;Human Resources\; Company Policy Enforcement" or something, to demonstrate nested org.units)

* Similarly, we should include LABEL (preformatted address) in the list of well-known vCard fields, and give the Wee Ninja's address label (see the Gabble regression tests for details)

(In reply to comment #3)
> * SupportedFields and ContactInfoFlags should have the same semantics as
> SupportedAvatarMIMETypes and friends: they can change without notice during the
> Connection's early lifetime, but must be "frozen" by the time the Connection
> moves to CONNECTED state.

I implemented this in Gabble.

> Based on implementation experience in Gabble, I'd also like to suggest:

The Contact_Info_Flag type should be called Contact_Info_Flags, with Contact_Info_Flag as its member prefix.

Contact_Info_Field_Flag_Parameters_Mandatory is a cumbersome name, and if you're not paying attention, the mention of "mandatory" makes it look as though the *field* is mandatory. Perhaps we could rename it to Contact_Info_Field_Flag_Params_Exact?

(In reply to comment #4)
> The Contact_Info_Flag type should be called Contact_Info_Flags, with
> Contact_Info_Flag as its member prefix.

Done in smcv/contact-info; this required some slight alterations to wording

> Contact_Info_Field_Flag_Parameters_Mandatory is a cumbersome name, and if
> you're not paying attention, the mention of "mandatory" makes it look as though
> the *field* is mandatory. Perhaps we could rename it to
> Contact_Info_Field_Flag_Params_Exact?

Done in smcv/contact-info

(In reply to comment #3)
> Looks good, except: [...]

Fixed in smcv/contact-info

> Marco has requested that the network-traffic-provoking part of GetContactInfo
> is replaced by something like a fire-and-forget RefreshContactInfo(au:
> Contacts) -> void, which polls all of those contacts' info and emits
> ContactInfoChanged signals. This seems easy to do.

Done in smcv/contact-info, but I haven't implemented this in Gabble yet (I'd like to get the initial implementation merged first)

> * SupportedFields and ContactInfoFlags should have the same semantics as
> SupportedAvatarMIMETypes and friends

Done in smcv/contact-info

> * For interop, it would be nice to have a more elaborate example of ORG:
> perhaps the Wee Ninja should have "ORG:Collabora, Ltd.;Management
> Division;Human Resources\; Company Policy Enforcement" or something, to
> demonstrate nested org.units)

Done in smcv/contact-info

> * Similarly, we should include LABEL (preformatted address) in the list of
> well-known vCard fields, and give the Wee Ninja's address label

Done in smcv/contact-info

Approved in principle by wjt, needs review in detail later

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

Approved with 1 minor change found here http://git.collabora.co.uk/?p=user/andrunko/telepathy-spec.git;a=shortlog;h=refs/heads/contact-info

I am finishing implementing the changes in gabble to make sure everything works.

> Renamed all occurrence of Params in ContactInfo to Parameters to follow other spec nomenclatures.

As you can see from Comment #4, this change was because the name was too long and unwieldy... I think you're probably right, though.

I think we should specmeet about undrafting this, once you have a Gabble branch that matches your spec branch. Please ping Bug #20831 when your Gabble branch is ready.

(In reply to comment #9)
> once you have a Gabble branch that matches your spec branch

... which is now the case, so this is on the agenda for the next spec meeting.

I'll merge and undraft this soon.

SupportedFields: XEP-0054 doesn't actually support all vCard fields. AP Simon: change the SupportedFields: [] example to refer to a hypothetical protocol which supports all of vCard.

Example is wrong: all the parameters should be 'type=foo' not 'foo'.

Stable API in 0.19.4.