Update spec to 0.21.3

- add TP_ERROR_PICKED_UP_ELSEWHERE

and in the Future:

- replace Members with LocalSendingState and RemoteMembers, and split the
  change-notification signals
- delete the Creator property

1 files changed, 87 insertions, 37 deletions

diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml
index 738564d23..b69398901 100644
--- a/spec/Call_Stream.xml
+++ b/spec/Call_Stream.xml
@@ -25,32 +25,32 @@
     <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">
       <tp:docstring>
         Set the stream to start or stop sending media from the local
-          user to other contacts.
+        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>
 
@@ -94,11 +94,12 @@
       </tp:possible-errors>
     </method>
 
-    <signal name="MembersChanged"
-        tp:name-for-bindings="Members_Changed">
-      <tp:changed version="0.21.2">renamed from SendersChanged</tp: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>Members</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">
@@ -110,21 +111,36 @@
       </arg>
       <arg name="Removed" type="au" tp:type="Contact_Handle[]">
         <tp:docstring>
-          The channel-specific handles that were removed from
-          the keys of the Members 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>
 
@@ -149,18 +165,22 @@
 
     <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="Interfaces" tp:name-for-bindings="Interfaces"
-      type="as" tp:type="DBus_Interface[]" access="read">
+      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
@@ -170,22 +190,16 @@
       </tp:docstring>
     </property>
 
-    <property name="Members" tp:name-for-bindings="Members"
+    <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="ofdT.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 Members 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
@@ -195,8 +209,44 @@
       </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">
+        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