Update to telepathy-spec 0.24.0

This also includes the updates to the Call-based example code omitted
from fa81060.

1 files changed, 60 insertions, 30 deletions

diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml
index 1d7b28147..2693f5305 100644
--- a/spec/Call_Stream.xml
+++ b/spec/Call_Stream.xml
@@ -20,13 +20,16 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="org.freedesktop.Telepathy.Call.Stream.DRAFT"
+  <interface name="org.freedesktop.Telepathy.Call1.Stream"
       tp:causes-havoc="experimental">
     <tp:added version="0.19.0">(draft 1)</tp:added>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       One stream inside a <tp:dbus-ref
-      namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
+      namespace="ofdT.Call1">Content</tp:dbus-ref>.  A stream is
+      a single flow of packets to and from a single remote endpoint.
+      If your call connects to multiple people, you could have
+      multiple streams.
     </tp:docstring>
 
     <method name="SetSending" tp:name-for-bindings="Set_Sending">
@@ -39,18 +42,24 @@
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <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
+            change to <tp:value-ref type="Sending_State">Sending</tp:value-ref>, 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
+            change to <tp:value-ref type="Sending_State">None</tp:value-ref>, if it isn't
             already.</p>
         </tp:docstring>
       </arg>
 
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" />
+        <tp:error name="org.freedesktop.Telepathy.Error.NotYet">
+          <tp:docstring>If the call has not been accepted yet, calling
+            SetSending(True) is an error. See
+            <tp:member-ref>LocalSendingState</tp:member-ref> for details.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
 
@@ -116,6 +125,11 @@
           property, as a result of the contact leaving this stream
         </tp:docstring>
       </arg>
+      <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason">
+        <tp:docstring>
+          A structured reason for the change.
+        </tp:docstring>
+      </arg>
     </signal>
 
     <signal name="LocalSendingStateChanged"
@@ -130,6 +144,12 @@
           <tp:member-ref>LocalSendingState</tp:member-ref>.
         </tp:docstring>
       </arg>
+
+      <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason">
+        <tp:docstring>
+          A structured reason for the change.
+        </tp:docstring>
+      </arg>
     </signal>
 
     <tp:enum name="Sending_State" type="u">
@@ -184,7 +204,7 @@
       <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>.
+            namespace="ofdT.Call1">Stream.Interface.Media</tp:dbus-ref>.
           This SHOULD NOT include the Stream interface itself, and cannot
           change once the stream has been created.</p>
       </tp:docstring>
@@ -194,18 +214,28 @@
         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 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
-          sending media to the contacts in this stream.
-          Sending_State_Pending_Send indicates contacts who are not sending but
-          have been asked to do so.</p>
+        <p>A map from remote contacts to their sending state.</p>
+
+        <p>Media sent to this stream will be sent to all members listed here.
+          All members listed here will also appear in <tp:dbus-ref
+          namespace="ofdT.Channel.Type.Call1">CallMembers</tp:dbus-ref>,
+          and each CallMembers member will be listed in at most one Stream per
+          Content. Therefore, to hide things from a member of the
+          call, UIs only need to mute one Stream per Content.</p>
+
+        <p>Contacts' handles in this map indicate whether they are
+          sending media to this stream. Sending_State_Pending_Send indicates
+          contacts who are not sending but have been asked to do so. The
+          local user's sending state is shown in <tp:member-ref
+          >LocalSendingState</tp:member-ref>.</p>
+
+        <p>This mapping is also used by the streaming implementation to map
+          from <tp:dbus-ref namespace="ofdT.Call1.Content"
+          >MediaDescription</tp:dbus-ref>s to Streams. In this use-case,
+          all of the senders in this stream will be represented in
+          <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media"
+          >RemoteMediaDescriptions</tp:dbus-ref>. This use-case should not
+          affect anything that does not handle media streaming.</p>
       </tp:docstring>
     </property>
 
@@ -228,20 +258,20 @@
           special-cased.
         </tp:rationale>
 
-        <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for
+        <p>A value of <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> 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>
+          local user start sending media (which can be done by calling either
+          <tp:member-ref>SetSending</tp:member-ref> or <tp:dbus-ref
+          namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref>).</p>
+
+        <p>When <tp:dbus-ref
+          namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref> is
+          called, all streams with a local sending state of
+          <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> and the associated
+          <tp:dbus-ref namespace="ofdT.Call1.Content"
+          >Disposition</tp:dbus-ref> set to
+          <tp:value-ref type="Call_Content_Disposition">Initial</tp:value-ref> are
+          automatically set to sending.</p>
       </tp:docstring>
     </property>