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="im.telepathy.Call1.Content.Interface.Media"
      tp:causes-havoc="experimental">
    <tp:added version="0.23.4">(draft 2)</tp:added>
    <tp:requires interface="im.telepathy.Call1.Content"/>

    <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="imt.Call1">Content</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="imt.Channel.Type">Call1</tp:dbus-ref> channel
        appears (whether it was requested or not) a <tp:dbus-ref
        namespace="imt.Call1.Content">MediaDescription</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 nothing is known about the remote side's Media capabilities
        (e.g. outgoing SIP/XMPP call), this <tp:dbus-ref namespace="imt.Call1.Content"
        >MediaDescription</tp:dbus-ref> will pop up with {<tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >HasRemoteInformation</tp:dbus-ref> = false, <tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >FurtherNegotiationRequired</tp:dbus-ref> = true}, and the local
        user's streaming implementation SHOULD call 
        <tp:dbus-ref namespace="imt.Call1.Content.MediaDescription"
        >Accept</tp:dbus-ref>,
        with a description of all supported codecs and other features.
        The CM will then send this information to the remote side (and
        <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> will fire
        with details of the description passed into <tp:dbus-ref
          namespace="imt.Call1.Content.MediaDescription"
          >Accept</tp:dbus-ref> for debugging purposes).
      </p>
      <p>When the remote codecs and other content information are available
        (e.g. Remote user replies to initial offer, or sends a new offer of
        their own, a new <tp:dbus-ref namespace="imt.Call1.Content"
         >MediaDescription</tp:dbus-ref> will appear, with {<tp:dbus-ref
         namespace="imt.Call1.Content.MediaDescription"
         >HasRemoteInformation</tp:dbus-ref> = true, <tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >FurtherNegotiationRequired</tp:dbus-ref> = false},
        and the <tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >Codecs</tp:dbus-ref>
        property on the description offer set to the codecs which are
        supported by the remote contact. The local user's streaming
        implementation SHOULD then call Accept, with a description
        that is compatible with the one one in the offer. After the codec
        set is accepted, both
         <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> and
         <tp:member-ref>RemoteMediaDescriptionsChanged</tp:member-ref>
        will fire to signal their respective changes, to aid with debugging.
        Note that if <tp:dbus-ref namespace="imt.Call1.Content.MediaDescription"
        >Accept</tp:dbus-ref> is called, with <tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >FurtherNegotiationRequired</tp:dbus-ref> set to false,
        the CM should be able to rely on the fact that the
        description passed into Accept is compatible with the one in the
        offer, and the description passed into Accept will not be signalled to
        the remote side.
      </p>

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

      <p>To update the codecs in the local (and optionally remote) media
        descriptions mid-call, the
        <tp:member-ref>UpdateLocalMediaDescription</tp:member-ref> method
        should be called with details of the new codec list. If this is
        accepted, then
        <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref>
        will be emitted with the new codec set.
      </p>
      <p> If parameters requiring negotiation are changed, then the
        <tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >FurtherNegotiationRequired</tp:dbus-ref> property should be set to
        TRUE, and the new media description should
        only be used once they come in a new MediaDescriptionOffer
      </p>

      <p>If the other side decides to update his or her codec list
        during a call, a new <tp:dbus-ref
        namespace="imt.Call1.Content">MediaDescription</tp:dbus-ref>
        object will appear through
        <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> which should be
        acted on as documented above.</p>

      <h4>Protocols without negotiation</h4>

      <p>For protocols where the codecs are not negotiable, the initial content's <tp:dbus-ref
        namespace="imt.Call1.Content">MediaDescription</tp:dbus-ref>
        object will appear with <tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >HasRemoteInformation</tp:dbus-ref>,
        set to true and the known supported codec values in <tp:dbus-ref
        namespace="imt.Call1.Content.MediaDescription"
          >Codecs</tp:dbus-ref>.
      </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="Updated" type="b">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          This should be set to true in calls to <tp:dbus-ref
              namespace="imt.Call1.Content.MediaDescription"
          >Accept</tp:dbus-ref> and
          <tp:member-ref>UpdateLocalMediaDescription</tp:member-ref> if this
          codec has changed in a way that needs to be signalled over the
          network. If it is set to false, the CM is allowed ignore any
          differences between the current parameters and the previous ones
          <tp:rationale>
            This mechanism may be used to save bandwidth and avoid the CM
            having to calculate diffs against previous versions of this
            struct, which can lead to false-positives (e.g. redundant ptime
            updates).
          </tp:rationale>
        </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(usuuba{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 or 0. This matches the
          <tp:dbus-ref namespace="imt.Call1.Content.MediaDescription"
            >RemoteContact</tp:dbus-ref> property on
          <tp:dbus-ref namespace="imt.Call1.Content"
                    >MediaDescription</tp:dbus-ref>
        </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="imt.Call1.Content"
          >MediaDescription</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="UpdateLocalMediaDescription"
            tp:name-for-bindings="Update_Local_Media_Description">
      <tp:docstring>
        Update the local codec mapping and other interfaces of the
        MediaDescription. This method should only be
        used during an existing call to update the local media description.
        This may trigger a re-negotiation which may result in new
        new MediaDescriptionOffers if the "FurtherNegotiationRequired"
        property is TRUE.
        Otherwise, only parameters which strictly describe the media being sent
        can be changed.
      </tp:docstring>
      <arg name="Remote_Contact" type="u" tp:type="Handle" direction="in">
        <tp:docstring>
          The remote contact that this description should be negotiated with
          (or 0 to mean "negotiate this with everyone"). Note that encoding
          the same video multiple times is often needlessly expensive, so
          differences in MediaDescriptions negotiated with different parties
          in the call should be limited to payloading parameters if possible.
        </tp:docstring>
      </arg>
      <arg name="MediaDescription" direction="in" type="a{sv}"
           tp:type="Media_Description_Properties">
        <tp:docstring>
          The updated media description that the local side wants to use.
        </tp:docstring>
      </arg>
      <tp:possible-errors>
        <tp:error name="im.telepathy.Error.NotImplemented">
          <tp:docstring>
            The protocol does not support changing the codecs mid-call.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.Error.InvalidArgument">
          <tp:docstring>
            The description given is invalid in some way.
          </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>

        <p>Keys of this map will appear in at most one <tp:dbus-ref
          namespace="imt.Call1.Stream">RemoteMembers</tp:dbus-ref>.
          See <tp:dbus-ref namespace="imt.Call1.Content.MediaDescription"
          >RemoteContact</tp:dbus-ref> for more details on how to map between
          MediaDescriptions and Streams.</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 the local side
           responsed with.</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="imt.Call1.Content"
          >MediaDescription</tp:dbus-ref> appears. The streaming
          >implementation MUST respond by calling the
          <tp:dbus-ref namespace="imt.Call1.Content.MediaDescription"
          >Accept</tp:dbus-ref> or <tp:dbus-ref
          namespace="imt.Call1.Content.MediaDescription"
          >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="imt.Call1.Content.Interface.Media"
            >MediaDescriptionOfferDone</tp:dbus-ref> must be emitted
          before <tp:dbus-ref
            namespace="imt.Call1.Content.Interface.Media"
              >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="Media_Description_Properties">
        <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="imt.Call1.Content"
          >MediaDescription</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="LocalMediaDescriptionChanged"
      tp:name-for-bindings="Local_Media_Description_Changed">

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Change notification for
            <tp:dbus-ref namespace="imt.Call1.Content.Interface.Media"
              >LocalMediaDescriptions</tp:dbus-ref>
        </p>
      </tp:docstring>

      <arg name="Remote_Contact" type="u" tp:type="Handle">
        <tp:docstring>
          The remote contact that this description was negotiated with
          (or 0 to mean "negotiated with everyone").
        </tp:docstring>
      </arg>

      <arg name="Updated_Media_Description" type="a{sv}"
        tp:type="Media_Description_Properties">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The local content description that was 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="imt.Call1.Content.Interface.Media"
              >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="imt.Call1.Content.Interface.Media"
              >RemoteMediaDescriptions</tp:dbus-ref>
            and
            <tp:dbus-ref namespace="imt.Call1.Content.Interface.Media"
              >LocalMediaDescriptions</tp:dbus-ref>
        </p>
      </tp:docstring>

      <arg name="Removed_Media_Descriptions" type="au"
          tp:type="Contact_Handle[]">
        <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="imt.Call1.Content"
           >MediaDescription</tp:dbus-ref> object, its
            <tp:dbus-ref namespace="imt.Call1.Content.MediaDescription"
            >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="imt.Call1.Content">MediaDescription</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>

    <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>

    <signal name="DTMFChangeRequested"
      tp:name-for-bindings="DTMF_Change_Requested">
      <tp:docstring>
        Used by the CM to relay instructions from <tp:dbus-ref
        namespace="imt">Channel.Interface.DTMF</tp:dbus-ref> to the streaming
        implementation. If any contact in this call supports the
        telephone-event codec in their MediaDescription, this event should be
        sent as outlined in RFC 4733. Otherwise, it should be sent as an
        audible tone.
      </tp:docstring>
      <arg name="Event" type="y" tp:type="DTMF_Event">
        <tp:docstring>
          The event to send (or stop sending).
        </tp:docstring>
      </arg>
      <arg name="State" type="u" tp:type="Sending_State">
        <tp:docstring>
          Either <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> or
          <tp:value-ref type="Sending_State">Pending_Stop_Sending</tp:value-ref>.
        </tp:docstring>
      </arg>
    </signal>

    <method name="AcknowledgeDTMFChange"
      tp:name-for-bindings="Acknowledge_DTMF_Change">
      <tp:docstring>
        Called by the streaming implementation in response to
        <tp:member-ref>DTMFChangeRequested</tp:member-ref> to confirm that it
        has started or stopped sending the event in question.
      </tp:docstring>
      <arg name="Event" type="y" tp:type="DTMF_Event" direction="in">
        <tp:docstring>
          The event referred to in the corresponding
          <tp:member-ref>DTMFChangeRequested</tp:member-ref> signal.
        </tp:docstring>
      </arg>
      <arg name="State" type="u" tp:type="Sending_State" direction="in">
        <tp:docstring>
          Either <tp:value-ref type="Sending_State">Sending</tp:value-ref> or
          <tp:value-ref type="Sending_State">None</tp:value-ref>.
        </tp:docstring>
      </arg>
    </method>

    <property name="CurrentDTMFEvent"
      tp:name-for-bindings="Current_DTMF_Event" type="y" tp:type="DTMF_Event"
      access="read">
      <tp:docstring>
        The currently requested DTMF event (for state-recoverability of
        <tp:member-ref>DTMFChangeRequested</tp:member-ref>). Should be ignored
        if <tp:member-ref>CurrentDTMFState</tp:member-ref> is None.
      </tp:docstring>
    </property>

    <property name="CurrentDTMFState"
      tp:name-for-bindings="Current_DTMF_State" type="u" tp:type="Sending_State"
      access="read">
      <tp:docstring>
        The current DTMF state (for state-recoverability of
        <tp:member-ref>DTMFChangeRequested</tp:member-ref>).
      </tp:docstring>
    </property>

    <method name="Fail" tp:name-for-bindings="Fail">
      <tp:docstring>
        Signal an unrecoverable error for this content, and remove it.
      </tp:docstring>
      <arg direction="in" name="Reason" type="(uuss)"
        tp:type="Call_State_Reason">
        <tp:docstring>
          A reason struct describing the error.
        </tp:docstring>
      </arg>
    </method>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->