<?xml version="1.0" ?>
<node name="/Call_Content_Interface_Media"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2009 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"/>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      Interface to use by a software implementation of media streaming.

      FIXME: How should the streaming implementation know when it is its turn
      to set the codecs.
    </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 contacts to the lists of codecs they support.
      </tp:docstring>

      <tp:member name="Handle" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          A contact
        </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="org.freedesktop.Telepathy.Call.Content"
              >CodecOffer.DRAFT</tp:dbus-ref>
        </tp:docstring>
      </tp:member>

      <tp:member name="Remote_Contact_Codec_Map" type="a{ua(usuua{ss})}"
          tp:type="Contact_Codec_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content"
            >CodecOffer.DRAFT.RemoteContactCodecMap</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 contacts to their 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="SetCodecs" tp:name-for-bindings="Set_Codecs">
      <tp:docstring>
        Set or update the local 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>
    </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
          <tp:member-ref>CodecsChanged</tp:member-ref>.</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="org.freedesktop.Telepathy.Call.Content"
            >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming
          implementation MUST respond by calling the <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT"
            >Accept</tp:dbus-ref> or <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.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>(Offer, Codecs)</code>.</p>
      </tp:docstring>

      <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{ua(usuua{ss})}" tp:type="Contact_Codec_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content"
              >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property
            of the codec offer.</p>

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

    <property name="CodecOffer" tp:name-for-bindings="Codec_Offer"
      type="(oa{ua(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="org.freedesktop.Telepathy.Call.Content"
              >CodecOffer.DRAFT</tp:dbus-ref> object, and its
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content"
              >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property.
            If the object path is "/" then there isn't an outstanding
          codec offer, and the mapping MUST be empty.</p>

        <tp:rationale>
          <p>Having the RemoteContactCodecMap property here saves a D-Bus
            round-trip - it shouldn't be necessary to get the property
            from the CodecOffer object, in practice.</p>
        </tp:rationale>

        <p>Change notification is via
          <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).</p>
      </tp:docstring>
    </property>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
