diff options
Diffstat (limited to 'spec/spec/Call_Content_Interface_Media.xml')
| -rw-r--r-- | spec/spec/Call_Content_Interface_Media.xml | 581 |
1 files changed, 581 insertions, 0 deletions
diff --git a/spec/spec/Call_Content_Interface_Media.xml b/spec/spec/Call_Content_Interface_Media.xml new file mode 100644 index 000000000..ca5ed36bf --- /dev/null +++ b/spec/spec/Call_Content_Interface_Media.xml @@ -0,0 +1,581 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Interface_Media" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <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 + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Call1.Content.Interface.Media" + tp:causes-havoc="experimental"> + <tp:added version="0.23.4">(draft 2)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call1.Content"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <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.Call1">Content</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> + + <h4>Codec Negotiation</h4> + + <p>When a new <tp:dbus-ref + namespace="ofdT.Channel.Type">Call1</tp:dbus-ref> channel + appears (whether it was requested or not) a <tp:dbus-ref + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> + object will either be waiting in the + <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property, or will + appear at some point via the + <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> signal.</p> + + <p>If nothing is known about the remote side's Media capabilities + (e.g. outgoing SIP/XMPP call), this <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> will pop up with {<tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >HasRemoteInformation</tp:dbus-ref> = false, <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> = true}, and the local + user's streaming implementation SHOULD call + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref>, + with a description of all supported codecs and other features. + The CM will then send this information to the remote side (and + <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> will fire + with details of the description passed into <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref> for debugging purposes). + </p> + <p>When the remote codecs and other content information are available + (e.g. Remote user replies to initial offer, or sends a new offer of + their own, a new <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> will appear, with {<tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >HasRemoteInformation</tp:dbus-ref> = true, <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> = false}, + and the <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Codecs</tp:dbus-ref> + property on the description offer set to the codecs which are + supported by the remote contact. The local user's streaming + implementation SHOULD then call Accept, with a description + that is compatible with the one one in the offer. After the codec + set is accepted, both + <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> and + <tp:member-ref>RemoteMediaDescriptionsChanged</tp:member-ref> + will fire to signal their respective changes, to aid with debugging. + Note that if <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref> is called, with <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> set to false, + the CM should be able to rely on the fact that the + description passed into Accept is compatible with the one in the + offer, and the description passed into Accept will not be signalled to + the remote side. + </p> + + <h4>Changing codecs mid-call</h4> + + <p>To update the codecs in the local (and optionally remote) media + descriptions mid-call, the + <tp:member-ref>UpdateLocalMediaDescription</tp:member-ref> method + should be called with details of the new codec list. If this is + accepted, then + <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> + will be emitted with the new codec set. + </p> + <p> If parameters requiring negotiation are changed, then the + <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> property should be set to + TRUE, and the new media description should + only be used once they come in a new MediaDescriptionOffer + </p> + + <p>If the other side decides to update his or her codec list + during a call, a new <tp:dbus-ref + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> + object will appear through + <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> which should be + acted on as documented above.</p> + + <h4>Protocols without negotiation</h4> + + <p>For protocols where the codecs are not negotiable, the initial content's <tp:dbus-ref + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> + object will appear with <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >HasRemoteInformation</tp:dbus-ref>, + set to true and the known supported codec values in <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Codecs</tp:dbus-ref>. + </p> + </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. + </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. + </tp:docstring> + </tp:member> + <tp:member name="Updated" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This should be set to true in calls to <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref> and + <tp:member-ref>UpdateLocalMediaDescription</tp:member-ref> if this + codec has changed in a way that needs to be signalled over the + network. If it is set to false, the CM is allowed ignore any + differences between the current parameters and the previous ones + <tp:rationale> + This mechanism may be used to save bandwidth and avoid the CM + having to calculate diffs against previous versions of this + struct, which can lead to false-positives (e.g. redundant ptime + updates). + </tp:rationale> + </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. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Contact_Codec_Map"> + <tp:docstring> + 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 handle. + </tp:docstring> + </tp:member> + <tp:member name="Codecs" type="a(usuuba{ss})" tp:type="Codec[]"> + <tp:docstring> + The codecs that the contact supports. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:mapping name="Contact_Media_Description_Properties_Map"> + <tp:member name="Remote_Contact" type="u" tp:type="Handle"> + <tp:docstring> + The remote contact this description refers to or 0. This matches the + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >RemoteContact</tp:dbus-ref> property on + <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> + </tp:docstring> + </tp:member> + <tp:member name="Media_Description_Properties" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring> + The properties of the description + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Media_Description_Offer"> + <tp:docstring> + The remote description offer and its information + </tp:docstring> + <tp:member name="Media_Description" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The object path to the <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> + </tp:docstring> + </tp:member> + <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The contact handle that this description applies to. + </tp:docstring> + </tp:member> + <tp:member name="Properties" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring> + The immutable properties of all interfaces of the codec description. + + <tp:rationale> + Having all the codec description properties here saves a D-Bus + round-trip - it shouldn't be necessary to get the properties from the + MediaDescription object, in practice. + </tp:rationale> + </tp:docstring> + </tp:member> + </tp:struct> + + <method name="UpdateLocalMediaDescription" + tp:name-for-bindings="Update_Local_Media_Description"> + <tp:docstring> + Update the local codec mapping and other interfaces of the + MediaDescription. This method should only be + used during an existing call to update the local media description. + This may trigger a re-negotiation which may result in new + new MediaDescriptionOffers if the "FurtherNegotiationRequired" + property is TRUE. + Otherwise, only parameters which strictly describe the media being sent + can be changed. + </tp:docstring> + <arg name="Remote_Contact" type="u" tp:type="Handle" direction="in"> + <tp:docstring> + The remote contact that this description should be negotiated with + (or 0 to mean "negotiate this with everyone"). Note that encoding + the same video multiple times is often needlessly expensive, so + differences in MediaDescriptions negotiated with different parties + in the call should be limited to payloading parameters if possible. + </tp:docstring> + </arg> + <arg name="MediaDescription" direction="in" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring> + The updated media description that the local side wants to use. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The protocol does not support changing the codecs mid-call. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The description given is invalid in some way. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="RemoteMediaDescriptions" + tp:name-for-bindings="Remote_Media_Descriptions" + type="a{ua{sv}}" + tp:type="Contact_Media_Description_Properties_Map" access="read"> + <tp:docstring> + <p>A map from contact handles to descriptions supported by that + contact.</p> + + <p>Keys of this map will appear in at most one <tp:dbus-ref + namespace="ofdT.Call1.Stream">RemoteMembers</tp:dbus-ref>. + See <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >RemoteContact</tp:dbus-ref> for more details on how to map between + MediaDescriptions and Streams.</p> + </tp:docstring> + </property> + + <property name="LocalMediaDescriptions" + tp:name-for-bindings="Local_Media_Descriptions" + type="a{ua{sv}}" + tp:type="Contact_Media_Description_Properties_Map" access="read"> + <tp:docstring> + <p>A map from contact handles to the descriptions the local side + responsed with.</p> </tp:docstring> + </property> + + <signal name="NewMediaDescriptionOffer" + tp:name-for-bindings="New_Media_Description_Offer"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> appears. The streaming + >implementation MUST respond by calling the + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref> or <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Reject</tp:dbus-ref> method on the description object appeared.</p> + + <p>Emission of this signal indicates that the + <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property has + changed to + <code>(Description, Contact, MediaDescriptionProperties)</code>.</p> + + <p>When the MediaDescriptionOffer has been dealt with then + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >MediaDescriptionOfferDone</tp:dbus-ref> must be emitted + before <tp:dbus-ref + namespace="ofdT.Call1.Content.Interface.Media" + >NewMediaDescriptionOffer</tp:dbus-ref> is emitted again. + </p> + + </tp:docstring> + <arg name="Media_Description" type="o"> + <tp:docstring> + The object path of the new media description. This replaces any + previous media description. + </tp:docstring> + </arg> + <arg name="Contact" type="u"> + <tp:docstring> + The remote contact the media description belongs to. + </tp:docstring> + </arg> + <arg name="Properties" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring> + The immutable properties of the remote media description. + + <tp:rationale> + Having all the MediaDescription properties here saves a D-Bus + round-trip - it shouldn't be necessary to get the properties from the + MediaDescription object, in practice. + </tp:rationale> + </tp:docstring> + </arg> + </signal> + + <signal name="MediaDescriptionOfferDone" + tp:name-for-bindings="Media_Description_Offer_Done"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> has been handled. </p> + <p>Emission of this signal indicates that the + <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property has + changed to + <code>("/", 0, {})</code>.</p> + </tp:docstring> + </signal> + + + <signal name="LocalMediaDescriptionChanged" + tp:name-for-bindings="Local_Media_Description_Changed"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Change notification for + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >LocalMediaDescriptions</tp:dbus-ref> + </p> + </tp:docstring> + + <arg name="Remote_Contact" type="u" tp:type="Handle"> + <tp:docstring> + The remote contact that this description was negotiated with + (or 0 to mean "negotiated with everyone"). + </tp:docstring> + </arg> + + <arg name="Updated_Media_Description" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The local content description that was updated</p> + </tp:docstring> + </arg> + </signal> + + <signal name="RemoteMediaDescriptionsChanged" + tp:name-for-bindings="Remote_Media_Descriptions_Changed"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Change notification for + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >RemoteMediaDescriptions</tp:dbus-ref> + </p> + </tp:docstring> + + <arg name="Updated_Media_Descriptions" type="a{ua{sv}}" + tp:type="Contact_Media_Description_Properties_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The remote content descriptions that were updated</p> + </tp:docstring> + </arg> + </signal> + + <signal name="MediaDescriptionsRemoved" + tp:name-for-bindings="Media_Descriptions_Removed"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Removal notification for + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >RemoteMediaDescriptions</tp:dbus-ref> + and + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >LocalMediaDescriptions</tp:dbus-ref> + </p> + </tp:docstring> + + <arg name="Removed_Media_Descriptions" type="au" + tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The local and remote content descriptions that are no longer part + of this content</p> + </tp:docstring> + </arg> + </signal> + + <property name="MediaDescriptionOffer" + tp:name-for-bindings="Media_Description_Offer" + type="(oua{sv})" tp:type="Media_Description_Offer" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The object path to the current + <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> object, its + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >RemoteContact</tp:dbus-ref> and + a mapping of the MediaDescriptions properties. + If the object path is "/" then there isn't an outstanding + content description, and the mapping MUST be empty.</p> + + <tp:rationale> + Having all <tp:dbus-ref + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the Content MediaDescription + object, in practice. + </tp:rationale> + + <p>Change notification is via the + <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> and + <tp:member-ref>MediaDescriptionOfferDone</tp:member-ref> signals. + </p> + </tp:docstring> + </property> + + <tp:enum name="Call_Content_Packetization_Type" type="u"> + <tp:added version="0.21.2"/> + <tp:docstring> + A packetization method that can be used for a content. + </tp:docstring> + + <tp:enumvalue suffix="RTP" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Real-time Transport Protocol, as documented by RFC 3550. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Raw" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Raw media. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="MSN_Webcam" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + MSN webcam. This is the video-only one-way type which was + used in earlier versions of WLM. Although no longer used, + modern WLM clients still support the MSN webcam protocol. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Packetization" tp:name-for-bindings="Packetization" + type="u" tp:type="Call_Content_Packetization_Type" access="read" + tp:immutable="yes"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The packetization method in use for this content.</p> + </tp:docstring> + </property> + + <signal name="DTMFChangeRequested" + tp:name-for-bindings="DTMF_Change_Requested"> + <tp:docstring> + Used by the CM to relay instructions from <tp:dbus-ref + namespace="ofdT">Channel.Interface.DTMF</tp:dbus-ref> to the streaming + implementation. If any contact in this call supports the + telephone-event codec in their MediaDescription, this event should be + sent as outlined in RFC 4733. Otherwise, it should be sent as an + audible tone. + </tp:docstring> + <arg name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring> + The event to send (or stop sending). + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Sending_State"> + <tp:docstring> + Either <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> or + <tp:value-ref type="Sending_State">Pending_Stop_Sending</tp:value-ref>. + </tp:docstring> + </arg> + </signal> + + <method name="AcknowledgeDTMFChange" + tp:name-for-bindings="Acknowledge_DTMF_Change"> + <tp:docstring> + Called by the streaming implementation in response to + <tp:member-ref>DTMFChangeRequested</tp:member-ref> to confirm that it + has started or stopped sending the event in question. + </tp:docstring> + <arg name="Event" type="y" tp:type="DTMF_Event" direction="in"> + <tp:docstring> + The event referred to in the corresponding + <tp:member-ref>DTMFChangeRequested</tp:member-ref> signal. + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Sending_State" direction="in"> + <tp:docstring> + Either <tp:value-ref type="Sending_State">Sending</tp:value-ref> or + <tp:value-ref type="Sending_State">None</tp:value-ref>. + </tp:docstring> + </arg> + </method> + + <property name="CurrentDTMFEvent" + tp:name-for-bindings="Current_DTMF_Event" type="y" tp:type="DTMF_Event" + access="read"> + <tp:docstring> + The currently requested DTMF event (for state-recoverability of + <tp:member-ref>DTMFChangeRequested</tp:member-ref>). Should be ignored + if <tp:member-ref>CurrentDTMFState</tp:member-ref> is None. + </tp:docstring> + </property> + + <property name="CurrentDTMFState" + tp:name-for-bindings="Current_DTMF_State" type="u" tp:type="Sending_State" + access="read"> + <tp:docstring> + The current DTMF state (for state-recoverability of + <tp:member-ref>DTMFChangeRequested</tp:member-ref>). + </tp:docstring> + </property> + + <method name="Fail" tp:name-for-bindings="Fail"> + <tp:docstring> + Signal an unrecoverable error for this content, and remove it. + </tp:docstring> + <arg direction="in" name="Reason" type="(uuss)" + tp:type="Call_State_Reason"> + <tp:docstring> + A reason struct describing the error. + </tp:docstring> + </arg> + </method> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |