<?xml version="1.0" ?>
<node name="/Call_Content"
  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.Call1.Content">
    <tp:added version="0.25.2">(as stable API)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>This object represents one Content inside a <tp:dbus-ref
      namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>. For
      example, in an audio/video call there would be one audio content
      and one video content. Each content has one or more <tp:dbus-ref
      namespace="ofdT.Call1">Stream</tp:dbus-ref> objects which
      represent the actual transport to one or more remote contacts.</p>
      <tp:rationale>
        There are two cases where multiple streams may happen:
        <ul>
          <li>Calls with more than two participants, if the protocol does not
          support multicast, and does not have mixer proxy.</li>
          <li>With jingle, when calling a contact connected from multiple
          resources, a stream is created for each resource. Once the remote
          contact answered from one of its resources, all other streams get
          removed.</li>
        </ul>
      </tp:rationale>
      <p>For protocols that support muting all streams of a given content
      separately, this object MAY also implement the <tp:dbus-ref
      namespace="ofdT.Call1.Interface">Mute</tp:dbus-ref> interface</p>
    </tp:docstring>

    <method name="Remove" tp:name-for-bindings="Remove">
      <tp:changed version="0.21.2">previously there were no
        arguments</tp:changed>
      <tp:docstring>
        Remove the content from the call. This will cause
        <tp:dbus-ref namespace="ofdT.Channel.Type">Call1.ContentRemoved</tp:dbus-ref>((self_handle,
        <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "", "")) to be
        emitted.
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            Raised when a Call doesn't support removing contents
            (e.g. a Google Talk video call).
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
      <tp:added version="0.19.11"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Extra interfaces provided by this content, such as <tp:dbus-ref
          namespace="ofdT.Call1">Content.Interface.Media</tp:dbus-ref>,
          <tp:dbus-ref namespace="ofdT.Channel">Interface.Hold</tp:dbus-ref> or
          <tp:dbus-ref namespace="ofdT.Call1">Interface.Mute</tp:dbus-ref>.
          This SHOULD NOT include the Content interface itself, and cannot
          change once the content has been created.</p>
      </tp:docstring>
    </property>

    <property name="Name" tp:name-for-bindings="Name" type="s" access="read"
      tp:immutable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The name of the content.</p>

        <tp:rationale>
          The content name property should be meaningful, so should be
          given a name which is significant to the user. The name
          could be the "audio" or "video" string localized, or perhaps
          include some string identifying the source, such as a webcam
          identifier.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="Type" tp:name-for-bindings="Type"
        type="u" tp:type="Media_Stream_Type" access="read" tp:immutable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The media type of this content.</p>
      </tp:docstring>
    </property>

    <tp:enum name="Call_Content_Disposition" type="u">
      <tp:docstring>
        The disposition of this content, which defines whether to
        automatically start sending data on the streams when
        <tp:dbus-ref
        namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref> is
        called on the channel.
      </tp:docstring>

      <tp:enumvalue suffix="None" value="0">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The content has no specific disposition.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Initial" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The content was initially part of the call. When
          <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref>
          is called on the channel, all streams of this content with
          <tp:dbus-ref
          namespace="ofdT.Call1.Stream">LocalSendingState</tp:dbus-ref>
          set to <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> will be
          moved to <tp:value-ref type="Sending_State">Sending</tp:value-ref> as if
          <tp:dbus-ref
          namespace="ofdT.Call1.Stream">SetSending</tp:dbus-ref>
          (True) had been called.</p>
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <property name="Disposition" tp:name-for-bindings="Disposition"
        type="u" tp:type="Call_Content_Disposition" access="read"
        tp:immutable="yes">
      <tp:docstring>
        The disposition of this content.
      </tp:docstring>
    </property>

    <signal name="StreamsAdded" tp:name-for-bindings="Streams_Added">
      <tp:changed version="0.21.2">plural version, renamed from
        StreamAdded</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Emitted when streams are added to a call.</p>
      </tp:docstring>
      <arg name="Streams" type="ao">
         <tp:docstring>
           The <tp:dbus-ref
           namespace="ofdT.Call1">Stream</tp:dbus-ref>s which were
           added.
         </tp:docstring>
       </arg>
    </signal>

    <signal name="StreamsRemoved" tp:name-for-bindings="Streams_Removed">
      <tp:changed version="0.21.2">plural version, renamed from
        StreamRemoved</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Emitted when streams are removed from a call</p>
      </tp:docstring>
      <arg name="Streams" type="ao">
        <tp:docstring>
          The <tp:dbus-ref
          namespace="ofdT.Call1">Stream</tp:dbus-ref>s which were
          removed.
        </tp:docstring>
      </arg>
      <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason">
        <tp:docstring>
          Why the content was removed.
        </tp:docstring>
      </arg>
    </signal>

    <property name="Streams" tp:name-for-bindings="Streams"
      type="ao" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The list of <tp:dbus-ref namespace="ofdT.Call1"
          >Stream</tp:dbus-ref> objects that exist in this
          content.</p>

        <tp:rationale>
          In a conference call multiple parties can share one media
          content (say, audio), but the streaming of that media can
          either be shared or separate. For example, in a multicast
          conference all contacts would share one stream, while in a
          Muji conference there would be a stream for each
          participant.
        </tp:rationale>

        <p>Change notification is through the
          <tp:member-ref>StreamsAdded</tp:member-ref> and
          <tp:member-ref>StreamsRemoved</tp:member-ref> signals.</p>
      </tp:docstring>
    </property>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
