path: root/farstream/extensions/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.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: -->