Split requested contacts into a separate argument in Conn.I.Addressing.

Remove the contact attributes ".../requested-*" and return the satisfied requested
addresses on GetContactsByURI/VCardField.

Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>

1 files changed, 38 insertions, 51 deletions

diff --git a/spec/spec/Connection_Interface_Addressing.xml b/spec/spec/Connection_Interface_Addressing.xml
index 9e01c1837..db8155f23 100644
--- a/spec/spec/Connection_Interface_Addressing.xml
+++ b/spec/spec/Connection_Interface_Addressing.xml
@@ -76,7 +76,18 @@
           </tp:docstring>
       </arg>
 
-      <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts"
+      <arg direction="out" type="a{su}" name="Requested"
+           tp:type="Addressing_Normalization_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A mapping from requested vCard addresses to the corresponding
+            contact handles.</p>
+
+          <p>Requested addresses that are not valid or understood for this protocol
+            MUST be omitted from the mapping.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" type="a{ua{sv}}" name="Attributes"
            tp:type="Contact_Attributes_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>A dictionary mapping the contact handles to contact attributes.
@@ -86,14 +97,12 @@
             the attribute should either be omitted from the result or
             replaced with a default value.</p>
 
-          <p>Requested addresses that cannot be satisfied MUST be ommitted
-            from the mapping.</p>
+          <p>Requested addresses that are not valid or understood for this protocol
+            MUST be omitted from the mapping.</p>
 
           <p>Each contact's attributes will always include at least the
             identifier that would be obtained by inspecting the handle
-            (<code>org.freedesktop.Telepathy.Connection/contact-id</code>),
-          and the vCard field used for requesting the contact in
-            <code>org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info</code>.
+            (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).
           </p>
         </tp:docstring>
       </arg>
@@ -143,7 +152,17 @@
           </tp:docstring>
       </arg>
 
-      <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts"
+      <arg direction="out" type="a{su}" name="Requested"
+           tp:type="Addressing_Normalization_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A mapping of requested URIs to the corresponding contact handles.</p>
+
+          <p>Requested URIs that are not valid or understood for this protocol
+            MUST be omitted from the mapping.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" type="a{ua{sv}}" name="Attributes"
            tp:type="Contact_Attributes_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>A dictionary mapping the contact handles to contact attributes.
@@ -153,8 +172,8 @@
             the attribute should either be omitted from the result or
             replaced with a default value.</p>
 
-          <p>Requested URIs that cannot be satisfied MUST be ommitted
-            from the mapping.</p>
+          <p>Requested URIs that are not valid or understood for this protocol
+            MUST be omitted from the mapping.</p>
 
           <p>Each contact's attributes will always include at least the
             identifier that would be obtained by inspecting the handle
@@ -201,57 +220,25 @@
       </tp:docstring>
     </tp:contact-attribute>
 
-    <tp:contact-attribute name="requested-address" type="(ss)"
-                          tp:type="Requested_Address">
-      <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>. This
-        attribute MUST be ommitted if the contact was not retrieved
-        through <tp:member-ref>GetContactsByVCardField</tp:member-ref>.</p>
-      <tp:rationale>
-        <p>When retrieving more than one contact
-          through <tp:member-ref>GetContactsByVCardField</tp:member-ref>,
-          there needs to be a way to map the given contact back o the
-          original request.</p>
-      </tp:rationale>
-      </tp:docstring>
-    </tp:contact-attribute>
-
-    <tp:contact-attribute name="requested-uri" type="s">
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The contact's URI, as it was requested through
-        <tp:member-ref>GetContactsByURI</tp:member-ref>. This
-        attribute MUST be ommitted if the contact was not retrieved
-        through <tp:member-ref>GetContactsByURI</tp:member-ref>.</p>
-      <tp:rationale>
-        <p>When retrieving more than one contact
-        through <tp:member-ref>GetContactsByURI</tp:member-ref>,
-        there needs to be a way to map the given contact back o the
-        original request.</p>
-      </tp:rationale>
-      </tp:docstring>
-    </tp:contact-attribute>
-
-    <tp:struct name="Requested_Address" array-name="">
+    <tp:mapping name="Addressing_Normalization_Map">
       <tp:docstring>
-        The address that has been requested by
-        <tp:member-ref>GetContactsByVCardField</tp:member-ref> or
-        <tp:member-ref>GetContactsByURI</tp:member-ref>.
+        A map from URIs/vCard addresses to the corresponding handle.
       </tp:docstring>
+      <tp:added version="0.25.UNRELEASED"/>
 
-      <tp:member name="Field" type="s">
+      <tp:member type="s" name="Requested_String">
         <tp:docstring>
-          The vCard field used in <tp:member-ref>GetContactsByVCardField</tp:member-ref>.
+        The URI or vCard address that has been requested by
+        <tp:member-ref>GetContactsByVCardField</tp:member-ref> or
+        <tp:member-ref>GetContactsByURI</tp:member-ref>.
         </tp:docstring>
       </tp:member>
-
-      <tp:member name="Address" type="s">
+      <tp:member type="u" name="Handle" tp:type="Contact_Handle">
         <tp:docstring>
-          The address that was requested.
+          A nonzero handle.
         </tp:docstring>
       </tp:member>
-
-    </tp:struct>
+    </tp:mapping>
 
   </interface>
 </node>