"Protocol" here refers to the Protocol objects introduced by Bug #20774.

(In reply to comment #0)
> * From a URI: 'xmpp:bob@example.com/Work' -> bob@example.com in
> telepathy-gabble

Note that you might also want to support URIs such as 'xmpp:smcv@example.com?subscribe' or, more troublingly, 'aim:goaway?message=bonghits+in+the+hood'.

Yeah, those URIs are more troublesome. My thought was that initially, we'd just support URIs as nouns (the way the architecture of the Web claims they should be used) mapping to contacts.

If we want to support URIs (mis)used as verbs as well, we'd need to add a separate ActOnURI(s: URI) option that did "something appropriate".

However, I think URIs as verbs are likely to need rather more UI than the CM can offer on its own, and contain additional cans of worms that I don't want blocking the simpler feature. URIs for many (all?) actions shouldn't actually perform the action, they should just open up appropriate UI to prepare to do it (e.g. fill in the message as a draft, or whatever, so the user just has to press Send to confirm).

Thanks, the sketch API is pretty much what I had in mind. Maybe there could be also bulk resolution methods like:
method RequestHandlesByAddress(s: Field, as: Addresses) -> au: Contact_Handles

Tangential to addresses-as-verbs, it would be interesting to support features like dialstrings, e.g. "1234455p56657#1434#", meaning call a number and after connecting, dial some extra numbers with DTMF. But on the other hand, it probably makes more sense to handle it in the call client, rather than implementing a DTMF jukebox in all connection managers.

There could be a property defining a primary vCard field for the connection, so that clients are advised to use this in persistent contact storage, rather than the contact ID. This can resolve problems like the recent one with Facebook XMPP chat, when Facebook has changed the mapping from Facebook user ID to XMPP JID, so everybody using Facebook chat through telepathy-gabble got their contacts duplicated.

Thinking about filtering accounts by RequestableChannelClasses (or whatever the version you get when not connected is called) has made me think: I think we (also?) want a requestable property on calls, so you can say something like:

EnsureChannel(
  { ChannelType: Call,
    TargetAddress: ('TEL', '+441234567890'),
  });

rather than having to faff around getting a handle before you can place the call.

But if we want to support showing this in RCC, then it'll have to be

    TargetAddressField: 'TEL',
    TargetAddress: '+441234567890',

because then there can be an RCC with TAF set to TEL, and clients can reasonably easily look this up.

(In reply to comment #6)
> EnsureChannel(
>   { ChannelType: Call,
>     TargetAddress: ('TEL', '+441234567890'),
>   });
> 
> rather than having to faff around getting a handle before you can place the
> call.
> 
> But if we want to support showing this in RCC, then it'll have to be
> 
>     TargetAddressField: 'TEL',
>     TargetAddress: '+441234567890',
> 
> because then there can be an RCC with TAF set to TEL, and clients can
> reasonably easily look this up.

I'm all for that. Indeed, resolving handles and requesting channels are two distinct cases, and the latter implies the former and uses the same implementation. Everybody wins.

So, if we add something like:

  Protocol.AddressableVCardFields: as
  Connection.RequestHandlesByVCardField(s: Field, as: Values) → au: Handles
  Channel.TargetVCardField: s

Then for connections that are offline you can look at the Protocol to determine what types of contact they support addressing; for those that are online, you can either still use that, or for a better idea look in RequestableChannelClasses. I think this means we don't need an equivalent of AddressableVCardFields on the Connection (for cases like XMPP where, in general, we only support X-JABBER, but when we connect it might turn out that our server has a SIP or POTS gateway).

So we want some way to store what we have discovered. But we also need a way for the user to configure it, as mentioned in bug 24898. I'll take some thoughts on that over there.

These are all the additions I got so far. 

Protocol.AddressableVCardFields: as
Used when offline to determine the what vCard fields we could use to request handles/channels.

Connection.RequestHandlesByVCardField(s: Field, as: Values) → au: Handles
Used for getting a handle with a vCard field.

Channel.TargetVCardField: s
Channel.TargetVCardAddress: s
Immutable properties.

Conn.I.Requests.RequestableChannelClasses
TargetVCardField could appear as a fixed property (with a value, like "TEL"), and TargetVCardAddress could appear as an allowed property. This is for determining capabilities when online. It also affects Connection.RequestHandlesByVCardField which is kind of weird, but not completely irrational.

(In reply to comment #8)
> So, if we add something like:
> 
>   Protocol.AddressableVCardFields: as
>   Connection.RequestHandlesByVCardField(s: Field, as: Values) → au: Handles
>   Channel.TargetVCardField: s
> 
> Then for connections that are offline you can look at the Protocol to determine
> what types of contact they support addressing; for those that are online, you
> can either still use that, or for a better idea look in
> RequestableChannelClasses. I think this means we don't need an equivalent of
> AddressableVCardFields on the Connection (for cases like XMPP where, in
> general, we only support X-JABBER, but when we connect it might turn out that
> our server has a SIP or POTS gateway).
> 
> So we want some way to store what we have discovered. But we also need a way
> for the user to configure it, as mentioned in bug 24898. I'll take some
> thoughts on that over there.

Do we need to duplicate it all for URI? I'm thinking maybe URIs could work like vCards, splitting the scheme and "host" part, and we would remove "VCard" from the names above.

I think the real power in URIs are in their query strings (subscribe, message, etc.). So maybe the "noun" URIs should use the same API as vCard, and then there would be a Connection method HandleURI or something that would execute a URI with a query string.

For example:
HandleURI("xmpp:romeo@montague.net?message;body=Hello%20World")
would be the equivalent of Conn.I.EnsureChannel and Chan.T.Text.Send.

(In reply to comment #9)
> These are all the additions I got so far. 
> 

I meant to ask, am I missing something?

(In reply to comment #10)
> Do we need to duplicate it all for URI? I'm thinking maybe URIs could work like
> vCards, splitting the scheme and "host" part, and we would remove "VCard" from
> the names above.
> 
> I think the real power in URIs are in their query strings (subscribe, message,
> etc.). So maybe the "noun" URIs should use the same API as vCard, and then
> there would be a Connection method HandleURI or something that would execute a
> URI with a query string.
> 
> For example:
> HandleURI("xmpp:romeo@montague.net?message;body=Hello%20World")
> would be the equivalent of Conn.I.EnsureChannel and Chan.T.Text.Send.

And there would need to be a way for a CM to advertise supported schemes. We will assume that if a scheme is supported, it could handle basic+ query strings. If not then HandleURI would raise an InvalidArgument exception.

(In reply to comment #10)
> Do we need to duplicate it all for URI? I'm thinking maybe URIs could work like
> vCards, splitting the scheme and "host" part, and we would remove "VCard" from
> the names above.

I don't think there is an identity between standard vCard field names and URI schemes.

> I think the real power in URIs are in their query strings (subscribe, message,
> etc.). So maybe the "noun" URIs should use the same API as vCard, and then
> there would be a Connection method HandleURI or something that would execute a
> URI with a query string.
> 
> For example:
> HandleURI("xmpp:romeo@montague.net?message;body=Hello%20World")
> would be the equivalent of Conn.I.EnsureChannel and Chan.T.Text.Send.

I think it's a good idea.

I think RequestHandlesByVCardField should probably be RequestContactsByVCardField (rationale: doesn't work for rooms), and either return a dict of (held handle, identifier) pairs, or even have GetContactAttributes-like behaviour.

(In reply to comment #13)
> I don't think there is an identity between standard vCard field names and URI
> schemes.

Indeed, there is not an identity. The URL vCard field can hold any URI, though, so in principle we could additionally add:

Protocol.AddressableURISchemes: as
    In addition to the AddressableVCardFields, the "url" vCard field is
    also addressable, if the URI scheme (the part before the ":")
    is in this list.

    For instance, if this is ["sip", "tel"], then you can call
    Connection.RequestHandlesByVCardField("url",
        ["sip:12345@example.com", "tel:+441223362967"])
    and expect it to work, but
    Connection.RequestHandlesByVCardField("url", ["xmpp:bob@example.com"])
    will not work.

I don't think "url" is useful without qualifying it by schemes in any case, so this seems harmless and useful.

> > I think the real power in URIs are in their query strings (subscribe, message,
> > etc.). So maybe the "noun" URIs should use the same API as vCard, and then
> > there would be a Connection method HandleURI or something that would execute a
> > URI with a query string.

In the web architecture, URIs are meant to be noun phrases ("Simon's e-mail address", "Simon's XMPP account"), not verb phrases ("send Simon an e-mail") - see <http://labs.apache.org/webarch/uri/rfc/rfc3986.html#identification>. mailto: URIs are mis-named for historical reasons: given a mailto: URI for my e-mail address, it's just as valid to add me to your address book as it is to send me e-mail right now.

Many URI schemes extend this with parameters that can turn it into a verb, but like you say, RequestHandlesByVCardField should be for the more generic use, i.e. it should ignore those parameters.

> > For example:
> > HandleURI("xmpp:romeo@montague.net?message;body=Hello%20World")
> > would be the equivalent of Conn.I.EnsureChannel and Chan.T.Text.Send.
> 
> I think it's a good idea.

Can we spin this off into a separate bug with lower priority? This seems likely to get much more complicated; I can see several issues straight away.

I'm not at all sure that the Connection is the right place to parse these verb-like URIs. If you're passing one to a Connection, you've already decided which Account it will act on, which is a non-trivial decision, and you've already put that Account online, which is also a non-trivial decision.

We need to be a bit careful about who handles the channel, if there is one. Perhaps it would be reasonable to say that acting on verb-like URIs is always "ensure and forget" (the default handler is invoked, and the caller is only told that it succeeded), and if you want to go beyond that you'll have to parse it yourself.

I don't think it's appropriate for clicking on a URI in a browser to take an irrevocable action (e.g. send messages). On the web there's an expectation that links to URIs will be GET-like, rather than POST-like. For the XMPP ?message parameter I think the functionality we actually want is "open a text chat, put the given message in the edit box ready to send, *but don't send it*" (analogous to a GET http link that takes you to a pre-composed draft webmail message). We don't currently have a way for a CM to do that (but wjt has proposed a way for a cooperating channel-request and Handler to do that, which I think may be more appropriate anyway).

(In reply to comment #14)
> Can we spin this off into a separate bug with lower priority?

Definitely.

Ok, first draft:

http://git.collabora.co.uk/?p=user/eitan/telepathy-spec.git;a=shortlog;h=refs/heads/vcard-field-requests

http://people.freedesktop.org/~eitani/telepathy-spec-vcard_field_requests/spec/index.html

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.

We could add a channel property in the form of TargetURIScheme, but channel requests would have this awkward form:

EnsureChannel(
  { ChannelType: Text,
    TargetVCardField: 'uri',
    TargetVCardAddress: 'xmpp:foo@bar.com',
    TargetURIScheme: 'xmpp'
  });

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@example.com):

Addressing/representations = (
    ["x-jabber": "smcv@example.com"],
    ["url": "xmpp:smcv@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@EXAMPLE.COM, I should get back:

Addressing/representations = (
    ["x-jabber": "smcv@example.com"],
    ["url": "xmpp:smcv@example.com"],
    )
Addressing/before-normalizing = (
    ["x-jabber": "smcv@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@example.com") or ("url:xmpp", "smcv@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@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"].

grr bugzilla and its mid-air collisions

There is an interesting corner case: service URNs from RFC 5031, and URN identifiers in general.
Can we simply treat "urn:service", or any other URN prefix for that matter, as an URI scheme?

(In reply to comment #17)
> 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).

In the future, a connection could be configured to translate tel URIs into sip/sips URIs locally, or via an ENUM lookup.

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

What about making ENUM lookups to resolve a tel URI?

(In reply to comment #20)
> What about making ENUM lookups to resolve a tel URI?

What about them, indeed...

How do these work? Is the idea that tel:+44123456789 somehow points (via ENUM) to sip:office@example.com, and then you call office@example.com instead?

One way to represent this would be for RequestHandles("tel:+44123456789"), and similar Addressing calls, to "normalize" to "sip:head-office@example.com", but I think that's only right if the mapping is (semi-)permanent and meant to be user-visible.

(Analogy: on an XMPP server example.com with an MSN transport, we could consider "normalizing" ("x-msn", "example@passport.com") to example%passport.com@msn.example.com. Maybe. I'm not sure whether it'd really be appropriate to do this for transports either, though.)

The other way to represent it would be to have the handle represent the tel URI, and do the ENUM lookup lazily when you actually interact with it (i.e. request a Channel - as an implementation detail, the CM should cache the mapping for a while, perhaps for the duration of the session). This would be correct if the contact being called is conceptually "tel:+44123456789", and the mapping via ENUM is considered to be an implementation detail of how we call it, which I think is probably more appropriate?

(Analogy: we don't normalize example@gmail.com to example@talk.l.google.com or to example@209.85.229.125.)

(In reply to comment #19)
> There is an interesting corner case: service URNs from RFC 5031, and URN
> identifiers in general.
> Can we simply treat "urn:service", or any other URN prefix for that matter, as
> an URI scheme?

It's not a URI scheme (the URI scheme is just "urn"), but we could special-case URNs so we treat the first level of hierarchy as conceptually part of the scheme, if there's a good reason to do so.

I'm not sure that wedging URNs into this structure is necessarily all that helpful, though? If you're aiming to solve the "emergency calls and service URNs" use case, we already have a separate interface for that which I think is probably more appropriate.

(In reply to comment #17)
> 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.
> 

So, let people retrieve meaningless contacts but fail if they try to communicate with them? Sounds reasonable.
Maybe Addressing/representations (see below), is an empty mapping the UI could assume the contact is not reachable.

> 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@example.com):
> 
> Addressing/representations = (
>     ["x-jabber": "smcv@example.com"],
>     ["url": "xmpp:smcv@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@EXAMPLE.COM, I should get back:
> 
> Addressing/representations = (
>     ["x-jabber": "smcv@example.com"],
>     ["url": "xmpp:smcv@example.com"],
>     )
> Addressing/before-normalizing = (
>     ["x-jabber": "smcv@EXAMPLE.COM"],
>     )
> 

Mapping back contacts to the actual request could also be done by their index in the returned list, if we promise the list will be the same length as the requested addresses list. That is obviously not good enough, because the client probably disposed the request list in the meantime.

How about something like this... For example on Gabble (with no PSTN gateway):

Addressing.GetContactsByVCardField("x-jabber", "eitan@EXAMPLE.COM", []) =>
Addressing/representations = {"x-jabber": "eitan@example.com",
                              "url": "xmpp:eitan@example.com"}
Addressing/requested = ("x-jabber", "eitan@EXAMPLE.COM")

And for a TEL request:
Addressing.GetContactsByVCardField("tel", "+12065553232", []) =>
Addressing/representations = []
Addressing/requested = ("tel", "+12065553232")

> 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.
> 

The static superset was my only point.

> 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@example.com") or ("url:xmpp",
> "smcv@example.com")?

I like it.

> 
> (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/") :-)
> 

tp-glib could enforce either, no? Just strip/add scheme. Let's go with the former.

> Details
> =======
> 

I'll get to those, and report back.

(In reply to comment #20)
> What about making ENUM lookups to resolve a tel URI?

It seems like just another resolution step. I guess the question is, if a CM advertises support for the TEL vCard field, are we assuming that it could reach any number on earth? Or could it be that it supports TEL only inside a walled garden (could only reach telephone numbers that successfully resolve with ENUM).

A same question exists with XMPP. If we connect to a service that is not federated with other XMPP services, but advertises support for X-JABBER, how do we deal with a X-JABBER request of a contact it can't reach?

This issue is beyond the scope of this feature, it has probably already been solved somewhere else!

(In reply to comment #21)
> (In reply to comment #20)
> > What about making ENUM lookups to resolve a tel URI?
> 
> What about them, indeed...
> 
> How do these work? Is the idea that tel:+44123456789 somehow points (via ENUM)
> to sip:office@example.com, and then you call office@example.com instead?
> 
> One way to represent this would be for RequestHandles("tel:+44123456789"), and
> similar Addressing calls, to "normalize" to "sip:head-office@example.com", but
> I think that's only right if the mapping is (semi-)permanent and meant to be
> user-visible.

ENUM is built on DNS entries, so the mapping is technically permanent up to its TTL. I could imagine someone making it work dynamically based on registration state or other things, but I don't think it's the primary purpose.

I don't see a problem making the mapping user-visible.

> The other way to represent it would be to have the handle represent the tel
> URI, and do the ENUM lookup lazily when you actually interact with it (i.e.
> request a Channel - as an implementation detail, the CM should cache the
> mapping for a while, perhaps for the duration of the session). This would be
> correct if the contact being called is conceptually "tel:+44123456789", and the
> mapping via ENUM is considered to be an implementation detail of how we call
> it, which I think is probably more appropriate?

Good points. Maybe ResolveContactsByVCardField could be a way to demand a network lookup if applicable, as opposed to more immediate GetContactByVCardField, but with lazy resolution it's not imperative to have it.

If we'd like to expose the actual URI, however, would it be appropriate to create the channel with TargetID/TargetHandle as translated per implicit lookup?

Another question: is it sane for EnsureChannel({ ..., TargetURI: 'tel:+77777777777' }) to have different behavior from EnsureChannel({ TargetID: 'tel:+77777777777'})? The latter is supposed to produce the same result as when the ID is first requested as a handle, and ENUM as part of handle normalization is probably not a good idea.

(In reply to comment #24)
> (In reply to comment #20)
> > What about making ENUM lookups to resolve a tel URI?
> 
> It seems like just another resolution step. I guess the question is, if a CM
> advertises support for the TEL vCard field, are we assuming that it could reach
> any number on earth? Or could it be that it supports TEL only inside a walled
> garden (could only reach telephone numbers that successfully resolve with
> ENUM).

Not really; It's not a problem to have unreachable contacts, and there can be fallback methods in case ENUM fails. I'm interested in where could we work these network roundtrips into the translation from an address to the target handle proper. I don't think it's good to perform during regular handle normalization, but requesting channels by address properties could be such a place. A consistent way to resolve contacts without requesting a channel requires some more thinking. Maybe it's just simpler to have one RequestContactsBy* method style and allow network roundtrips. But then, bulk requesters will cause a lot of traffic.

(In reply to comment #23)
> How about something like this... For example on Gabble (with no PSTN gateway):
> 
> Addressing.GetContactsByVCardField("x-jabber", "eitan@EXAMPLE.COM", []) =>
> Addressing/representations = {"x-jabber": "eitan@example.com",
>                               "url": "xmpp:eitan@example.com"}
> Addressing/requested = ("x-jabber", "eitan@EXAMPLE.COM")
> 
> And for a TEL request:
> Addressing.GetContactsByVCardField("tel", "+12065553232", []) =>
> Addressing/representations = []
> Addressing/requested = ("tel", "+12065553232")
> 

All this has been added in fbaf085

> > 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@example.com") or ("url:xmpp",
> > "smcv@example.com")?
> 
> I like it.
> 

Done. c146214

> > 
> > (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/") :-)
> > 
> 
> tp-glib could enforce either, no? Just strip/add scheme. Let's go with the
> former.

c146214

(In reply to comment #17)
> 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!)

8feacef

> 
> > -          <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@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.

8948dcb

> 
> > +          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"].

c146214

With the ENUM resolution issues aside (not clear what additions are necessary, ResolveContactsByVCardField should be added, even if we assume resolution is always lazy?).

These changes are ready for another round of review.
http://people.freedesktop.org/~eitani/telepathy-spec-vcard_field_requests/spec/index.html

    <tp:contact-attribute name="representations" type="a{ss}"
                          tp:type="Representations_Map">
      <tp:docstring>
        The various vCard and URI addresses that identify this contact.
      </tp:docstring>
    </tp:contact-attribute>

I think it's better to have another attribute for URI representations, rather than (in addition to?) distinguishing them by the special "url:" namespace (which may be a misnomer, as URLs are a subset of URIs). A client should not be forced to filter maps if it is only interested in URI representations. Also, with my pet case of using URNs, "url:urn" will look ugly and confusing.

    <tp:contact-attribute name="requested" type="s">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The contact's address, as it was requested
        through <tp:member-ref>GetContactsByVCardField</tp:member-ref>.</p>
      </tp:docstring>
    </tp:contact-attribute>

Should the vCard field name be also represented?

(In reply to comment #17)
> > +          <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.

I agree. Getting any meaningful contact info attributes just from translating addresses is an unnecessarily strong requirement. A rump vCard could be returned based on what the CM knows immediately, but what is to tell the clients that they can ask for more?
If ContactInfo attributes are explicitly requested, the CM could retrieve remote contact information in background and signal updates. But it should not be mandated behavior.

Should o.fd.Tp.Protocol grow methods to resolve addresses/URIs statically, to complement NormalizeContact?

(In reply to comment #30)
>     <tp:contact-attribute name="representations" type="a{ss}"
>                           tp:type="Representations_Map">
>       <tp:docstring>
>         The various vCard and URI addresses that identify this contact.
>       </tp:docstring>
>     </tp:contact-attribute>
> 
> I think it's better to have another attribute for URI representations, rather
> than (in addition to?) distinguishing them by the special "url:" namespace
> (which may be a misnomer, as URLs are a subset of URIs). A client should not be
> forced to filter maps if it is only interested in URI representations. Also,
> with my pet case of using URNs, "url:urn" will look ugly and confusing.

Do you think using a url: prefix is a bad idea everywhere we expect a vcard field? Or just that we should use uri: instead?

If the former, we will need:
 * To split the attribute above to vcard-representations and uri-representations.
 * Addressing.GetContactsByURI
 * Add Protocol.AddressableURIField
 * Add Channel.TargetURIScheme and Channel.TargetURI

URLs could just be on their own and not be used as URL fields from vcards, so this weird pattern could be avoided:
Addressing.GetContactsByVCardField("url", "sip:example.com")

And instead would be:
Addressing.GetContactsByURI("sip:eitan@example.com")
and
EnsureChannel(
  { ChannelType: Call,
    TargetURIScheme: "sip",
    TargetURI: "sip:eitan@example.com",
  });

Does all that look reasonable?

> 
>     <tp:contact-attribute name="requested" type="s">
>       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>         <p>The contact's address, as it was requested
>         through <tp:member-ref>GetContactsByVCardField</tp:member-ref>.</p>
>       </tp:docstring>
>     </tp:contact-attribute>
> 
> Should the vCard field name be also represented?

Good catch, I'll fix that. It should be ss.

(In reply to comment #31)
> (In reply to comment #17)
> > > +          <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.
> 
> I agree. Getting any meaningful contact info attributes just from translating
> addresses is an unnecessarily strong requirement. A rump vCard could be
> returned based on what the CM knows immediately, but what is to tell the
> clients that they can ask for more?
> If ContactInfo attributes are explicitly requested, the CM could retrieve
> remote contact information in background and signal updates. But it should not
> be mandated behavior.

The new draft got rid of this, and instead you get Addressing attributes which are different vcard representations.

(In reply to comment #32)
> Should o.fd.Tp.Protocol grow methods to resolve addresses/URIs statically, to
> complement NormalizeContact?

I'm not sure what you mean here, doesn't resolving imply the connection being connected? How could it do it statically on Protocol?

(In reply to comment #35)
> > Should o.fd.Tp.Protocol grow methods to resolve addresses/URIs statically, to
> > complement NormalizeContact?
> 
> I'm not sure what you mean here, doesn't resolving imply the connection being
> connected? How could it do it statically on Protocol?

I mean translation without using the network; same considerations apply as for NormalizeContact.

For example, a Skype Protocol could do:

GetContactIDByAddress('tel', '+7(777)777-7777') => '+77777777777'

(In reply to comment #33)
>  * To split the attribute above to vcard-representations and
> uri-representations.

Yes. Maybe some shorter names, like 'addresses' and 'uris'.
Or maybe just drop the representations for now (move to a branch for later consideration), since we have requested (and its URI brother?).

>  * Addressing.GetContactsByURI
>  * Add Protocol.AddressableURIField

AddressableURISchemes?

>  * Add Channel.TargetURIScheme and Channel.TargetURI

The scheme may be needed for dispatching, right? Otherwise it is redundant.

> URLs could just be on their own and not be used as URL fields from vcards, so
> this weird pattern could be avoided:
> Addressing.GetContactsByVCardField("url", "sip:example.com")
> 
> And instead would be:
> Addressing.GetContactsByURI("sip:eitan@example.com")
> and
> EnsureChannel(
>   { ChannelType: Call,
>     TargetURIScheme: "sip",
>     TargetURI: "sip:eitan@example.com",
>   });
> 
> Does all that look reasonable?

Yep.

(In reply to comment #36)
> (In reply to comment #35)
> > > Should o.fd.Tp.Protocol grow methods to resolve addresses/URIs statically, to
> > > complement NormalizeContact?
> > 
> > I'm not sure what you mean here, doesn't resolving imply the connection being
> > connected? How could it do it statically on Protocol?
> 
> I mean translation without using the network; same considerations apply as for
> NormalizeContact.
> 
> For example, a Skype Protocol could do:
> 
> GetContactIDByAddress('tel', '+7(777)777-7777') => '+77777777777'

How about:
NormalizeVCardAddress('tel', '+7(777)777-7777') => '+77777777777'
NormalizeURI('xmpp:eitan@EXAMPLE.COM') => 'xmpp:eitan@example.com'

(In reply to comment #37)
> (In reply to comment #33)
> >  * To split the attribute above to vcard-representations and
> > uri-representations.
> 
> Yes. Maybe some shorter names, like 'addresses' and 'uris'.
> Or maybe just drop the representations for now (move to a branch for later
> consideration), since we have requested (and its URI brother?).
> 

Added in the most recent HEAD in my branch (da2679d).

> >  * Addressing.GetContactsByURI
> >  * Add Protocol.AddressableURIField
> 
> AddressableURISchemes?
> 
> >  * Add Channel.TargetURIScheme and Channel.TargetURI
> 
> The scheme may be needed for dispatching, right? Otherwise it is redundant.

Right :(

> 
> > URLs could just be on their own and not be used as URL fields from vcards, so
> > this weird pattern could be avoided:
> > Addressing.GetContactsByVCardField("url", "sip:example.com")
> > 
> > And instead would be:
> > Addressing.GetContactsByURI("sip:eitan@example.com")
> > and
> > EnsureChannel(
> >   { ChannelType: Call,
> >     TargetURIScheme: "sip",
> >     TargetURI: "sip:eitan@example.com",
> >   });
> > 
> > Does all that look reasonable?
> 
> Yep.

Done.

(In reply to comment #38)
> NormalizeVCardAddress('tel', '+7(777)777-7777') => '+77777777777'
> NormalizeURI('xmpp:eitan@EXAMPLE.COM') => 'xmpp:eitan@example.com'

OK to me.

OK, new branch up for review:

http://git.collabora.co.uk/?p=user/eitan/telepathy-spec.git;a=shortlog;h=refs/heads/vcard-field-requests

http://people.freedesktop.org/~eitani/telepathy-spec-vcard_field_requests/spec/

This branch adds stable (i.e. guaranteed) API, so it can't easily be merged as a draft. I think it'd be worth moving TargetURI, TargetURIScheme, TargetVCardField and TargetVCardAddress to a new Chan.I.Addressing which can be merged as a draft (we can consider flattening them into Channel in Telepathy 1.0), and moving the Protocol stuff to a Protocol.I.Addressing (ditto).

Alternatively, if you feel strongly that the new stuff should be a core part of Telepathy as soon as it's undrafted, put it on Channel.FUTURE and Protocol.FUTURE pseudo-interfaces.

TargetURIScheme exactly duplicates part of TargetURI, so it deserves a <tp:rationale> explaining that yes, it really is duplicate information, and it exists to be available in requestable channel classes. TargetURI and TargetURIScheme should probably reference each other (or perhaps only in one direction) to say that TargetURI MUST start with TargetURIScheme + ":".

Protocol.NormalizeVCardAddress should document what happens if the VCard_Field is not in AddressableVCardFields, and what happens if the VCard_Address is not a syntactically valid instance of that vCard field.

(My opinion: InvalidArgument or NotImplemented for the former, InvalidHandle (stretching its meaning rather) or InvalidArgument for the latter.)

Likewise for NormalizeURI.

NormalizeURI seems to have incorrect argument names/types, referring to vCard addresses.

> +          The URI to normalize. The URI's scheme must appear in

It might be worth repeating "scheme (i.e. the part before the first colon)" here?

The copyright notice in Chan.I.Addressing needs stretching to include 2010.

> +          The URI addresses to get contact handles for. The URI
> +          schemes need to be supported by the connection, this could
> +          be determined by inspecting the TargetURIScheme
> +          fixed-property on
> +          [...]Requests.RequestableChannelClasses</tp:dbus-ref>.

No, I think this should be from the Protocol: the requestable channel classes are unnecessarily strict. A telepathy-sofiasip instance whose server lacks a PSTN gateway can still discuss, and allocate handles for, tel: URIs, even if it can't actually call them.

/requested-address and /requested-uri need well-defined semantics (I propose "MUST be omitted from the mapping") when not requested via the relevant method.

> If the <code>URL</code> vCard
> +          field is addressable, a colon, followed by the supported URI
> +          schemes will be concatenated.</p>
> +
> +          <p>For example: <code>["tel", "x-sip", "url:tel", [...]

I thought we agreed this was a bad idea? If so, please eradicate this mention of "url:"-prefixed pseudo-fields, and replace it with something like:

    The <code>url</code> vCard field MUST NOT appear here; see
    _AddressableURISchemes_ instead.

    | In practice, protocols have a limited set of URI schemes that make
    | sense to resolve as a contact.

GetContactsByVCardAddress and TargetVCardField should probably gain a similar note, pointing users to the appropriate URI-based alternative.

> Do you think using a url: prefix is a bad idea everywhere we expect a vcard
> field? Or just that we should use uri: instead?

For the record: if we'd gone this way, "uri" would be bad, since the vCard field name is "URL" with an L.

Regarding ENUM, I suspect the presentation we want is probably that the TargetID is the (normalized form of the) string the user typed, i.e. tel:+1234567890; even if my call was redirected via ENUM to sip:secretary@office.example.com, the string I should be saving in my address book is tel:+1234567890? Or is there a requirement or expectation I'm missing that means we shouldn't do this?

(Analogy: if I type example.com into any network client, there's a permanent-up-to-TTL mapping to 192.0.32.10, but that doesn't mean I should be displaying 192.0.32.10 in my UI, or saving it, or using it preferentially; if I connect my XMPP client to gmail.com, there's a permanent-up-to-TTL mapping via SRV to talk.l.google.com, but that doesn't mean I should be remembering that hostname.)

We could perhaps have an informational property on the Channel for "this is who you're actually talking to" if that information is actually needed? (Hmm, looks a lot like channel-specific handles... or XMPP resources, if you look at it sideways.)

(In reply to comment #33)
> Do you think using a url: prefix is a bad idea everywhere we expect a vcard
> field? Or just that we should use uri: instead?

I don't think this special case in vCard is necessary; explicit treatment of URIs should work better for clients, and it bypasses the terminological issue of "url" vs URI.

(In reply to comment #44)
> (In reply to comment #33)
> > Do you think using a url: prefix is a bad idea everywhere we expect a vcard
> > field? Or just that we should use uri: instead?
> 
> I don't think this special case in vCard is necessary; explicit treatment of
> URIs should work better for clients, and it bypasses the terminological issue
> of "url" vs URI.

I agree 100%

Pushed to:
http://git.collabora.co.uk/?p=user/eitan/telepathy-spec.git;a=shortlog;h=refs/heads/vcard-field-requests

Uploaded HTML to:
http://people.freedesktop.org/~eitani/telepathy-spec-vcard_field_requests/spec/

(In reply to comment #42)
> This branch adds stable (i.e. guaranteed) API, so it can't easily be merged as
> a draft. I think it'd be worth moving TargetURI, TargetURIScheme,
> TargetVCardField and TargetVCardAddress to a new Chan.I.Addressing which can be
> merged as a draft (we can consider flattening them into Channel in Telepathy
> 1.0), and moving the Protocol stuff to a Protocol.I.Addressing (ditto).
> 

I guess they could be separate interfaces. My concern is that CMs need to be consistent about implementing Chan.I.Addressing for every channel that has a target contact, or it will get confusing (for example, the iface would appear in channels requested through TargetURI, but not when through TargetID).

> Alternatively, if you feel strongly that the new stuff should be a core part of
> Telepathy as soon as it's undrafted, put it on Channel.FUTURE and
> Protocol.FUTURE pseudo-interfaces.
> 

I don't feel too strongly about that. Just slightly concerned above. I'll defer to your judgement, and make them distinct interfaces.

Done in 90795fb and 5a417c4

> TargetURIScheme exactly duplicates part of TargetURI, so it deserves a
> <tp:rationale> explaining that yes, it really is duplicate information, and it
> exists to be available in requestable channel classes. TargetURI and
> TargetURIScheme should probably reference each other (or perhaps only in one
> direction) to say that TargetURI MUST start with TargetURIScheme + ":".
> 

b06967c

> Protocol.NormalizeVCardAddress should document what happens if the VCard_Field
> is not in AddressableVCardFields, and what happens if the VCard_Address is not
> a syntactically valid instance of that vCard field.
> 
> (My opinion: InvalidArgument or NotImplemented for the former, InvalidHandle
> (stretching its meaning rather) or InvalidArgument for the latter.)
> 
> Likewise for NormalizeURI.
> 

5cc1f2b

> NormalizeURI seems to have incorrect argument names/types, referring to vCard
> addresses.

b016407

> 
> > +          The URI to normalize. The URI's scheme must appear in
> 
> It might be worth repeating "scheme (i.e. the part before the first colon)"
> here?
> 

5cc1f2b

> The copyright notice in Chan.I.Addressing needs stretching to include 2010.
> 

ba56944


> > +          The URI addresses to get contact handles for. The URI
> > +          schemes need to be supported by the connection, this could
> > +          be determined by inspecting the TargetURIScheme
> > +          fixed-property on
> > +          [...]Requests.RequestableChannelClasses</tp:dbus-ref>.
> 
> No, I think this should be from the Protocol: the requestable channel classes
> are unnecessarily strict. A telepathy-sofiasip instance whose server lacks a
> PSTN gateway can still discuss, and allocate handles for, tel: URIs, even if it
> can't actually call them.

dab41e3

> 
> /requested-address and /requested-uri need well-defined semantics (I propose
> "MUST be omitted from the mapping") when not requested via the relevant method.
> 

e21a532

> > If the <code>URL</code> vCard
> > +          field is addressable, a colon, followed by the supported URI
> > +          schemes will be concatenated.</p>
> > +
> > +          <p>For example: <code>["tel", "x-sip", "url:tel", [...]
> 
> I thought we agreed this was a bad idea? If so, please eradicate this mention
> of "url:"-prefixed pseudo-fields, 

db93862

> and replace it with something like:
> 
>     The <code>url</code> vCard field MUST NOT appear here; see
>     _AddressableURISchemes_ instead.
> 
>     | In practice, protocols have a limited set of URI schemes that make
>     | sense to resolve as a contact.
> 
> GetContactsByVCardAddress and TargetVCardField should probably gain a similar
> note, pointing users to the appropriate URI-based alternative.
> 

52a4101

> > Do you think using a url: prefix is a bad idea everywhere we expect a vcard
> > field? Or just that we should use uri: instead?
> 
> For the record: if we'd gone this way, "uri" would be bad, since the vCard
> field name is "URL" with an L.

This now looks good as a draft. There are some minor typos etc. that I'd like fixed before the next spec release if possible, but they don't block a merge.

Minor style point for the future: I prefer the introductory <tp:docstring> to appear at the beginning of the XML (I know we're inconsistent about that usage, but I prefer to at least have it this way in new interfaces).

It would be good if you could expand on the introductory docstrings a bit, too.

> This interface deals with different forms of addresses that conform to contacts.

Conform doesn't mean that. Refer to contacts? Can be used to identify contacts?

> cannot me satisfied

cannot be satisfied (appears at least twice, please grep)

(In reply to comment #46)
> > I think it'd be worth moving TargetURI, TargetURIScheme,
> > TargetVCardField and TargetVCardAddress to a new Chan.I.Addressing which can be
> > merged as a draft (we can consider flattening them into Channel in Telepathy
> > 1.0), and moving the Protocol stuff to a Protocol.I.Addressing (ditto).
> 
> I guess they could be separate interfaces. My concern is that CMs need to be
> consistent about implementing Chan.I.Addressing for every channel that has a
> target contact, or it will get confusing (for example, the iface would appear
> in channels requested through TargetURI, but not when through TargetID).

I think implementing the situation you're worried about is actually more difficult than implementing the correct situation, so this doesn't need to be a concern :-)

If you're worried, you could say this at appropriate places in Chan.I.Addressing:

    If the protocol's identifiers can be represented as a vCard field, and
    the connection manager supports this interface, then
    every channel whose _TargetHandleType_ is Contact MUST have
    non-empty _TargetVCardField_ and _TargetVCardAddress_ properties that
    represent the _TargetID_.

    (For instance, XMPP channels that communicate with a contact would
    have TargetVCardField = "x-jabber", and TargetVCardAddress equal to
    TargetID; channels on a SIP connection with a PSTN gateway might
    have a TargetVCardField of either "x-sip" or "tel".)

    If the protocol's identifiers can be represented as a URI,
    and the connection manager supports this interface, then every
    channel whose _TargetHandleType_ is Contact MUST have a non-empty
    _TargetURI_ property that represents the _TargetID_, and
    a corresponding _TargetURIScheme_ property.

    (For instance, XMPP channels that communicate with a contact would
    have TargetURIScheme = "xmpp", and TargetURI set to an xmpp: URI
    corresponding to the TargetID; channels on a SIP connection with
    a PSTN gateway might have a TargetURIScheme of either "sip", "sips"
    or "tel".)

One other thing: I wonder whether it'd be worth having a list of well-known unofficial URI schemes in one of these interfaces, probably Conn.I.Addressing or Protocol.I.Addressing.

XMPP, SIP etc. are easy, because their URI schemes are proper IANA-registered ones. However, it might be worth mentioning the de facto URI schemes for the proprietary protocols, for which see <http://en.wikipedia.org/wiki/URI_scheme>.

In particular, for the ones that are primarily verb-like and have no noun form (ymsgr, aim, msnim), we should decide which verb to use as the TargetURI. I suggest either "add contact" (aim:addbuddy?screenname=foo, msnim:add?contact=foo@example.com, ymsgr:addfriend?foo) or "send IM" (aim:goim?screenname=foo, ymsgr:sendIM?foo, msnim:chat?contact=foo@example.com) as the most representative way to talk about a contact.

(From a quick skim through the list of unofficial URI schemes on Wikipedia, IRC and Gadu-Gadu have noun-like URIs (like SIP), and Skype has noun-like URIs with an optional trailing verb (like XMPP), so they're easy to represent.)

(In reply to comment #47)
> If you're worried, you could say this at appropriate places in
> Chan.I.Addressing:
> 
>     If the protocol's identifiers can be represented as a vCard field, and
>     the connection manager supports this interface, then
>     every channel whose _TargetHandleType_ is Contact MUST have
>     non-empty _TargetVCardField_ and _TargetVCardAddress_ properties that
>     represent the _TargetID_.
> 
>     (For instance, XMPP channels that communicate with a contact would
>     have TargetVCardField = "x-jabber", and TargetVCardAddress equal to
>     TargetID; channels on a SIP connection with a PSTN gateway might
>     have a TargetVCardField of either "x-sip" or "tel".)
> 
>     If the protocol's identifiers can be represented as a URI,
>     and the connection manager supports this interface, then every
>     channel whose _TargetHandleType_ is Contact MUST have a non-empty
>     _TargetURI_ property that represents the _TargetID_, and
>     a corresponding _TargetURIScheme_ property.
> 
>     (For instance, XMPP channels that communicate with a contact would
>     have TargetURIScheme = "xmpp", and TargetURI set to an xmpp: URI
>     corresponding to the TargetID; channels on a SIP connection with
>     a PSTN gateway might have a TargetURIScheme of either "sip", "sips"
>     or "tel".)

I don't think these are correct. A random channel with a contact target handle will not have these properties populated unless they were requested. This is because one given contact could have more than one address, this is why the contact addressing attributes are in plural.

My concern was that CMs that implement this need to make sure that all call/tube/text/etc channels implement this interface for consistency's sake. It's not a big deal, but it's yet another interface. And by "implement" I just mean this needs to show up in Channel.Interfaces, that's all.

(In reply to comment #48)
> One other thing: I wonder whether it'd be worth having a list of well-known
> unofficial URI schemes in one of these interfaces, probably Conn.I.Addressing
> or Protocol.I.Addressing.
> 
> XMPP, SIP etc. are easy, because their URI schemes are proper IANA-registered
> ones. However, it might be worth mentioning the de facto URI schemes for the
> proprietary protocols, for which see <http://en.wikipedia.org/wiki/URI_scheme>.
> 
> In particular, for the ones that are primarily verb-like and have no noun form
> (ymsgr, aim, msnim), we should decide which verb to use as the TargetURI. I
> suggest either "add contact" (aim:addbuddy?screenname=foo,
> msnim:add?contact=foo@example.com, ymsgr:addfriend?foo) or "send IM"
> (aim:goim?screenname=foo, ymsgr:sendIM?foo, msnim:chat?contact=foo@example.com)
> as the most representative way to talk about a contact.
> 
> (From a quick skim through the list of unofficial URI schemes on Wikipedia, IRC
> and Gadu-Gadu have noun-like URIs (like SIP), and Skype has noun-like URIs with
> an optional trailing verb (like XMPP), so they're easy to represent.)

I'll add this to Protocol.I.Addressing.AddressableURISchemes.

About the verby schemes, maybe it should be clear that the verb (hostname) is ignored and that a contact query is required. For example in msnim a "contact=", in aol a "screenname=", and in ymsgr any verb that takes a yahooid as a query.

IRC only seems to work in the context of servers and channels and not contacts, so I don't think it should be included.

This has been merged as a draft to master with additional amendments.

(In reply to comment #51)
> with additional amendments

Please give reviewers a chance to review all non-trivial amendments before pushing to master. Typo and build-system fixes are sometimes considered trivial; clarifications and normative changes are never trivial.

(This also means that rebasing just before pushing is unhelpful, because reviewers can't tell what has changed.)

> +        following lines in it's <tt>.manager</tt> file.</p>

Still typo'd

> +          <dt><code>x-icq</code></dt>
> +          <dd>The X-ICQ vCard field. Used for ICQ UINs.</dd>

Duplicated

> +          <dt><code>x-skype</code></dt>
> +          <dd>The X-SKYPE vCard field. Used for Skype user names or
> +          telephone numbers.</dd>
> +          <dt><code>x-skype-username</code></dt>
> +          <dd>The X-SKYPE-USERNAME vCard field. Used for Skype user names.</dd>

I think we should choose one of these (I would suggest X-SKYPE unless there are reasons to prefer X-SKYPE-USERNAME) and say that for the purposes of Telepathy, it is the preferred form.

> +          <dt><code>msnm</code></dt>
> +          <dd>The authority part of this URI is ignored. Instead, the
> +            <code>contact</code> query key is used.
> +            For example: <code>msnim:chat?contact=julien</code>.</dd>

Typo: s/msnm/msnim/

This is not a hierarchical URI, so it doesn't have an authority part: I'd say "verb part".

The thing I wanted you to say about msnim (and the other always-verb-like schemes) is something like "For the purposes of _Protocol.I.Addressing_, _Conn.I.Addressing_ and _Chan.I.Addressing_, the verb part is ignored, and SHOULD be "add"; the contact field in the query string is used to identify the contact."

Same comments about aim and ymsgr.

(In reply to comment #49)
> I don't think these are correct. A random channel with a contact target handle
> will not have these properties populated unless they were requested.

I think they should be populated anyway, with the/a preferred form. I'm running away to a meeting now but will say more about this later.

Sorry for merging.

Here is a branch with the additional tweaks you mentioned:
http://git.collabora.co.uk/?p=user/eitan/telepathy-spec.git;a=shortlog;h=refs/heads/addressing-tweaks

> +            <code>username</code> field in the query string is used to
> +            identify the contact.
> +            For example: <code>aim:addbuddy?screenname=julien</code>.</dd>

Inconsistent: username vs. screenname. Which is it? (Wikipedia says screenname.)

review+ with the obvious fix for that.

Merged, thanks!

I can't find anything in any of the Addressing interfaces explaining how these would appear in RequestableChannelClasses. Oh hmm, but Protocol.I.Addressing.AddressableVCardFields is a nice shortcut for that. In any case, I think that the Channel interface should document some possible RequestableChannelClasses including these properties, given that they are requestable.

Implementation issues from Bug #30296:

smcv:
> wjt:
> > ‘...using the addressing bits for
> > requests requires handle type to be omitted.’: i think that's fine. you might
> > not know up-front what handle type the URI corresponds to. You could have an
> > XMPP URI for a MUC. (I don't know if such a beast exists, the internet
> > connection here isn't working.)
> 
> I'd assumed that the scope of Addressing was limited to Handle_Type_Contact,
> although I suppose if an organization can have a vCard (which it can), then so
> can a chatroom...
> 
> If Addressing *isn't* implicitly Contact-based, then we need to include the
> handle type in the request (and amend telepathy-glib to cope) - given an XMPP
> JID or URI, I don't believe we can generally tell whether it's a contact or a
> MUC (in an ideal world, possibly we could if Google's MUC servers responded to
> disco queries).

Chan.I.Addressing.TargetURI and Chan.I.Addressing.TargetVCardAddress currently both say "TargetHandleType must either not be present or set to Handle_Type_Contact". The former works, the latter needs telepathy-glib changes but I think we should support it anyway. We'll need to change that spec text if we want to support addressing non-contacts by vCard field or URI.

The only other handle type we currently have is Handle_Type_Room. Does anyone feel strongly that we should or shouldn't support requesting chatrooms by URI or vCard field?

Overview of a few protocols with URI schemes and chatrooms
----------------------------------------------------------

XMPP

xmpp:smcv@example.com is a contact. xmpp:smcvsfriends@conference.example.com is a MUC (room). We obviously can't tell this syntactically; if all servers were perfect, we might be able to disco them both and find out which was which, but that requires round-trips, and Google MUC servers don't reply to disco anyway.

IRC

It appears we *can* tell syntactically, via ",isnick".
There is no RFC. References include <http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt>, <http://tools.ietf.org/html/draft-butcher-irc-url-04>, <http://www.mozilla.org/projects/rt-messaging/chatzilla/irc-urls.html>, <http://about.psyc.eu/IRC_URI>
irc://irc.freenode.net/telepathy is a room, #telepathy. So is irc://irc.freenode.net/%23telepathy (#telepathy, URI-encoded).
irc://irc.freenode.net/smcv,isnick is a contact, smcv (despite comma not being valid in URIs...)
The Mozilla page seems to suggest that irc://irc.freenode.net/smcv would also be a valid way to describe the contact smcv, but I can't see how that would ever be useful - in practice the client would have to guess wildly and join #smcv instead.

MSN, Skype

Chatrooms don't have user-visible names so there's nothing useful to put in a URI.

(In reply to comment #57)
> I can't find anything in any of the Addressing interfaces explaining how these
> would appear in RequestableChannelClasses. [...] In
> any case, I think that the Channel interface should document some possible
> RequestableChannelClasses including these properties, given that they are
> requestable.

Yes; otherwise, the only way to know how the spec author intends it to work is to look at Gabble.

(In reply to comment #58)
> Chan.I.Addressing.TargetURI and Chan.I.Addressing.TargetVCardAddress currently
> both say "TargetHandleType must either not be present or set to
> Handle_Type_Contact". The former works, the latter needs telepathy-glib changes
> but I think we should support it anyway. We'll need to change that spec text if
> we want to support addressing non-contacts by vCard field or URI.
> 
> The only other handle type we currently have is Handle_Type_Room.

I'm inclined to say we should limit the scope of Addressing to be addressing contacts: we could add a new property to Chan.I.Room (Bug #23151) if we want to be able to address rooms by URI.

Implementation status:

* Gabble: Bug #30296 (a simple case: xmpp: and vCard X-JABBER)
* tpsip: Bug #31469 (a complex case: tel:, sip:, sips:, and vCard TEL and X-SIP)
* butterfly: no bug yet

Brain dump:

We could dodge some of the channel class complexity by just putting all of the properties into Allowed, rather than having an explosion of channel classes, and say that applications should check out the protocol object to see what's supported. This allows us to punt on the discovering-support-when-connected side of things, without blocking us from adding it in the future.

Also, the Protocol interface could be finished without the Connection and Channel interfaces. Currently telepathy-sofiasip lets you request handles for phone numbers or for SIP IDs, and guesses what you mean well enough. So this would give us the basic information on what's supported on the protocol, which we don't currently have.

(In reply to comment #60)
> Also, the Protocol interface could be finished without the Connection and
> Channel interfaces. Currently telepathy-sofiasip lets you request handles for
> phone numbers or for SIP IDs, and guesses what you mean well enough. So this
> would give us the basic information on what's supported on the protocol, which
> we don't currently have.

Yeah, let's do the Protocol interface first. I'll have it block this bug.

Andre, do you have a branch, or is your proposal just "it's perfect, undraft it as-is"?

(In reply to comment #62)
> or is your proposal just "it's perfect, undraft it
> as-is"?

It isn't. :-P

> Each contact's attributes will always include at least the identifier
> that would be obtained by inspecting the handle
> (org.freedesktop.Telepathy.Connection/contact-id), and the vCard field
> used for requesting the contact in
> org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info.

This is old and wrong: the better version (as implemented in Andre's Gabble branch) is to say that the attributes will always include .../contact-id and .../requested-address. This is no longer anything to do with ContactInfo.

Similarly, when requesting by URI, you always get at least .../contact-id and ../requested-uri.

This representation is flawed, though: suppose I request two URIs (or two vCard fields) that resolve to the same contact:

    GetContactsByURI(["xmpp:simon.mcvittie@collabora.co.uk",
                      "xmpp:simon.mcvittie@Collabora.CO.UK"], [])

The result is not useful:

    {
        my handle => {
            .../contact-id => "simon.mcvittie@collabora.co.uk",
            .../requested-address => one of the things you asked for, randomly
    }

... you find out that one of the URIs (randomly chosen) is me, and you think the other was invalid, whereas in fact it was perfectly valid and also resolved as me.

The cleanest way to fix this (but I'm not sure how easy it is to implement in telepathy-glib) would be to throw away the .../requested-foo pseudo-attributes, and change the result to a{su}a{ua{sv}} like this:

    {
        # thing you asked for => handle
        # if you requested by vCard field, the single vCard field is omitted
        # (you are expected to remember what you asked for)
        "xmpp:simon.mcvittie@collabora.co.uk" => my handle,
        "xmpp:simon.mcvittie@Collabora.CO.UK" => my handle,
    },
    {
        my handle => { .../contact-id => ... }
    }

The next best thing would be to make requested-addresses and requested-uris into arrays so they can express this sort of thing, as a list of more than one requested string.

(In reply to comment #63)
> The cleanest way to fix this (but I'm not sure how easy it is to implement in
> telepathy-glib) ...

Now that we have tp_contacts_mixin_get_contact_attributes() I believe this is actually quite easy?

Why does this depend on bug #31469?

For the record, there is no pressure to undraft these interfaces until we have verified an implementation. We can do it off non-mainline branches.

(In reply to comment #65)
> Why does this depend on bug #31469?

When it was initially opened, telepathy-sofiasip was the only CM that would benefit from a non-trivial implementation (XMPP doesn't count, since it has one vCard field and one URI scheme), so undrafting this was blocked by having that non-trivial implementation.

We now want x-facebook-id for XMPP, so Gabble's implementation isn't going to be so trivial any more.

(In reply to comment #63)
> (In reply to comment #62)
> > or is your proposal just "it's perfect, undraft it
> > as-is"?
> 
> It isn't. :-P
> 
> > Each contact's attributes will always include at least the identifier
> > that would be obtained by inspecting the handle
> > (org.freedesktop.Telepathy.Connection/contact-id), and the vCard field
> > used for requesting the contact in
> > org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info.
> 
> This is old and wrong: the better version (as implemented in Andre's Gabble
> branch) is to say that the attributes will always include .../contact-id and
> .../requested-address. This is no longer anything to do with ContactInfo.
> 
> Similarly, when requesting by URI, you always get at least .../contact-id and
> ../requested-uri.
> 
> This representation is flawed, though: suppose I request two URIs (or two vCard
> fields) that resolve to the same contact:
> 
>     GetContactsByURI(["xmpp:simon.mcvittie@collabora.co.uk",
>                       "xmpp:simon.mcvittie@Collabora.CO.UK"], [])
> 
> The result is not useful:
> 
>     {
>         my handle => {
>             .../contact-id => "simon.mcvittie@collabora.co.uk",
>             .../requested-address => one of the things you asked for, randomly
>     }
> 
> ... you find out that one of the URIs (randomly chosen) is me, and you think
> the other was invalid, whereas in fact it was perfectly valid and also resolved
> as me.
> 
> The cleanest way to fix this (but I'm not sure how easy it is to implement in
> telepathy-glib) would be to throw away the .../requested-foo pseudo-attributes,
> and change the result to a{su}a{ua{sv}} like this:
> 
>     {
>         # thing you asked for => handle
>         # if you requested by vCard field, the single vCard field is omitted
>         # (you are expected to remember what you asked for)
>         "xmpp:simon.mcvittie@collabora.co.uk" => my handle,
>         "xmpp:simon.mcvittie@Collabora.CO.UK" => my handle,
>     },
>     {
>         my handle => { .../contact-id => ... }
>     }
> 
> The next best thing would be to make requested-addresses and requested-uris
> into arrays so they can express this sort of thing, as a list of more than one
> requested string.
Changes in the spec done and implemented in my gabble repo. I will update the spec with the changes once we are done here.
URL updated pointing to the branch implementing this.

The changes to Conn.I.Addr in your Gabble branch make sense to me, please copy them into the spec. (AIUI, it's still a draft until we validate the implementation by producing a client-side in either tp-glib or tp-qt.)

(In reply to comment #68)
> The changes to Conn.I.Addr in your Gabble branch make sense to me, please copy
> them into the spec. (AIUI, it's still a draft until we validate the
> implementation by producing a client-side in either tp-glib or tp-qt.)

Done, changes merged upstream.

How about un-DRAFTing the interface, now that there is a client-side implementation in a released tp-qt version (0.9.0) as well?

Created attachment 57036 [details] [review]
Document the members of VCard_Field_Address_Map and why it's  plural

(In reply to comment #70)
> How about un-DRAFTing the interface, now that there is a client-side implementation in a released tp-qt version (0.9.0) as well?

I have no objection to undrafting this; let's do it for 0.25.2.

Looking back through it, I did notice that VCard_Field_Address_Map wasn't documented.

Created attachment 57037 [details] [review]
Undraft Conn.I.Addressing

---

Any objection?

(In reply to comment #72)
> Created attachment 57037 [details] [review] [review]
> Undraft Conn.I.Addressing
> 
> ---
> 
> Any objection?

Hmm, I have some things I would like to discuss first.

tp-qt 0.9.0 supports Conn.I.Addressing.DRAFT from tp-spec 0.25.1. As the interface was draft we only generate internal low-level proxies (not exported).
I see now that the current spec release contains Conn.I.Addressing1 instead (not support by tp-qt).

The problem is that we haven't decided what to do with versioned interfaces.
Should we make the generated proxies public? The generate class is named ConnectionInterfaceAddressingInterface (not including the version number). What if the
interface changes to Addressing2 and breaks API? Should we generate the class as ConnectionInterfaceAddressing1Interface instead so we can generate both when
Addressing2 is around? Or should we make all versioned interfaces internal now, much like what we do for DRAFT interfaces?
Or should we just ignore the versioning and make it public and hope for the best.

We would also have issues with the high-level API when/if versioned interfaces changes, as the changes may affect high-level public API (we could deprecate
them if needed, but still an "issue").

Note that this is important for all versioned interfaces, not only this one.

(In reply to comment #73)
> The problem is that we haven't decided what to do with versioned interfaces.
> Should we make the generated proxies public? The generate class is named ConnectionInterfaceAddressingInterface (not including the version number).
> What if the interface changes to Addressing2 and breaks API? Should we
> generate the class as ConnectionInterfaceAddressing1Interface instead so
> we can generate both when Addressing2 is around? Or should we make all
> versioned interfaces internal now, much like what we do for DRAFT interfaces?

In telepathy-glib, the generated code uses the (unversioned) node name from the spec XML to generate the C bindings, so if we break a versioned interface, we'll break telepathy-glib anyway.

I think tp-qt should follow tp-glib here: use the node name to decide what to call generated stuff, and if we break it in Addressing2, we'll have to change the node name to ..._Addressing2 (leading to tp_svc_connection_interface_addressing2_get_new_thing() or whatever, which is admittedly ugly, but that'd be our fault for getting it wrong the first time and needing to break ABI).

I believe the rationale for the node name not initially being versioned was that when early drafts break ABI but leave the node name the same, you don't have to run sed over the bits that didn't change just to replace Foo1 with Foo2, only fix the things that actually changed - but when generating code for a "hopefully final" versioned interface, that doesn't apply, since Foo = Foo1 has effectively become part of the API. At *that* point, you have to version the node-names of subsequent versions.

I think this situation could make sense, for instance:

* design Foo1, generate code as Foo, implement in Gabble,  find that it's
  wrong
* design Foo2, generate code as Foo, fix Gabble to compile again,
  implement in Empathy, find that it's still wrong
* design Foo3, generate code as Foo, fix Gabble/Empathy to compile again,
  everyone's happy, "ship it", declare stable, add to tp-glib & tp-qt
* discover that to support Gadu-Gadu or something, we need a Foo4;
  generate code as Foo4 and have it as a second, parallel stable version

Versioned interfaces were mostly wjt's idea, I think. Will, if I'm not understanding this correctly, please correct me :-)

> We would also have issues with the high-level API when/if versioned
> interfaces changes, as the changes may affect high-level public API
> (we could deprecate them if needed, but still an "issue").

Yes, this is unavoidable (and this is why we shouldn't be too keen to add high-level API for things that are not necessarily fully-designed yet). We shouldn't merge high-level API until we're reasonably sure about it.

(In reply to comment #74)
> Will, if I'm not understanding this correctly, please correct me :-)

Do whatever works.

Created attachment 57093 [details] [review]
Describe our policy on versioned interfaces

Andre, does this sound sensible and address your concerns?

(In reply to comment #76)
> Created attachment 57093 [details] [review] [review]
> Describe our policy on versioned interfaces
> 
> Andre, does this sound sensible and address your concerns?

Seems perfectly fine for me :). So be it.

(In reply to comment #77)
> Seems perfectly fine for me :). So be it.

Thanks, committed. So, who likes this interface? Shall we ship it? Any other objections? Anyone want to review my patches?

At the moment I'm trying to herd things into a release of tp-spec for today or tomorrow (with captchas, Account.Supersedes and hopefully Call1), so if you want or don't want this interface, speak now.

(In reply to comment #74)
> Versioned interfaces were mostly wjt's idea, I think. Will, if I'm not understanding this correctly, please correct me :-)

I'm not Will, but I can pretend to be him.

I've seen you've pushed this change to master. I personally don't really care what you do with versioning in master, but I do not agree with this way for next. It's way way way way too complicated. I find it extremely difficult to read the four paragraphs you wrote in that README without losing interest and going to drink some free coke.

I think tp:causes-havoc should just be noticed by the HTML generation code and display a pretty warning at the top of the generated HTML and that's it -- don't change any codegen behaviour on it.

In next, *every* non-core interface is versioned. Did you see that?

I think in next, tp-glib should generate code for everything, depending on the interface name, not the node name. So, generate tp_svc_connection_interface_vengaboys1_call_go_to_ibiza for im.telepathy1.Connection.Interface.Vengaboys1.GoToIbiza in node Connection_Interface_Vengaboys. I guess we'll need to version node names so we can generate code for both versions of Conn.Iface.Vengaboys{1,2} but that's an implementation detail.

So just generate code for everything. If something's not ready at all for any code, then don't put it in the spec at all... If we come out with Channel.Iface.RoomConfig19 then who cares? tp_svc_channel_interface_room_config19_… looks ugly but no-one cares. This will be in the lowlevel library which only tp-glib highlevel should be using anyway. It'll look a bit ugly in the dbus-monitor logs too, but I don't care about that either.

So, yeah, make things reaaaaaaally simple. What's wrong with this?

I still haven't managed to get through those instructions in the README. Feel free to keep it for master though.

(In reply to comment #79)
> In next, *every* non-core interface is versioned. Did you see that?

Yes, and I agree with your versioning strategy as described in the commit message for 7fb519ab43f34.

> I think in next, tp-glib should generate code for everything,
> depending on the interface name, not the node name. So, generate
> tp_svc_connection_interface_vengaboys1_call_go_to_ibiza for
> im.telepathy1.Connection.Interface.Vengaboys1.GoToIbiza in node
> Connection_Interface_Vengaboys. I
> guess we'll need to version node names so we can generate code for
> both versions of Conn.Iface.Vengaboys{1,2} but that's an
> implementation detail.

Sure, that's fine. We'll also need to change the filenames so we can *have* both versions (let's keep the filename == nodename.replace('/', '') + '.xml' invariant, it's probably the easiest-to-understand).

I believe the rationale for unversioned codegen until the first stable version was this. Suppose you have an interface Vengaboys1 with GoToIbiza and Party methods, then you realise GoToIbiza needs an extra parameter or something. In the approach you're advocating for 'next', you also have to replace all calls to ..._vengaboys1_call_party with ..._vengaboys2_call_party, even though the signature and semantics of that method didn't actually change. That advantage stops applying as soon as you remove the draft/final distinction and generate ABI-stable code for all versions, though; so for 'next', let's do what you said instead.

For Conn.I.Addressing1 in master, I thought it was probably better to be consistent with Room2, RoomConfig1, Subject2 and Call1 (none of which have versioned filenames/node names/codegen) than to apply that simplification. Do you agree? (This also affects CaptchaAuthentication1, which we want to land soon.)

(In reply to comment #80)
> For Conn.I.Addressing1 in master, I thought it was probably better to
> be consistent with Room2, RoomConfig1, Subject2 and Call1 (none of which
> have versioned filenames/node names/codegen) than to apply
> that simplification. Do you agree?

Jonny agreed on IRC, so this is no longer a blocker.

(In reply to comment #78)
> So, who likes this interface? Shall we ship it? Any other objections?
> Anyone want to review my patches?

Andre clarifed on IRC that he meant "r+" for everything except the versioning. So, no more blockers, and I've merged this for 0.25.2.