fd.o #20903: ContactCapabilities: update draft from telepathy-spec 0.17.26

This requires that Requestable_Channel_Class is added to all.xml as an
externally-defined type.

Incompatible changes in ContactCapabilities, none of which actually affect
MC:

* ContactCapabilitiesChanged acts on multiple contacts (but MC never
  connects to this signal)
* Contact_Handle_Enhanced_Contact_Capability_Map renamed to
  Contact_Capabilities_Map (but MC never mentions this type by name, and
  the D-Bus signature is the same)
* Enhanced_Contact_Capability is replaced by the Requestable_Channel_Class
  type first defined in Requests (but MC never mentions this type by
  name, and the D-Bus signature is the same)

2 files changed, 44 insertions, 48 deletions

diff --git a/xml/Connection_Interface_Contact_Capabilities.xml b/xml/Connection_Interface_Contact_Capabilities.xml
index 4d1d6320..042b24be 100644
--- a/xml/Connection_Interface_Contact_Capabilities.xml
+++ b/xml/Connection_Interface_Contact_Capabilities.xml
@@ -18,13 +18,15 @@ Lesser General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT"
+    tp:causes-havoc="experimental">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <tp:added version="0.17.16">(as a draft)</tp:added>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>An interface to get contact capabilities in order to know what channel
-        classes may be created with a contact before the request is made to the
-        connection object. Each capability represents a commitment by the
+      <p>Contact capabilities describe the channel classes which may be
+        created with a given contact in advance of attempting to create a
+        channel. Each capability represents a commitment by the
         connection manager that it will ordinarily be able to create a channel
         with a contact when given a request with the properties defined by the
         channel class.</p>
@@ -35,9 +37,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
       <p>This interface also enables user interfaces to notify the connection
         manager what capabilities to advertise for the user to other contacts.
-        This is done by using the SetSelfCapabilities method, and deals with
-        channel properties values pertaining to them which are implemented by
-        available client processes.</p>
+        This is done by using the
+        <tp:member-ref>SetSelfCapabilities</tp:member-ref> method, and deals
+        with channel property values pertaining to them which are implemented
+        by available client processes.</p>
 
     </tp:docstring>
 
@@ -47,7 +50,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
            tp:type="String_Variant_Map[]">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           An array of channel classes to replace to the list of what the
-          connection can handle
+          connection can handle. If you include optional properties, they
+          may not get advertised. The given properties are matched to the
+          mandatory properties.
         </tp:docstring>
       </arg>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -60,9 +65,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         class are added.</p>
 
         <p>Upon a successful invocation of this method, the
-        ContactCapabilitiesChanged signal will be emitted for the user's own
-        handle (as returned by GetSelfHandle) by the connection manager to
-        indicate the changes that have been made.</p>
+        <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
+        will only be emitted for the user's own
+        handle (as returned by GetSelfHandle) by the connection manager if, in
+        the given protocol, the given capabilities are distinct from the
+        previous state.</p>
+
+        <tp:rationale>
+          <p>The connection manager will essentially intersect the provided
+            capabilities and the channel classes it implements. Therefore,
+            certain properties which are never fixed for a channel class
+            (such as the target handle, or the Parameters property of a tube
+            channel) will almost certainly not be advertised.</p>
+        </tp:rationale>
+
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
@@ -85,7 +101,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
            Now there is a fix, so we don't use the workaround anymore.
         -->
       <arg direction="out" type="a{ua(a{sv}as)}"
-           tp:type="Contact_Handle_Enhanced_Contact_Capability_Map">
+           tp:type="Contact_Capabilities_Map" name="Contact_Capabilities">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           An array of structures containing:
           <ul>
@@ -109,49 +125,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
     <signal name="ContactCapabilitiesChanged"
             tp:name-for-bindings="Contact_Capabilities_Changed">
-      <arg name="handle" type="u" tp:type="Contact_Handle">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>A contact handle.</p>
-        </tp:docstring>
-      </arg>
-      <arg name="caps" type="a(a{sv}as)"
-           tp:type="Enhanced_Contact_Capability[]">
+      <arg name="caps" type="a{ua(a{sv}as)}"
+           tp:type="Contact_Capabilities_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          All the capabilities of the contact
+          All the capabilities of the contacts
         </tp:docstring>
       </arg>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Announce that there has been a change of capabilities on the
-          given handle.</p>
-      </tp:docstring>
-    </signal>
+          given handles. A single signal can be emitted for several
+        contacts.</p>
+
+        <tp:rationale>
+          <p>The underlying protocol can get several contacts' capabilities at
+            the same time.</p>
+        </tp:rationale>
 
-    <tp:struct name="Enhanced_Contact_Capability"
-               array-name="Enhanced_Contact_Capability_List">
-      <tp:docstring>
-        A struct representing a capability posessed by a contact,
-        as returned by GetContactCapabilities on the ContactCapabilities
-        interface. The channel creation will succeed if the request contains
-        all the Fixed_Properties will the values specified in this struct. The
-        request can contain additional properties from Allowed_Properties. If
-        the request contains a property which does not belong to
-        Fixed_Properties nor to Allowed_Properties, the request will fail.
       </tp:docstring>
-      <tp:member type="a{sv}" tp:type="Channel_Class"
-                 name="Fixed_Properties">
-        <tp:docstring>
-          A dictionary mapping the channel properties to their values.
-        </tp:docstring>
-      </tp:member>
-      <tp:member type="as" name="Allowed_Properties">
-        <tp:docstring>
-          An array of additional allowed properties.
-        </tp:docstring>
-      </tp:member>
-    </tp:struct>
+    </signal>
 
-  <tp:mapping name="Contact_Handle_Enhanced_Contact_Capability_Map"
-              array-name="Contact_Handle_Enhanced_Contact_Capability_Map_List">
+  <tp:mapping name="Contact_Capabilities_Map"
+              array-name="Contact_Capabilities_Map_List">
     <tp:docstring>A mapping from contact handle to their capabilities.
     </tp:docstring>
     <tp:member type="u" name="Key" tp:type="Contact_Handle">
@@ -160,7 +154,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:docstring>
     </tp:member>
     <tp:member type="a(a{sv}as)" name="Value"
-               tp:type="Enhanced_Contact_Capability[]">
+               tp:type="Requestable_Channel_Class[]">
       <tp:docstring>
         The contact capabilities.
       </tp:docstring>
diff --git a/xml/all.xml b/xml/all.xml
index e70c2db2..96dc6c43 100644
--- a/xml/all.xml
+++ b/xml/all.xml
@@ -23,6 +23,8 @@
 	from="Telepathy specification (SimplePresence)"/>
     <tp:external-type name="Conn_Mgr_Param_Flags" type="u"
 	from="Telepathy specification (ConnectionManager)"/>
+    <tp:external-type name="Requestable_Channel_Class" type="(a{sv}as)"
+      from="Telepathy specification (Requests)"/>
 </tp:generic-types>
 
 <xi:include href="generic-types.xml"/>