diff options
Diffstat (limited to 'qt4/spec/Call_Content_Interface_Media.xml')
| -rw-r--r-- | qt4/spec/Call_Content_Interface_Media.xml | 367 |
1 files changed, 367 insertions, 0 deletions
diff --git a/qt4/spec/Call_Content_Interface_Media.xml b/qt4/spec/Call_Content_Interface_Media.xml new file mode 100644 index 000000000..038ce8c7a --- /dev/null +++ b/qt4/spec/Call_Content_Interface_Media.xml @@ -0,0 +1,367 @@ +<?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.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.DRAFT"/> + + <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.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> + + <h4>Codec negotiation</h4> + + <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 + 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 + 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 lists 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 can be proposed.</p> + + <p>For incoming calls on protocols where codecs are proposed when + 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 + be the empty list.</p> + + <p>The streaming implementation should look at the remote codec + map and the codecs known by the local user and call + <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref> + on the intersection of these two codec lists.</p> + + <p>This means that in practice, outgoing calls will have a codec + offer pop up with no information in the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, + so the local user will call <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> + with the list of all codecs supported. If this codec offer is + accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> + will fire with the details of the codecs passed into + <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If + the call is incoming, then the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + will contain details of the remote contact's codecs and the + local user will call <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> + with the codecs that both sides understand. After the codec + set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref> + will fire to signal this change.</p> + + <h4>Protocols without codec negotiation</h4> + + <p>For protocols where the codecs are not negotiable, instead of + popping up the initial content's <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object with an empty <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, + the CM should set the supported codec values to known codec + values in the said object's codec map.</p> + + <h4>Changing codecs mid-call</h4> + + <p>To update the codec list used mid-call, the + <tp:member-ref>UpdateCodecs</tp:member-ref> method should be + called with details of the new codec list. If this is + accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> + will be emitted with the new codec set.</p> + + <p>If the other side decides to update his or her codec list + during a call, a new <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object will appear through + <tp:member-ref>NewCodecOffer</tp:member-ref> which should be + acted on as documented above.</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="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(usuua{ss})" tp:type="Codec[]"> + <tp:docstring> + The codecs that the contact supports. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Codec_Offering"> + <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="ofdT.Call.Content" + >CodecOffer.DRAFT</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 codec offer applies to. + </tp:docstring> + </tp:member> + <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})" + tp:type="Codec[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property + of the codec offer. + </tp:docstring> + </tp:member> + </tp:struct> + + <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the codecs in use change.</p> + + <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> + </tp:docstring> + <arg name="Updated_Codecs" type="a{ua(usuua{ss})}" + tp:type="Contact_Codec_Map"> + <tp:docstring> + 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 + <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because + those contacts left the call. + </tp:docstring> + </arg> + </signal> + + <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs"> + <tp:docstring> + 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 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 + 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> + object has appeared. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map" + type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read"> + <tp:docstring> + <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 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="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming + implementation MUST respond by calling the <tp:dbus-ref + 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>(Contact, Offer, Codecs)</code>.</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 + codec offer. + </tp:docstring> + </arg> + <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property + of the codec offer.</p> + + <tp:rationale> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</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> + + <property name="CodecOffer" tp:name-for-bindings="Codec_Offer" + type="(oua(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="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> object, its + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties. + If the object path is "/" then there isn't an outstanding + codec offer, and the mapping MUST be empty.</p> + + <tp:rationale> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContact</tp:dbus-ref> and + <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContactCodecs</tp:dbus-ref> + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the CodecOffer object, in + practice. + </tp:rationale> + + <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) 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> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |