[Bug 26866] add support for requesting handles for a vCard field or URI

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=26866

Simon McVittie <simon.mcvittie at collabora.co.uk> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Blocks|29797                       |

--- Comment #17 from Simon McVittie <simon.mcvittie at collabora.co.uk> 2010-08-25 05:56:13 PDT ---
Shape of the API
================

I think it would be useful to introduce a Connection.Interface.Addressing or
something (which should explicitly require Contacts!), and put this
functionality on it. Perhaps Addressing should be flattened into Connection in
Telepathy 1.0, but we're not there yet.

There are two things we can do with a contact identified by a vCard field:

* you may get a handle (and bonus extra contact attributes) for any field
mentioned in the fixed properties of any channel class

* you may request a channel according to the channel classes in the usual way

I think we should relax the first to "you may get a handle for any field in the
Protocol.AddressableWhatever", which would avoid the strange interaction with
requestable channel classes altogether. It would also be reasonable to say that
any CM that implements Addressing should also implement Protocol (if only
because Protocol is rather easy to implement).

Concrete example: telepathy-sofiasip supports sip, sips and tel URIs (and x-sip
and tel vCard fields). tel URIs may or may not actually work, depending whether
our server has an attached PSTN gateway (tp-sofiasip just passes them on).

If we imagine that our server has some way to tell us its capabilities, we
could reasonably exclude the telephony-related requestable channel classes on
servers that lack PSTN connectivity, but there seems no reason not to let
people request handles for such identifiers? The handle will represent a string
like tel:123456, which is a perfectly valid thing to talk about, even if our
particular connection has no way to communicate with it. All the contact
attributes will have dummy/unknown values, but that's not harmful.

RequestContactsByVCardField should be named with Get: "RequestThing" has a
network round-trip before completing, whereas "GetThing" returns whatever
cached values are available.

> +          <p>Attributes from the interface
> +            <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref>
> +            and
> +            <tp:dbus-ref>org.freedesktop.Telepathy.Connection.Interface.ContactInfo</tp:dbus-ref>
> +            are always returned, and need not be requested
> +            explicitly.</p>

I can see what you're trying to do here, but I don't think it's appropriate.
ContactInfo is information that the contact *claims* is true, but the
interpretation of the contact's identifier as a vCard field is unarguably true,
can be parsed by the CM without any networking, and can't change.

I think it'd be better to have Addressing implicitly-requested, and have an
attribute on Addressing that gives the interpretation of the contact's
identifier in terms of vCard fields. However, that itself opens a can of worms,
because there can be more than one interpretation, so we'd have to have
something like this (for the JID smcv at example.com):

Addressing/representations = (
    ["x-jabber": "smcv at example.com"],
    ["url": "xmpp:smcv at example.com"],
    )

A subtlety is that if the contact identifier wasn't given in a normalized form,
the requester needs some way to relate it back to what they asked for, which
you don't provide here. Perhaps if I asked for the x-jabber contact
smcv at EXAMPLE.COM, I should get back:

Addressing/representations = (
    ["x-jabber": "smcv at example.com"],
    ["url": "xmpp:smcv at example.com"],
    )
Addressing/before-normalizing = (
    ["x-jabber": "smcv at EXAMPLE.COM"],
    )

For the second case, requesting channels, we should just advocate setting the
TargetVCardField and TargetVCardAddress directly.

> The one issue I see is the addition of Protocol.AddressableURISchemes being
> partial: It has no change notification, and it does not have a
> channel property to make it useful with RCC. So we are left with the
> URI scheme support being static and not discoverable when online.

There's nothing to stop you using Protocol for an online connection;
TpConnection can grow convenience API for this if needed. I see your point
about it being a static superset, though.

Perhaps we should special-case "url" in TargetVCardField, or maybe even in
AddressableVCardFields too (which would remove the need for
AddressableURISchemes), so you set (TargetVCardField, TargetVCardAddress) to
either ("url:xmpp", "xmpp:smcv at example.com") or ("url:xmpp",
"smcv at example.com")?

(If we go for the former, duplicative, form, telepathy-glib's channel manager
code could enforce it if desired. If we go for the latter form, then
hierarchical URI schemes would look pretty weird: ("url:http",
"//people.collabora.co.uk/~smcv/") :-)

Details
=======

> +AddressableVCardFields=x-example;tel;email;sip
...
> +AddressableURISchemes=tel;sip

All non-empty lists in .desktop format should have a trailing semicolon, so end
both of these with "...;sip;".

A more illustrative value might be:

    AddressableVCardFields=x-sip;tel;email;
    AddressableURISchemes=sip;sips;tel;mailto;

(X-SIP is the de facto standard vCard field for SIP, as used on the N900. SIP
and e-mail provide a useful example, because their vCard field names are not
the same as their URI schemes!)

> -          <p>It is not necessarily valid to interpret contacts' identifiers
> -            as values of this vCard field. For instance, telepathy-sofiasip
> -            supports contacts whose identifiers are of the form
> -            sip:jenny at example.com or tel:8675309, which would not normally
> -            both be represented by any single vCard field.

I don't think this note should be removed: it corrects a possible
misinterpretation. Perhaps this should be promoted out of rationale into the
main text, since it's more clarification than rationale.

> +          normalized to lower case (for example: tel, x-jabber).</p>

I'd prefer examples to be realistic, appear in pseudo-(Python|JSON) syntax, and
explain what they mean:

    For example, a SIP connection manager that can also interact with the
    PSTN might set this to ["x-sip", "tel"].

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.