diff options
Diffstat (limited to 'spec/Call_Content_Interface_Media.xml')
| -rw-r--r-- | spec/Call_Content_Interface_Media.xml | 145 |
1 files changed, 84 insertions, 61 deletions
diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 8b9a17c..24811fd 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Call_Content_Interface_Media" 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 @@ -23,65 +23,85 @@ <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content"/> + <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Interface to use by a software implementation of media streaming. + <p>Interface to use by a software implementation of media + streaming. The reason behind splitting the members of this + interface out from the main <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> interface is + that the software is not necessarily what controls the + media. An example of this is in GSM phones, where the CM just + tells the phone to dial a number and it does the audio routing + in a device specific hardware way and the CM does not need + to concern itself with codecs.</p> + + <p>On new <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels, + handlers should wait for <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + objects to appear (one will either already be present, or will + appear at some point in the channel's lifetime).</p> + + <p>If the Call is incoming, then the codec offer's <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + will already be filled with the codec information of the + remote contacts. Depending on the protocol, an outgoing call's + <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + will either be filled with remote contact codec information, or + it will be empty. If empty, then this SHOULD be interpreted to + mean that all codecs are supported. Once a compatible list of + codecs has been decided, <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref> + should be called with the details of these codecs.</p> - FIXME: How should the streaming implementation know when it is its turn - to set the codecs. </tp:docstring> <tp:struct name="Codec" array-name="Codec_List"> <tp:docstring> A description of a codec. </tp:docstring> - <tp:member name="Identifier" type="u"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Numeric identifier for the codec. This will be used as the PT in the SDP or content description. </tp:docstring> </tp:member> - <tp:member name="Name" type="s"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The name of the codec. </tp:docstring> </tp:member> - <tp:member name="Clockrate" type="u"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The clockrate of the codec + The clockrate of the codec. </tp:docstring> </tp:member> <tp:member name="Channels" type="u"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Number of channels of the codec if applicable, otherwise 0 + Number of channels of the codec if applicable, otherwise 0. </tp:docstring> </tp:member> - <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Extra parameters for this codec + Extra parameters for this codec. </tp:docstring> </tp:member> </tp:struct> <tp:mapping name="Contact_Codec_Map"> <tp:docstring> - A map from contacts to the lists of codecs they support. + A map from contact to the list of codecs he or she supports. </tp:docstring> - <tp:member name="Handle" type="u" tp:type="Contact_Handle"> <tp:docstring> - A contact + A contact handle. </tp:docstring> </tp:member> - <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> <tp:docstring> - The codecs that the contact supports + The codecs that the contact supports. </tp:docstring> </tp:member> </tp:mapping> @@ -90,20 +110,17 @@ <tp:docstring> A codec offer and its corresponding remote contact codec map. </tp:docstring> - <tp:member name="Codec_Offer" type="o"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The object path to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> + The object path to the <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> </tp:docstring> </tp:member> - <tp:member name="Remote_Contact_Codec_Map" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property + The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property of the codec offer. </tp:docstring> </tp:member> @@ -118,16 +135,15 @@ signal implies that the <tp:member-ref>CodecOffer</tp:member-ref> property has changed to <code>('/', {})</code>.</p> </tp:docstring> - <arg name="Updated_Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> <tp:docstring> - A map from contacts to their codecs. Each pair in this map is added - to the <tp:member-ref>ContactCodecMap</tp:member-ref> property, + A map from contact to his or her codecs. Each pair in this + map is added to the + <tp:member-ref>ContactCodecMap</tp:member-ref> property, replacing any previous pair with that key. </tp:docstring> </arg> - <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]"> <tp:docstring> A list of keys which were removed from the @@ -137,17 +153,24 @@ </arg> </signal> - <method name="SetCodecs" tp:name-for-bindings="Set_Codecs"> + <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs"> <tp:docstring> - Set or update the local codec mapping. + Update the local codec mapping. This method should only be + used during an existing call to update the codec mapping. </tp:docstring> - <arg name="Codecs" direction="in" type="a(usuua{ss})" tp:type="Codec[]"> <tp:docstring> The codecs now supported by the local user. </tp:docstring> </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Raised when not used during an existing call to update the codec mapping. + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map" @@ -156,45 +179,44 @@ <p>A map from contact handles (including the local user's own handle) to the codecs supported by that contact.</p> - <p>Change notification is via - <tp:member-ref>CodecsChanged</tp:member-ref>.</p> + <p>Change notification is via the + <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p> </tp:docstring> </property> <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming + <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming implementation MUST respond by calling the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT" - >Accept</tp:dbus-ref> or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT" - >Reject</tp:dbus-ref> method on the codec offer object.</p> + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >Accept</tp:dbus-ref> or <tp:dbus-ref + 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> </tp:docstring> - <arg name="Offer" type="o"> <tp:docstring> The object path of the new codec offer. This replaces any previous codec offer. </tp:docstring> </arg> - <arg name="Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property + <p>The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property of the codec offer.</p> - <tp:rationale> - <p>Having the RemoteContactCodecMap property here saves a D-Bus - round-trip - it shouldn't be necessary to get the property - from the CodecOffer object, in practice.</p> - </tp:rationale> + <tp:rationale> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + property here saves a D-Bus round-trip - it shouldn't be + necessary to get the property from the CodecOffer object, in + practice. + </tp:rationale> </tp:docstring> </arg> </signal> @@ -203,25 +225,26 @@ type="(oa{ua(usuua{ss})})" tp:type="Codec_Offering" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The object path to the current - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> object, and its - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property. + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> object, and its + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property. If the object path is "/" then there isn't an outstanding - codec offer, and the mapping MUST be empty.</p> + codec offer, and the mapping MUST be empty.</p> <tp:rationale> - <p>Having the RemoteContactCodecMap property here saves a D-Bus - round-trip - it shouldn't be necessary to get the property - from the CodecOffer object, in practice.</p> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + property here saves a D-Bus round-trip - it shouldn't be + necessary to get the property from the CodecOffer object, in + practice. </tp:rationale> - <p>Change notification is via + <p>Change notification is via the <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the value of this property with a new codec offer), and <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that - there is no longer any active codec offer).</p> + there is no longer any active codec offer) signals.</p> </tp:docstring> </property> </interface> |