extensions: update to 0.21.2 Call specs

This means gabble doesn't compile anymore.

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

1 files changed, 137 insertions, 41 deletions

diff --git a/extensions/Call_Stream.xml b/extensions/Call_Stream.xml
index 302bd5e9b..b69398901 100644
--- a/extensions/Call_Stream.xml
+++ b/extensions/Call_Stream.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Call_Stream"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
       modify it under the terms of the GNU Lesser General Public
@@ -25,36 +25,43 @@
     <tp:added version="0.19.0">(draft 1)</tp:added>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      One stream inside a content
-      FIXME, direction should be a mapping of contact -> (bool)sending ?
+      One stream inside a <tp:dbus-ref
+      namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
     </tp:docstring>
 
     <method name="SetSending" tp:name-for-bindings="Set_Sending">
-      <p>Set the stream to start or stop sending media from the local
-        user to other contacts.</p>
+      <tp:docstring>
+        Set the stream to start or stop sending media from the local
+        user to other contacts.
+      </tp:docstring>
 
       <arg name="Send" type="b" direction="in">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>If true, the local user's sending state should change
-            to Sending, if it isn't already.</p>
+          <p>If True, the
+            <tp:member-ref>LocalSendingState</tp:member-ref> should
+            change to <tp:type>Sending_State</tp:type>_Sending, if it isn't
+            already.</p>
 
-          <p>If false, the local user's sending state should change to None,
-            if it isn't already.</p>
+          <p>If False, the
+            <tp:member-ref>LocalSendingState</tp:member-ref> should
+            change to <tp:type>Sending_State</tp:type>_None, if it isn't
+            already.</p>
         </tp:docstring>
       </arg>
 
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
-          <tp:docstring>
-            [FIXME: when?]
-          </tp:docstring>
-        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" />
       </tp:possible-errors>
     </method>
 
     <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving">
       <tp:docstring>
-        Request that a remote contact stops or starts sending on this stream.
+        <p>Request that a remote contact stops or starts sending on
+          this stream.</p>
+
+        <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref>
+          property defines whether the protocol allows the local user to
+          request the other side start sending on this stream.</p>
       </tp:docstring>
 
       <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
@@ -71,44 +78,69 @@
       </arg>
 
       <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The request contact is valid but is not involved in this
+            stream.
+          </tp:docstring>
+        </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
           <tp:docstring>
-            [FIXME: when?]
+            The protocol does not allow the local user to request the
+            other side starts sending on this stream.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
     </method>
 
-    <signal name="SendersChanged"
-        tp:name-for-bindings="Senders_Changed">
+    <signal name="RemoteMembersChanged"
+        tp:name-for-bindings="Remote_Members_Changed">
+      <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed>
+      <tp:changed version="0.21.UNRELEASED">renamed from MembersChanged to RemoteMembersChanged</tp:changed>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        Emitted when <tp:member-ref>Senders</tp:member-ref> changes.
+        Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes.
       </tp:docstring>
 
       <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map">
         <tp:docstring>
           A mapping from channel-specific handles to their updated sending
-          state, whose keys include at least the senders who were added,
-          and the senders whose states changed.
+          state, whose keys include at least the members who were added,
+          and the members whose states changed.
         </tp:docstring>
       </arg>
       <arg name="Removed" type="au" tp:type="Contact_Handle[]">
         <tp:docstring>
-          The channel-specific handles that were removed from
-          the keys of the Senders property, as a result of the
-          contact leaving this stream
+          The channel-specific handles that were removed from the keys
+          of the <tp:member-ref>RemoteMembers</tp:member-ref>
+          property, as a result of the contact leaving this stream
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="LocalSendingStateChanged"
+        tp:name-for-bindings="Local_Sending_State_Changed">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes.
+      </tp:docstring>
+
+      <arg name="State" type="u" tp:type="Sending_State">
+        <tp:docstring>
+          The new value of
+          <tp:member-ref>LocalSendingState</tp:member-ref>.
         </tp:docstring>
       </arg>
     </signal>
 
     <tp:enum name="Sending_State" type="u">
       <tp:docstring>
-        Tristate indicating whether a contact is sending media.
+        Enum indicating whether a contact is sending media.
       </tp:docstring>
 
       <tp:enumvalue suffix="None" value="0">
         <tp:docstring>
-          The contact is not sending media and has not been asked to do so.
+          The contact is not sending media and has not been asked to
+          do so.
         </tp:docstring>
       </tp:enumvalue>
 
@@ -123,35 +155,51 @@
           The contact is sending media.
         </tp:docstring>
       </tp:enumvalue>
+
+      <tp:enumvalue suffix="Pending_Stop_Sending" value="3">
+        <tp:docstring>
+          The contact has been asked to stop sending media.
+        </tp:docstring>
+      </tp:enumvalue>
     </tp:enum>
 
     <tp:mapping name="Contact_Sending_State_Map">
       <tp:docstring>
-        A map from contacts to their sending state.
+        A map from a contact to his or her sending state.
       </tp:docstring>
       <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The contact handle.
+        </tp:docstring>
       </tp:member>
       <tp:member name="Sending" type="u" tp:type="Sending_State">
          <tp:docstring>
+           The sending state of the contact.
          </tp:docstring>
       </tp:member>
     </tp:mapping>
 
-    <property name="Senders" tp:name-for-bindings="Senders"
+    <property name="Interfaces" tp:name-for-bindings="Interfaces"
+      type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+      <tp:added version="0.19.11"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Extra interfaces provided by this stream, such as <tp:dbus-ref
+            namespace="ofdT.Call">Stream.Interface.Media.DRAFT</tp:dbus-ref>.
+          This SHOULD NOT include the Stream interface itself, and cannot
+          change once the stream has been created.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="RemoteMembers" tp:name-for-bindings="Remote_Members"
         type="a{uu}" access="read" tp:type="Contact_Sending_State_Map">
+      <tp:changed version="0.21.2">renamed from Senders</tp:changed>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>A map from contacts to their sending state.</p>
-
-        <p>The local user's handle in this map (the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Channel.Interface"
-            >Group.SelfHandle</tp:dbus-ref> if the channel implements
-          Group, or the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy"
-            >Connection.SelfHandle</tp:dbus-ref> otherwise) indicates
-          whether the local user is sending media. Media sent on this stream
-          should be assumed to be received, directly or indirectly, by every
-          other contact in the Senders mapping. Sending_State_Pending_Send
-          indicates that another contact has asked the local user to send
+        <p>A map from remote contacts to their sending state. The
+          local user's sending state is shown in
+          <tp:member-ref>LocalSendingState</tp:member-ref>.</p>
+
+        <p><tp:type>Sending_State</tp:type>_Pending_Send indicates
+          that another contact has asked the local user to send
           media.</p>
 
         <p>Other contacts' handles in this map indicate whether they are
@@ -160,6 +208,54 @@
           have been asked to do so.</p>
       </tp:docstring>
     </property>
+
+    <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State"
+        type="u" access="read" tp:type="Sending_State">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The local user's sending state. Media sent on this stream
+          should be assumed to be received, directly or indirectly, by
+          every other contact in the
+          <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change
+          notification is given via the
+          <tp:member-ref>LocalSendingStateChanged</tp:member-ref>
+          signal.</p>
+
+        <tp:rationale>
+          Implementations of the first Call draft had the self handle
+          in the <tp:member-ref>RemoteMembers</tp:member-ref> (then
+          called Members) map and this showed that it's annoying
+          having to keep track of the self handle so that it can be
+          special-cased.
+        </tp:rationale>
+
+        <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for
+          this property indicates that the other side requested the
+          local user start sending media, which can be done by calling
+          <tp:member-ref>SetSending</tp:member-ref>. When a call is
+          accepted, all initial contents with streams that have a
+          local sending state of
+          <tp:type>Sending_State</tp:type>_Pending_Send are
+          automatically set to sending. For example, on an incoming
+          call it means you need to <tp:dbus-ref
+          namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+          to start the actual call, on an outgoing call it might mean
+          you need to call <tp:dbus-ref
+          namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+          before actually starting the call.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving"
+        type="b" access="read" tp:immutable="yes">
+      <tp:added version="0.21.2"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>If true, the user can request that a remote contact starts
+          sending on this stream.</p>
+
+        <tp:rationale>Not all protocols allow the user to ask the
+          other side to start sending media.</tp:rationale>
+      </tp:docstring>
+    </property>
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->