<?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 &quot;rtp&quot;
        </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: -->
