path: root/spec/Call_Content_Interface_Media.xml

<?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.DRAFT2"
      tp:causes-havoc="experimental">
    <tp:added version="UNRELEASED">(draft 2)</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">Description.DRAFT</tp:dbus-ref> object
        will either be waiting in the
        <tp:member-ref>DescriptionOffer</tp:member-ref> property, or will
        appear at some point via the
        <tp:member-ref>NewDescriptionOffer</tp:member-ref> signal.</p>

      <p> If the remote codecs and other content information is available
        then the  <tp:dbus-ref namespace="ofdT.Call.Content.Description.DRAFT"
          >EmptyDescription</tp:dbus-ref> property will be false
        and the <tp:dbus-ref
        namespace="ofdT.Call.Content.Description.DRAFT">RemoteCodecs</tp:dbus-ref>
        property on the description 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. </p>

      <p>For incoming calls on protocols where the content is described 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.Description.DRAFT">RemoteCodecs</tp:dbus-ref>
        will contain information on the codecs that have already been
        proposed by the remote contact, otherwise
        the <tp:dbus-ref namespace="ofdT.Call.Content.Description.DRAFT"
          >EmptyDescription</tp:dbus-ref> property will be true </p>

      <p>The streaming implementation should look at the remote description
        and the codecs and other features known by the local user and call
        <tp:dbus-ref
        namespace="ofdT.Call.Content">Description.DRAFT.Accept</tp:dbus-ref>
        with the locally supported description.</p>

      <p>This means that in practice, outgoing calls will have a content
        description pop up with <tp:dbus-ref
        namespace="ofdT.Call.Content.Description.DRAFT">EmptyDescription</tp:dbus-ref>,
        property true so the local user will call <tp:dbus-ref
        namespace="ofdT.Call.Content.Description.DRAFT">Accept</tp:dbus-ref>
        with a description of all supported codecs and other features. If this
        description is accepted, then
        <tp:member-ref>LocalDescriptionsChanged</tp:member-ref> will fire with
        the details of description passed into <tp:dbus-ref
        namespace="ofdT.Call.Content.Description.DRAFT">Accept</tp:dbus-ref>.
        If the call is incoming, then the <tp:dbus-ref
        namespace="ofdT.Call.Content.Description.DRAFT">RemoteCodecs</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.Description.DRAFT">Accept</tp:dbus-ref>
        with the codecs that both sides understand. After the codec
        set is accepted, both
         <tp:member-ref>LocalDescriptionsChanged </tp:member-ref> and
         <tp:member-ref>RemoteDescriptionsChanged </tp:member-ref>
        will fire to signal their respective changes. </p>

      <h4>Protocols without 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">Description.DRAFT</tp:dbus-ref>
        object with <tp:dbus-ref
        namespace="ofdT.Call.Content.Description.DRAFT">EmptyDescription</tp:dbus-ref>,
        set to true and no codecs/features being defined, the CM should set the
        supported codec values to known codec values in said object's codec
        map.</p>

      <h4>Changing codecs mid-call</h4>

      <p>To update the local codecs in all local descriptions 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>LocalDescriptionsChanged </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">Description.DRAFT</tp:dbus-ref>
        object will appear through
        <tp:member-ref>NewDescriptionOffer</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:mapping name="Contact_Description_Properties_Map">
      <tp:member name="Remote_Contact" type="u" tp:type="Handle">
        <tp:docstring>
          The remote contact this description refers to
        </tp:docstring>
      </tp:member>
      <tp:member name="Description_Properties" type="a{sv}"
          tp:type="Description_Properties">
        <tp:docstring>
          The properties of the description
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:struct name="Description_Offer">
      <tp:docstring>
        The remote description offer and its information
      </tp:docstring>
      <tp:member name="Description" type="o">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The object path to the <tp:dbus-ref namespace="ofdT.Call.Content"
          >Description.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 description applies to.
        </tp:docstring>
      </tp:member>
      <tp:member name="Properties" type="a{sv}"
           tp:type="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
          Description object, in practice.
          </tp:rationale>
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <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 in all local
        content descriptions.
      </tp:docstring>
      <arg name="Codecs" direction="in"
        type="a(usuua{ss})" tp:type="Codec[]">
        <tp:docstring>
          The updated codecs map as will be used by the local end.
        </tp:docstring>
      </arg>
    </method>

    <property name="RemoteDescriptions"
        tp:name-for-bindings="Remote_Descriptions"
        type="a{ua{sv}}"
        tp:type="Contact_Description_Properties_Map" access="read">
      <tp:docstring>
        <p>A map from contact handles to descriptions supported by that
           contact.</p>
      </tp:docstring>
    </property>

    <property name="LocalDescriptions"
        tp:name-for-bindings="Local_Descriptions"
        type="a{ua{sv}}"
        tp:type="Contact_Description_Properties_Map" access="read">
      <tp:docstring>
        <p>A map from contact handles to the descriptions as response.</p>
      </tp:docstring>
    </property>

    <signal name="NewDescriptionOffer"
        tp:name-for-bindings="New_Description_Offer">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content"
          >Description.DRAFT</tp:dbus-ref> appears or a previous one 
          disappears. The streaming implementation MUST respond by calling the
          <tp:dbus-ref namespace="ofdT.Call.Content.Description.DRAFT"
          >Accept</tp:dbus-ref> or <tp:dbus-ref
          namespace="ofdT.Call.Content.Description.DRAFT"
          >Reject</tp:dbus-ref> method on the description object if it has
          >appeared.</p>

        <p>Emission of this signal indicates that the
          <tp:member-ref>DescriptionOffer</tp:member-ref> property has
          changed to
            <code>(Description, Contact, DescriptionProperties)</code>.</p>
      </tp:docstring>
      <arg name="Description" type="o">
        <tp:docstring>
          The object path of the new description or "/" in case of no new
          description. This replaces any previous description.
        </tp:docstring>
      </arg>
      <arg name="Contact" type="u">
        <tp:docstring>
          The remote contact the description belongs to.
        </tp:docstring>
      </arg>
      <arg name="Properties" type="a{sv}"
           tp:type="Qualified_Property_Value_Map">
        <tp:docstring>
          The immutable properties of the remote description.

          <tp:rationale>
          Having all the Description properties here saves a D-Bus round-trip -
          it shouldn't be necessary to get the properties from the Description
          object, in practice.
          </tp:rationale>
        </tp:docstring>
      </arg>
    </signal>


    <signal name="LocalDescriptionsChanged"
      tp:name-for-bindings="Local_Descriptions_Changed">

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Change notification for
            <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
              >LocalDescriptions</tp:dbus-ref>
        </p>
      </tp:docstring>

      <arg name="Updated_Descriptions" type="a{ua{sv}}"
        tp:type="Contact_Description_Properties_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The local content descriptions that were updated</p>
        </tp:docstring>
      </arg>
      <arg name="Removed_Descriptions" type="au">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The local content descriptions that are no longer part
             of this content</p>
        </tp:docstring>
      </arg>
    </signal>

    <signal name="RemoteDescriptionsChanged"
      tp:name-for-bindings="Remote_Descriptions_Changed">

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Change notification for
            <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
              >RemoteDescriptions</tp:dbus-ref>
        </p>
      </tp:docstring>

      <arg name="Updated_Descriptions" type="a{ua{sv}}"
          tp:type="Contact_Description_Properties_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The remote content descriptions that were updated</p>
        </tp:docstring>
      </arg>
      <arg name="Removed_Descriptions" type="au">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The remote content descriptions that are no longer part
             of this content</p>
        </tp:docstring>
      </arg>
    </signal>

    <property name="DescriptionOffer"
        tp:name-for-bindings="Description_Offer"
      type="(oua{sv})" tp:type="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.Call.Content"
           >Description.DRAFT</tp:dbus-ref> object, its
            <tp:dbus-ref namespace="ofdT.Call.Content.Description.DRAFT"
            >RemoteContact</tp:dbus-ref> and
            a mapping of the Descriptions 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.Call.Content">Description.DRAFT</tp:dbus-ref>
          properties here saves a D-Bus round-trip - it shouldn't be
          necessary to get these properties from the Content Description
          object, in practice.
        </tp:rationale>

        <p>Change notification is via the
          <tp:member-ref>NewDescriptionOffer</tp:member-ref>
          (which replaces the value of this property with a new content
          description if any)
         </p>
      </tp:docstring>
    </property>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->