diff options
Diffstat (limited to 'qt4/spec/Channel_Interface_Media_Signalling.xml')
| -rw-r--r-- | qt4/spec/Channel_Interface_Media_Signalling.xml | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Interface_Media_Signalling.xml b/qt4/spec/Channel_Interface_Media_Signalling.xml new file mode 100644 index 000000000..242c95284 --- /dev/null +++ b/qt4/spec/Channel_Interface_Media_Signalling.xml @@ -0,0 +1,235 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </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.Channel.Interface.MediaSignalling"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for signalling a channel containing synchronised media + sessions which can contain an arbitrary number of streams. The + presence of this interface on a Channel indicates that the connection + manager will not carry out the actual streaming for this channel, + and that the client handling the channel is responsible for doing + so; in most cases we recommend doing this by using the + telepathy-farsight library.</p> + + <tp:rationale> + <p>Streaming audio and (particularly) video requires a high level of + integration with the UI, and having the connection manager act as + a proxy would be likely to introduce unacceptable latency. As a + result, audio/video streaming is offloaded into the client + where possible, as an exception to the general design of + Telepathy.</p> + </tp:rationale> + + <p>The negotiation interface is based on the API of the + <a href="http://farsight.freedesktop.org/">Farsight</a> library. + This, in turn, is based upon the IETF MMusic ICE drafts, where + connections are established by signalling potential connection + candidates to the peer until a usable connection is found, and + codecs are negotiated with an SDP-style offer and answer. However, + the principles should be applicable to other media streaming methods + and the API re-used without difficulty.</p> + + <p>Note that the naming conventions used in the MediaStreamHandler + and MediaSessionHandler interfaces are rather confusing; methods + have signal-like names and signals have method-like names, due to + the API being based rather too closely on that of Farsight. This + is for historical reasons and will be fixed in a future release + of the Telepathy specification.</p> + </tp:docstring> + + <tp:simple-type name="Media_Session_Type" type="s"> + <tp:docstring>The type of a media session. Currently, the only supported + value is "rtp".</tp:docstring> + </tp:simple-type> + + <tp:struct name="Media_Session_Handler_Info" + array-name="Media_Session_Handler_Info_List"> + <tp:docstring>A struct representing a active session handler.</tp:docstring> + <tp:member type="o" name="Session_Handler"> + <tp:docstring>The object path of the session handler, which is on the + same bus name as the channel.</tp:docstring> + </tp:member> + <tp:member type="s" tp:type="Media_Session_Type" name="Media_Session_Type"> + <tp:docstring>The media session's type</tp:docstring> + </tp:member> + </tp:struct> + + <method name="GetSessionHandlers" + tp:name-for-bindings="Get_Session_Handlers"> + <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]" + name="Session_Handlers"/> + <tp:docstring> + Returns all currently active session handlers on this channel + as a list of (session_handler_path, type). + </tp:docstring> + </method> + + <signal name="NewSessionHandler" tp:name-for-bindings="New_Session_Handler"> + <arg name="Session_Handler" type="o"> + <tp:docstring> + Object path of the new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Media.SessionHandler</tp:dbus-ref> + object + </tp:docstring> + </arg> + <arg name="Session_Type" tp:type="Media_Session_Type" type="s"> + <tp:docstring> + String indicating type of session, eg "rtp" + </tp:docstring> + </arg> + <tp:docstring> + Signal that a session handler object has been created. The client + should create a session object and create streams for the streams + within. + </tp:docstring> + </signal> + + <tp:property name="nat-traversal" type="s"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> + <tp:docstring> + A string indicating the NAT traversal techniques employed by the + streams within this channel if they do not have a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property. The possible values are the same as for the NATTraversal + property on the streams. + </tp:docstring> + </tp:property> + + <tp:property name="stun-server" type="s"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> + <tp:docstring> + The IP address or hostname of the STUN server to use for NAT traversal + if the individual streams do not specify one. + </tp:docstring> + </tp:property> + + <tp:property name="stun-port" type="q"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> + <tp:docstring> + The UDP port number to use on the provided STUN server. + </tp:docstring> + </tp:property> + + <tp:property name="gtalk-p2p-relay-token" type="s"> + <tp:deprecated version="0.17.22">XMPP connection managers + supporting the Google Talk relay server SHOULD make the necessary + HTTP requests to find a username and password, and use those + to populate the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref> + property on the Media.StreamHandler.</tp:deprecated> + <tp:docstring> + The authentication token for use with the Google Talk peer-to-peer relay + server. + </tp:docstring> + </tp:property> + + <tp:hct name="gtalk-p2p"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>gtalk-p2p</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="ice-udp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>ice-udp</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="wlm-8.5"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>wlm-8.5</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="wlm-2009"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>wlm-2009</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="video/h264" is-family="yes"> + <tp:docstring> + <p>The client supports media streaming with H264 (etc.).</p> + + <p>This handler capability token is a one of a family + of similar tokens: for any other audio or video codec whose MIME + type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler + capability token of this form may exist (the subtype MUST appear + in lower case in this context). Clients MAY support more + codecs than they explicitly advertise support for; clients SHOULD + explicitly advertise support for their preferred codec(s), and + for codecs like H264 that are, in practice, significant in codec + negotiation.</p> + + <tp:rationale> + <p>For instance, the XMPP capability used by the Google Video + Chat web client to determine whether a client is compatible + with it requires support for H264 video, so an XMPP + connection manager that supports this version of Jingle should + not advertise the Google Video Chat capability unless there + is at least one installed client that declares that it supports + <code>video/h264</code> on StreamedMedia channels.</p> + </tp:rationale> + + <p>For example, a client could advertise support for + Speex, Theora and H264 by having three + handler capability tokens, + <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex</code>, + <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora</code> and + <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264</code>, + in its <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref> + property.</p> + + <p>Clients MAY have media signalling abilities without explicitly + supporting any particular codec, and connection managers SHOULD + support this usage.</p> + + <tp:rationale> + <p>This is necessary to support gatewaying between two Telepathy + connections, in which case the available codecs might not be + known to the gatewaying process.</p> + </tp:rationale> + </tp:docstring> + </tp:hct> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |