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">MediaDescription.DRAFT</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 the remote codecs and other content information are available
        then the  <tp:dbus-ref
         namespace="ofdT.Call.Content.MediaDescription.DRAFT"
         >NoRemoteInformation</tp:dbus-ref> property will be false
        and the <tp:dbus-ref
        namespace="ofdT.Call.Content.MediaDescription.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.MediaDescription.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.MediaDescription.DRAFT"
          >NoRemoteInformation</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"
          >MediaDescription.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.MediaDescription.DRAFT"
          >NoRemoteInformation</tp:dbus-ref>,
        property true so the local user will call <tp:dbus-ref
        namespace="ofdT.Call.Content.MediaDescription.DRAFT"
        >Accept</tp:dbus-ref>
        with a description of all supported codecs and other features. If this
        description is accepted, then
        <tp:member-ref>LocalMediaDescriptionsChanged</tp:member-ref> will fire
        with the details of description passed into <tp:dbus-ref
          namespace="ofdT.Call.Content.MediaDescription.DRAFT"
          >Accept</tp:dbus-ref>.
        If the call is incoming, then the <tp:dbus-ref
        namespace="ofdT.Call.Content.MediaDescription.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.MediaDescription.DRAFT"
          >Accept</tp:dbus-ref>
        with the codecs that both sides understand. After the codec
        set is accepted, both
         <tp:member-ref>LocalMediaDescriptionsChanged</tp:member-ref> and
         <tp:member-ref>RemoteMediaDescriptionsChanged</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">MediaDescription.DRAFT</tp:dbus-ref>
        object with <tp:dbus-ref
        namespace="ofdT.Call.Content.MediaDescription.DRAFT"
          >NoRemoteInformation</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>LocalMediaDescriptionsChanged</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">MediaDescription.DRAFT</tp:dbus-ref>
        object will appear through
        <tp:member-ref>NewMediaDescriptionOffer</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_Media_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="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.Call.Content"
          >MediaDescription.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="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="UpdateCodecs" tp:name-for-bindings="Update_Codecs">
      <tp:docstring>
        Update the codec mapping of the local MediaDescriptions. This
        method should only be used during an existing call to update the local
        media descriptions. Only parameters which strictly describe the media
        being sent can be changed.
      </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>
      <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: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>
      </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 as response.</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.Call.Content"
          >MediaDescription.DRAFT</tp:dbus-ref> appears. The streaming
          >implementation MUST respond by calling the
          <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
          >Accept</tp:dbus-ref> or <tp:dbus-ref
          namespace="ofdT.Call.Content.MediaDescription.DRAFT"
          >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.Call.Content.Interface.Media.DRAFT2"
            >MediaDescriptionOfferDone</tp:dbus-ref> must be emitted
          before <tp:dbus-ref
            namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
              >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="Qualified_Property_Value_Map">
        <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.Call.Content"
          >MediaDescription.DRAFT</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="LocalMediaDescriptionsChanged"
      tp:name-for-bindings="Local_Media_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"
              >LocalMediaDescriptions</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 local content descriptions that were 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.Call.Content.Interface.Media.DRAFT2"
              >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.Call.Content.Interface.Media.DRAFT2"
              >RemoteMediaDescriptions</tp:dbus-ref>
            and
            <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
              >LocalMediaDescriptions</tp:dbus-ref>
        </p>
      </tp:docstring>

      <arg name="Removed_Media_Descriptions" type="au">
        <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.Call.Content"
           >MediaDescription.DRAFT</tp:dbus-ref> object, its
            <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
            >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.Call.Content">MediaDescription.DRAFT</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>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->