Call_Content_I_Media: update to talk about multiple codec offerscodec-offers

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

1 files changed, 47 insertions, 21 deletions

diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml
index 2d023572..33fd88b5 100644
--- a/spec/Call_Content_Interface_Media.xml
+++ b/spec/Call_Content_Interface_Media.xml
@@ -33,21 +33,25 @@
 
       <p>When a new <tp:dbus-ref
         namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel
-        appears, whether it was requested or not, a <tp:dbus-ref
+        appears, whether it was requested or not, one or more <tp:dbus-ref
         namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
-        will either be waiting in the
-        <tp:member-ref>CodecOffer</tp:member-ref> property, or will
+        objects will either be waiting in the
+        <tp:member-ref>CodecOffers</tp:member-ref> mapping, or will
         appear at some point via the
         <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p>
 
       <p>The <tp:dbus-ref
         namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
-        property on the codec offer will determine the codecs that
-        should be proposed by the local user's streaming
-        implementation. An empty list means all codecs are available.</p>
+        property on the codec offer list the codecs which are
+        supported by the remote contact, and so will determine the
+        codecs that should be proposed by the local user's streaming
+        implementation. An empty list means all codecs are
+        supported.</p>
 
       <p>For incoming calls on protocols where codecs are proposed when
-        starting the call (for example, Jingle), the <tp:dbus-ref
+        starting the call (for example, <a
+        href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>),
+        the <tp:dbus-ref
         namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
         will contain information on the codecs that have already been
         proposed by the remote contact, otherwise the codec map will
@@ -153,7 +157,7 @@
       </tp:member>
     </tp:mapping>
 
-    <tp:struct name="Codec_Offering">
+    <tp:struct name="Codec_Offering" array-name="Codec_Offering_List">
       <tp:docstring>
         A codec offer and its corresponding remote contact codec map.
       </tp:docstring>
@@ -179,8 +183,8 @@
 
         <p>As well as acting as change notification for the
           <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this
-          signal implies that the <tp:member-ref>CodecOffer</tp:member-ref>
-          property has changed to <code>('/', {})</code>.</p>
+          signal implies that the <tp:member-ref>CodecOffers</tp:member-ref>
+          property has changed to the empty list.</p>
       </tp:docstring>
       <arg name="Updated_Codecs" type="a{ua(usuua{ss})}"
         tp:type="Contact_Codec_Map">
@@ -217,7 +221,7 @@
             Raised when a <tp:dbus-ref
             namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
             object exists and is referred to in the
-            <tp:member-ref>CodecOffer</tp:member-ref> property which
+            <tp:member-ref>CodecOffers</tp:member-ref> property which
             should be used instead of calling this method, or before
             the content's initial <tp:dbus-ref
             namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
@@ -248,10 +252,15 @@
           namespace="ofdT.Call.Content.CodecOffer.DRAFT"
           >Reject</tp:dbus-ref> method on the codec offer object.</p>
 
-        <p>Emission of this signal indicates that the
-          <tp:member-ref>CodecOffer</tp:member-ref> property has changed to
-          <code>(Offer, Codecs)</code>.</p>
+        <p>Emission of this signal indicates that the a new (Contact,
+          Offer, Codecs) element has been added to the
+          <tp:member-ref>CodecOffers</tp:member-ref> property.</p>
       </tp:docstring>
+      <arg name="Contact" type="u">
+        <tp:docstring>
+          The contact the codec offer belongs to.
+        </tp:docstring>
+      </arg>
       <arg name="Offer" type="o">
         <tp:docstring>
           The object path of the new codec offer. This replaces any previous
@@ -275,16 +284,33 @@
       </arg>
     </signal>
 
-    <property name="CodecOffer" tp:name-for-bindings="Codec_Offer"
-      type="(oa{ua(usuua{ss})})" tp:type="Codec_Offering" access="read">
+    <tp:mapping name="Contact_Codec_Offering_Map">
+      <tp:docstring>
+        A map from contact to codec offering.
+      </tp:docstring>
+      <tp:member name="Handle" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          A contact handle.
+        </tp:docstring>
+      </tp:member>
+      <tp:member name="Codec_Offering" type="(oa{ua(usuua{ss})})"
+        tp:type="Codec_Offering[]">
+        <tp:docstring>
+          The codec offering for the contact.
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <property name="CodecOffers" tp:name-for-bindings="Codec_Offers"
+      type="a{u(oa{ua(usuua{ss})})}" tp:type="Contact_Codec_Offering_Map"
+      access="read">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The object path to the current
           <tp:dbus-ref namespace="ofdT.Call.Content"
-            >CodecOffer.DRAFT</tp:dbus-ref> object, and its
-            <tp:dbus-ref namespace="ofdT.Call.Content"
-            >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property.
-            If the object path is "/" then there isn't an outstanding
-            codec offer, and the mapping MUST be empty.</p>
+          >CodecOffer.DRAFT</tp:dbus-ref> objects, and their
+          <tp:dbus-ref namespace="ofdT.Call.Content"
+          >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties.
+          An empty list means there are no outstanding codec offers.</p>
 
         <tp:rationale>
           Having the <tp:dbus-ref