Update Proto.I.Addressing from tp-spec.

3 files changed, 59 insertions, 24 deletions

diff --git a/glib/spec/Protocol_Interface_Addressing.xml b/glib/spec/Protocol_Interface_Addressing.xml
index 4bbdeb445..0bad92a6d 100644
--- a/glib/spec/Protocol_Interface_Addressing.xml
+++ b/glib/spec/Protocol_Interface_Addressing.xml
@@ -22,7 +22,8 @@
 
   <interface
      name="org.freedesktop.Telepathy.Protocol.Interface.Addressing">
-    <tp:added version="0.21.UNRELEASED">(as stable API)</tp:added>
+    <tp:added version="0.25.UNRELEASED">(as stable API)</tp:added>
+    <tp:changed version="0.25.UNRELEASED">(renamed NormalizeURI)</tp:changed>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>An interface for protocols that support multiple forms of
         addressing contacts, for example through vCard addresses and URIs.</p>
@@ -61,13 +62,6 @@ AddressableURISchemes=tel;sip;
               schemes that make sense to resolve as a contact.</p>
           </tp:rationale>
 
-        <p>This property should only be used when the connection is
-          offline. When it is connected the addressable fields should be
-          retrieved from the
-          <tp:dbus-ref
-             namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s
-             TargetVCardField fixed-property instead.</p>
-
         <p>Connection managers with a <code>.manager</code> file
           MUST cache this property in the protocol's section of the
           <code>.manager</code> file if it is non-empty, using the key
@@ -101,6 +95,9 @@ AddressableURISchemes=tel;sip;
           <dd>The X-MSN vCard field. Used for MSN contacts.</dd>
           <dt><code>x-yahoo</code></dt>
           <dd>The X-YAHOO vCard field. Used for Yahoo! IDs.</dd>
+          <dt><code>x-facebook-id</code></dt>
+          <dd>Used for Facebook IDs in XMPP. If the user JID is
+          "-12345@chat.facebook.com" then the x-facebook-id is "12345"</dd>
         </dl>
 
       </tp:docstring>
@@ -216,7 +213,8 @@ AddressableURISchemes=tel;sip;
 
       <arg direction="in" name="VCard_Address" type="s">
         <tp:docstring>
-          The address to normalize.
+          The address to normalize, which is assumed to belong to a
+          contact (and not, for instance, a chatroom or server).
         </tp:docstring>
       </arg>
 
@@ -242,8 +240,9 @@ AddressableURISchemes=tel;sip;
       </tp:possible-errors>
     </method>
 
-    <method name="NormalizeURI"
-      tp:name-for-bindings="Normalize_URI">
+    <method name="NormalizeContactURI"
+      tp:name-for-bindings="Normalize_Contact_URI">
+      <tp:added version="0.25.UNRELEASED">(renamed from NormalizeURI)</tp:added>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Attempt to normalize the given contact URI. Where possible, this
           SHOULD return an address that would appear in the
@@ -257,8 +256,28 @@ AddressableURISchemes=tel;sip;
             namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>,
           this method SHOULD perform a best-effort normalization.</p>
 
-        <p>Example: <code>xmpp:eitan@EXAMPLE.COM</code> would be normalized to
-        <code>xmpp:eitan@example.com</code>.</p>
+        <p>If the URI has extra information beyond what's necessary to
+          identify a particular contact, such as an XMPP resource or an
+          action to carry out, this extra information SHOULD be removed.
+          If all URIs in a scheme contain a verb or action
+          (like <code>aim</code>, <code>ymsgr</code> and
+          <code>msnim</code> URIs), then the verb SHOULD be replaced
+          with the one specified in
+          <tp:member-ref>AddressableURISchemes</tp:member-ref>.</p>
+
+        <tp:rationale>
+          <p>This method is intended to normalize URIs stored in address
+            books, for instance. In protocols like XMPP, if you
+            vary the resource or action (query string), the URI still
+            refers to the same high-level contact.</p>
+        </tp:rationale>
+
+        <p>For instance,
+          <code>xmpp:romeo@Example.Com/Empathy?message;body=Hello</code>
+          would be normalized to <code>xmpp:romeo@example.com</code>,
+          and <code>aim:goim?screenname=Romeo%20M&amp;message=Hello</code>
+          would be normalized to
+          <code>aim:addbuddy?screenname=romeom</code>.</p>
 
         <p>This method MAY simply raise NotImplemented on some
         protocols, if it has no use.</p>
@@ -266,9 +285,18 @@ AddressableURISchemes=tel;sip;
 
       <arg direction="in" name="URI" type="s">
         <tp:docstring>
-          The URI to normalize. The URI's scheme (i.e. the part before
-          the first colon) MUST appear in
-          <tp:member-ref>AddressableURISchemes</tp:member-ref>.
+          <p>The URI to normalize, which is assumed to refer to a contact
+            (as opposed to, for instance, a chatroom or a server).</p>
+
+        <tp:rationale>
+          <p>In some protocols, like XMPP, there is no way to tell whether
+            a given URI refers to a contact or a chatroom by looking at
+            its syntax.</p>
+        </tp:rationale>
+
+          <p>The URI's scheme (i.e. the part before
+            the first colon) MUST appear in
+            <tp:member-ref>AddressableURISchemes</tp:member-ref>.</p>
         </tp:docstring>
       </arg>
 
@@ -288,7 +316,14 @@ AddressableURISchemes=tel;sip;
 
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
-            The URI is syntactically incorrect.
+            <p>The URI is syntactically incorrect or cannot be interpreted
+              as a reference to a contact.</p>
+
+            <tp:rationale>
+              <p>For instance, <code>aim:!?</code> is not a valid AIM URI,
+                while <code>aim:goaway?message=Absent</code> is a
+                valid AIM URI, but not a contact.</p>
+            </tp:rationale>
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
diff --git a/glib/telepathy-glib/base-protocol.c b/glib/telepathy-glib/base-protocol.c
index 8756afe93..7cec21074 100644
--- a/glib/telepathy-glib/base-protocol.c
+++ b/glib/telepathy-glib/base-protocol.c
@@ -429,7 +429,7 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
  * always be implemented.
  * @normalize_vcard_address: protocol-specific implementation for normalizing
  * vCard addresses.
- * @normalize_uri: protocol-specific implementation for normalizing URIs.
+ * @normalize_contact_uri: protocol-specific implementation for normalizing contact URIs.
  *
  * The interface vtable for a %TP_TYPE_PROTOCOL_ADDRESSING.
  *
@@ -1725,7 +1725,7 @@ protocol_identify_account (TpSvcProtocol *protocol,
 }
 
 static void
-addressing_normalize_uri (TpSvcProtocolInterfaceAddressing *protocol,
+addressing_normalize_contact_uri (TpSvcProtocolInterfaceAddressing *protocol,
     const gchar *uri,
     DBusGMethodInvocation *context)
 {
@@ -1739,10 +1739,10 @@ addressing_normalize_uri (TpSvcProtocolInterfaceAddressing *protocol,
 
   iface = TP_PROTOCOL_ADDRESSING_GET_INTERFACE (self);
 
-  if (iface->normalize_uri == NULL)
+  if (iface->normalize_contact_uri == NULL)
     goto notimplemented;
 
-  ret = iface->normalize_uri (self, uri, &error);
+  ret = iface->normalize_contact_uri (self, uri, &error);
 
   if (ret == NULL)
     {
@@ -1751,7 +1751,7 @@ addressing_normalize_uri (TpSvcProtocolInterfaceAddressing *protocol,
       return;
     }
 
-  tp_svc_protocol_interface_addressing_return_from_normalize_uri (context,
+  tp_svc_protocol_interface_addressing_return_from_normalize_contact_uri (context,
       ret);
 
   g_free (ret);
@@ -1822,7 +1822,7 @@ static void
 addressing_iface_init (TpSvcProtocolInterfaceAddressingClass *cls)
 {
 #define IMPLEMENT(x) tp_svc_protocol_interface_addressing_implement_##x (cls, addressing_##x)
-  IMPLEMENT (normalize_uri);
+  IMPLEMENT (normalize_contact_uri);
   IMPLEMENT (normalize_vcard_address);
 #undef IMPLEMENT
 }
diff --git a/glib/telepathy-glib/base-protocol.h b/glib/telepathy-glib/base-protocol.h
index 3a8e557e1..9d34be555 100644
--- a/glib/telepathy-glib/base-protocol.h
+++ b/glib/telepathy-glib/base-protocol.h
@@ -221,7 +221,7 @@ struct _TpProtocolAddressingInterface {
 
   TpBaseProtocolNormalizeVCardAddressFunc normalize_vcard_address;
 
-  TpBaseProtocolNormalizeURIFunc normalize_uri;
+  TpBaseProtocolNormalizeURIFunc normalize_contact_uri;
 };
 
 GType tp_protocol_addressing_get_type (void) G_GNUC_CONST;