path: root/spec/Channel_Type_Call.xml

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

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.

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.
  </tp:license>
  <interface name="org.freedesktop.Telepathy.Channel.Type.Call1">
    <tp:added version="0.25.2">(as stable API)</tp:added>

    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:requires
      interface="org.freedesktop.Telepathy.Call1.Interface.Mute"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>A channel type for making audio and video calls. Call
        channels supersede the old <tp:dbus-ref
        namespace="ofdT.Channel.Type">StreamedMedia</tp:dbus-ref>
        channel type. Call channels are much more flexible than its
        predecessor and allow more than two participants.</p>

      <p>Handlers are advised against executing all the media
        signalling, codec and candidate negotiation themselves but
        instead use a helper library such as <a
        href="http://telepathy.freedesktop.org/doc/telepathy-farstream/">telepathy-farstream</a>
        which when given a new Call channel will set up the
        transports and codecs and create GStreamer pads which
        can be added to the handler UI. This is useful as it means
        the handler does not have to worry how exactly the
        connection between the call participants is being made.</p>

      <p>The <tp:dbus-ref
        namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> and
        <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>
        properties in a Call channel refer to the contact that the
        user initially called, or which contact initially called the
        user. Even in a conference call, where there are multiple
        contacts in the call, these properties refer to the
        initial contact, who might have left the conference since
        then. As a result, handlers should not rely on these
        properties.</p>

      <h4>Contents</h4>

      <p><tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref>
        objects represent the actual media that forms the Call (for
        example an audio content and a video content). Calls always
        have one or more Content objects associated with them. As a
        result, a new Call channel request MUST have either
        <tp:member-ref>InitialAudio</tp:member-ref>=True, or
        <tp:member-ref>InitialVideo</tp:member-ref>=True, or both,
        as the Requestable Channel Classes will document.</p>

      <p><tp:dbus-ref
        namespace="ofdT.Call1">Content</tp:dbus-ref> objects have
        one or more stream associated with them. More information on
        these streams and how to maniuplate them can be found on the
        <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref>
        interface page.</p>

      <h4>Outgoing calls</h4>

      <p>To make an audio-only call to a contact <tt>foo@example.com</tt>
        handlers should call:</p>

      <blockquote>
        <pre>
<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
  ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
      namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>,
  ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
  ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com',
  ...<tp:member-ref>InitialAudio</tp:member-ref>: True,
})</pre></blockquote>

      <p>As always, <tp:dbus-ref
        namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> may be used
        in place of
        <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>
        if the contact's handle is already known. To make an audio
        and video call, the handler should also specify
        <tp:member-ref>InitialVideo</tp:member-ref> The
        connection manager SHOULD return a channel whose immutable
        properties contain the local user as the <tp:dbus-ref
        namespace="ofdT.Channel">InitiatorHandle</tp:dbus-ref>, the
        remote contact as the <tp:dbus-ref
        namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>,
        <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> =
        <code>True</code> (indicating the call is outgoing).</p>

      <p>After a new Call channel is requested, the
        <tp:member-ref>CallState</tp:member-ref> property will be
        <tp:value-ref type="Call_State">Pending_Initiator</tp:value-ref>. As the local
        user is the initiator, the call must be accepted by the handler
        by calling the <tp:member-ref>Accept</tp:member-ref> method.
        At this point, <tp:member-ref>CallState</tp:member-ref> changes
        to <tp:value-ref type="Call_State">Initialising</tp:value-ref>, which signifies
        that the call is waiting for the network to do
        something. When the CM has information indicating that the remote contact has been
        notified about the call (or immediately if the network is known not to convey such
        information) it should also change to
        <tp:value-ref type="Call_State">Initialised</tp:value-ref>. All changes to
        the <tp:member-ref>CallState</tp:member-ref> property are signalled using
        the <tp:member-ref>CallStateChanged</tp:member-ref> signal.</p>

      <p>When the call is accepted by the remote contact, the
        <tp:member-ref>CallStateChanged</tp:member-ref> signal fires
        again to show that <tp:member-ref>CallState</tp:member-ref> =
        <tp:value-ref type="Call_State">Accepted</tp:value-ref>.</p>

      <p>At this point <a
        href="http://telepathy.freedesktop.org/doc/telepathy-farstream/">telepathy-farstream</a>
        will signal that a pad is available for the handler to show
        in the user interface. Once media is correctly flowing in both
        directions, the state will change to
        <tp:value-ref type="Call_State">Active</tp:value-ref>, to inform the user that they
        have a correctly working call there is nothing amiss.</p>

      <h5>Missed calls</h5>

      <p>If the remote contact does not accept the call in time, then
        the call can be terminated by the server. Note that this only
        happens in some protocols. Most XMPP clients, for example, do
        not do this and rely on the call initiator terminating the call.
        A missed call is shown in a Call channel by the
        <tp:member-ref>CallState</tp:member-ref> property changing to
        <tp:value-ref type="Call_State">Ended</tp:value-ref>, and the
        <tp:member-ref>CallStateReason</tp:member-ref> property changing
        to (remote contact,
        <tp:value-ref type="Call_State_Change_Reason">No_Answer</tp:value-ref>, "").</p>

      <h5>Rejected calls</h5>

      <p>If the remote contact decides he or she does not feel like
        talking to the local user, he or she can reject his or her
        incoming call. This will be shown in the Call channel by
        <tp:member-ref>CallState</tp:member-ref> changing to
        <tp:value-ref type="Call_State">Ended</tp:value-ref> and the
        <tp:member-ref>CallStateReason</tp:member-ref> property
        changing to (remote contact,
        <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>,
        "org.freedesktop.Telepathy.Error.Rejected").</p>

      <h4>Incoming calls</h4>

      <p>When an incoming call occurs, something like the following
        <tp:dbus-ref
        namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
        signal will occur:</p>

      <blockquote>
        <pre>
<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([
  /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
  {
    ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
      namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>,
    ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
    ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com',
    ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42,
    ...<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>: False,
    ...<tp:member-ref>InitialAudio</tp:member-ref>: True,
    ...<tp:member-ref>InitialVideo</tp:member-ref>: True,
    ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio",
    ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video",
    ...<tp:member-ref>MutableContents</tp:member-ref>: True,
  }])</pre></blockquote>

      <p>The <tp:member-ref>InitialAudio</tp:member-ref> and
        <tp:member-ref>InitialVideo</tp:member-ref> properties show that
        the call has been started with two contents: one for audio
        streaming and one for video streaming. The
        <tp:member-ref>InitialAudioName</tp:member-ref> and
        <tp:member-ref>InitialVideoName</tp:member-ref> properties also
        show that the aforementioned audio and video contents have names
        "audio" and "video".</p>

      <p>Once the handler has notified the local user that there is an
        incoming call waiting for acceptance, the handler should call
        <tp:member-ref>SetRinging</tp:member-ref> to let the CM know.
        The new channel should also be given to telepathy-farstream to
        work out how the two participants will connect together.
        telepathy-farstream will call the appropriate methods on the call's
        <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref>s
        to negotiate codecs and transports.</p>

      <p>To pick up the call, the handler should call
        <tp:member-ref>Accept</tp:member-ref>. The
        <tp:member-ref>CallState</tp:member-ref> property changes to
        <tp:value-ref type="Call_State">Accepted</tp:value-ref> and once media is
        being transferred, telepathy-farstream will notify the
        handler of a new pad to be shown to the local user in the
        UI. Once media is correctly flowing in both directions, the state will
        change to <tp:value-ref type="Call_State">Active</tp:value-ref>, to inform the user
        that they have a correctly working call there is nothing amiss.</p>

      <p>To reject the call, the handler should call the
        <tp:member-ref>Hangup</tp:member-ref> method. The
        <tp:member-ref>CallState</tp:member-ref> property will change to
        <tp:value-ref type="Call_State">Ended</tp:value-ref> and the
        <tp:member-ref>CallStateReason</tp:member-ref> property will
        change to (self handle,
        <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>,
        "org.freedesktop.Telepathy.Error.Rejected").</p>

      <h4>Ongoing calls</h4>

      <h5>Adding and removing contents</h5>

      <p>When a call is open, new contents can be added as long as the
        CM supports it. The
        <tp:member-ref>MutableContents</tp:member-ref> property will let
        the handler know whether further contents can be added or
        existing contents removed. An example of this is starting a
        voice call between a contact and then adding a video content.
        To do this, the should call
        <tp:member-ref>AddContent</tp:member-ref> like this:</p>

      <blockquote>
        <pre><tp:member-ref>AddContent</tp:member-ref>("video",
           <tp:value-ref type="Media_Stream_Type">Video</tp:value-ref>)</pre>
      </blockquote>

      <p>Assuming no errors, the new video content will be added to
        the call. telepathy-farstream will pick up the new content and
        perform the transport and codec negotiation automatically.
        telpathy-farstream will signal when the video is ready to
        show in the handler's user interface.</p>

      <p>A similar method is used for removing contents from a call,
        except that the <tp:dbus-ref
        namespace="ofdT.Call1.Content">Remove</tp:dbus-ref> method
        is on the <tp:dbus-ref
        namespace="ofdT.Call1">Content</tp:dbus-ref> object.</p>

      <h5>Ending the call</h5>

      <p>To end the call, the handler should call the
        <tp:member-ref>Hangup</tp:member-ref> method. The
        <tp:member-ref>CallState</tp:member-ref> property will change to
        <tp:value-ref type="Call_State">Ended</tp:value-ref> and
        <tp:member-ref>CallStateReason</tp:member-ref> will change
        to (self handle,
        <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>,
        "org.freedesktop.Telepathy.Error.Cancelled").</p>

      <p>If the other participant hangs up first then the
        <tp:member-ref>CallState</tp:member-ref> property will change to
        <tp:value-ref type="Call_State">Ended</tp:value-ref> and
        <tp:member-ref>CallStateReason</tp:member-ref> will change
        to (remote contact,
        <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>,
        "org.freedesktop.Telepathy.Error.Terminated").</p>

      <h4>Multi-party calls</h4>

      <h4>Requestable channel classes</h4>

      <p>The <tp:dbus-ref
        namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
        for <tp:dbus-ref
        namespace="ofdT.Channel.Type">Call1</tp:dbus-ref> channels
        can be:</p>

      <blockquote>
        <pre>
[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>,
            ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
            ...<tp:member-ref>InitialVideo</tp:member-ref>: True
          },
  Allowed = [ ...<tp:member-ref>InitialVideoName</tp:member-ref>,
              ...<tp:member-ref>InitialAudio</tp:member-ref>,
              ...<tp:member-ref>InitialAudioName</tp:member-ref>
            ]
),
( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>,
            ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
            ...<tp:member-ref>InitialAudio</tp:member-ref>: True
          },
  Allowed = [ ...<tp:member-ref>InitialAudioName</tp:member-ref>,
              ...<tp:member-ref>InitialVideo</tp:member-ref>,
              ...<tp:member-ref>InitialVideoName</tp:member-ref>
            ]
)]</pre></blockquote>

      <p>Clients aren't allowed to make outgoing calls that have
        neither initial audio nor initial video. Clearly, CMs
        which don't support video should leave out the first class and
        omit <tp:member-ref>InitialVideo</tp:member-ref> from the second
        class, and vice versa for CMs without audio support.</p>

      <p>Handlers should not close <tp:dbus-ref
        namespace="ofdT.Channel.Type">Call1</tp:dbus-ref> channels
        without first calling <tp:member-ref>Hangup</tp:member-ref> on
        the channel. If a Call handler crashes, the <tp:dbus-ref
        namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call
        <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the
        channel which SHOULD also imply a call to
        <tp:member-ref>Hangup</tp:member-ref>(<tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>,
        "org.freedesktop.Telepathy.Error.Terminated", "") before
        actually closing the channel.</p>

    </tp:docstring>

    <method name="SetRinging" tp:name-for-bindings="Set_Ringing">
      <tp:changed version="0.21.2">renamed from Ringing</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Indicate that the local user has been alerted about the incoming
          call.</p>

        <p>This method is only useful if the
          channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>
          property is False, and
          the <tp:member-ref>CallState</tp:member-ref> is
          <tp:value-ref type="Call_State">Initialised</tp:value-ref> (an incoming
          call is ready and waiting for the user to be notified). Calling this method
          SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit
          <tp:value-ref type="Call_Flags">Locally_Ringing</tp:value-ref>, and notify the
          remote contact that the local user has been alerted (if the
          protocol supports this); repeated calls to this method
          SHOULD succeed, but have no further effect.</p>

        <p>In all other states, this method SHOULD fail with the error
          NotAvailable.</p>
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The call was <tp:dbus-ref namespace="ofdT.Channel"
            >Requested</tp:dbus-ref>, so ringing does not make sense.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The call is no longer in state
            <tp:value-ref type="Call_State">Initialised</tp:value-ref>.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="SetQueued" tp:name-for-bindings="Set_Queued">
      <tp:changed version="0.21.2">renamed from Ringing</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Notifies the CM that the local user is already in a call, so this
          call has been put in a call-waiting style queue.</p>

        <p>This method is only useful if the
          channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>
          property is False, and
          the <tp:member-ref>CallState</tp:member-ref> is
          <tp:value-ref type="Call_State">Initialising</tp:value-ref> or
          <tp:value-ref type="Call_State">Initialised</tp:value-ref>. Calling this method
          SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit
          <tp:value-ref type="Call_Flags">Locally_Queued</tp:value-ref>, and notify the
          remote contact that the call is in a queue (if the
          protocol supports this); repeated calls to this method
          SHOULD succeed, but have no further effect.</p>

        <p>Locally_Queued is a little like Locally_Held, but applies to calls that have not
          been Accepted (the Locally_Queued flag should be unset by the CM when Accept
          is called). It should also be set in response to the state of the
          world, rather than in response to user action.</p>
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The call was <tp:dbus-ref namespace="ofdT.Channel"
            >Requested</tp:dbus-ref>, so queueing does not make sense.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The call is no longer in state
            <tp:value-ref type="Call_State">Initialising</tp:value-ref> or
            <tp:value-ref type="Call_State">Initialised</tp:value-ref>.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="Accept" tp:name-for-bindings="Accept">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>For incoming calls in state
          <tp:value-ref type="Call_State">Initialised</tp:value-ref>, accept the incoming call.
          This changes the <tp:member-ref>CallState</tp:member-ref> to
          <tp:value-ref type="Call_State">Accepted</tp:value-ref>.</p>

        <p>For outgoing calls in state
          <tp:value-ref type="Call_State">Pending_Initiator</tp:value-ref>, actually
          call the remote contact; this changes the
          <tp:member-ref>CallState</tp:member-ref> to
          <tp:value-ref type="Call_State">Initialising</tp:value-ref>.</p>

        <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p>

        <p>This method should be called exactly once per Call, by whatever
          client (user interface) is handling the channel.</p>

        <p>When this method is called, for each <tp:dbus-ref
          namespace="ofdT.Call1" >Content</tp:dbus-ref> whose
          <tp:dbus-ref namespace="ofdT.Call1.Content"
          >Disposition</tp:dbus-ref> is
          <tp:value-ref type="Call_Content_Disposition">Initial</tp:value-ref>, any
          streams where the <tp:dbus-ref
          namespace="ofdT.Call1.Stream">LocalSendingState</tp:dbus-ref>
          is <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:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The call is not in one of the states where this method makes sense.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="Hangup" tp:name-for-bindings="Hangup">
      <tp:docstring>
        Request that the call is ended. All contents will be removed
        from the Call so that the
        <tp:member-ref>Contents</tp:member-ref> property will be the
        empty list.
      </tp:docstring>

      <arg direction="in" name="Reason"
        type="u" tp:type="Call_State_Change_Reason">
        <tp:docstring>
          A generic hangup reason.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Detailed_Hangup_Reason"
        type="s" tp:type="DBus_Error_Name">
        <tp:docstring>
          A more specific reason for the call hangup, if one is available, or
          an empty string otherwise.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Message" type="s">
        <tp:docstring>
          A human-readable message to be sent to the remote contact(s).

          <tp:rationale>
            XMPP Jingle allows calls to be terminated with a human-readable
            message.
          </tp:rationale>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The call has already been ended.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="AddContent" tp:name-for-bindings="Add_Content">
      <tp:docstring>
        Request that a new <tp:dbus-ref
        namespace="ofdT.Call1">Content</tp:dbus-ref> of type
        Content_Type is added to the Call1. Handlers should check the
        value of the <tp:member-ref>MutableContents</tp:member-ref>
        property before trying to add another content as it might not
        be allowed.
      </tp:docstring>
      <arg direction="in" name="Content_Name" type="s">
        <tp:docstring>
          <p>The suggested name of the content to add.</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 a localized "audio", "video" or perhaps include
            some string identifying the source, such as a webcam
            identifier.
          </tp:rationale>

          <p>If there is already a content with the same name as this
            property then a sensible suffix should be added. For example,
            if this argument is "audio" but a content of the same name
            already exists, a sensible suffix such as " (1)" is appended
            to name the new content "audio (1)". A further content with the
            name "audio" would then be named "audio (2)".</p>

        </tp:docstring>
      </arg>
      <arg direction="in" name="Content_Type" type="u"
          tp:type="Media_Stream_Type">
        <tp:docstring>
          The media stream type of the content to be added to the
          call.
        </tp:docstring>
      </arg>
      <arg direction="in" name="InitialDirection" type="u"
          tp:type="Media_Stream_Direction">
        <tp:docstring>
          The requested initial direction of the new content.
        </tp:docstring>
      </arg>
      <arg direction="out" name="Content" type="o">
        <tp:docstring>
          Path to the newly-created <tp:dbus-ref
            namespace="org.freedesktop.Telepathy"
            >Call1.Content</tp:dbus-ref> object.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The media stream type given is invalid.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The media stream type requested is not implemented by the
            CM.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.Media.UnsupportedType">
          <tp:docstring>
            The media stream type requested is not supported by either the
            local or remote side.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
          <tp:docstring>
            The content type requested cannot be added to this
            call. Examples of why this might be the case include
            because a second video stream cannot be added, or a
            content cannot be added when the content set isn't
            mutable.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <signal name="ContentAdded"
            tp:name-for-bindings="Content_Added">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call1"
          >Content</tp:dbus-ref> is added to the call.</p>
      </tp:docstring>
      <arg name="Content" type="o">
        <tp:docstring>
          Path to the newly-created <tp:dbus-ref namespace="ofdT.Call1"
          >Content</tp:dbus-ref> object.
        </tp:docstring>
      </arg>
    </signal>

    <signal name="ContentRemoved" tp:name-for-bindings="Content_Removed">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call1"
          >Content</tp:dbus-ref> is removed from the call.</p>
      </tp:docstring>
      <arg name="Content" type="o">
        <tp:docstring>
          The <tp:dbus-ref namespace="ofdT.Call1"
          >Content</tp:dbus-ref> which was 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="Contents" type="ao" access="read"
      tp:name-for-bindings="Contents">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The list of <tp:dbus-ref
          namespace="ofdT.Call1">Content</tp:dbus-ref> objects that
          are part of this call. Change notification is via the
          <tp:member-ref>ContentAdded</tp:member-ref> and
          <tp:member-ref>ContentRemoved</tp:member-ref> signals.
        </p>
      </tp:docstring>
    </property>

    <tp:enum type="u" name="Call_State">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The state of a call, as a whole.</p>

        <p>The allowed transitions are:</p>

        <ul>
          <li>Pending_Initiator → Initialising (for outgoing calls,
            when <tp:member-ref>Accept</tp:member-ref> is called)</li>
          <li>Initialising → Initialised (for outgoing calls, when
            the remote client indicates that the user has been notified about
            the call. If the network is known not to provide feedback about whether
            the remote side is ringing, then the call should immediately be
            set to Initialised.</li>
          <li>Initialising → Initialised (for incoming calls, when e.g. the
            implementation has been initialised far enough that it is sensible
            to notify the user about the call (to reduce the probability that
            the user will pick up the call and have it immediately fail).
            The UI should then alert the user about the call, and call
            <tp:member-ref>SetRinging</tp:member-ref>)</li>
          <li>Initialised → Accepted (for outgoing calls to a contact,
            when the remote contact accepts the call; for incoming calls, when
            <tp:member-ref>Accept</tp:member-ref> is called.)</li>
          <li>Accepted → Active (when the local user successfully
            joins the call/conference, and media is known to be flowing
            successfully; also, when temporary connection problems are
            resolved (See below)). If the network is known not to provide
            feedback about when the call is properly connected, the call
            should immediately be set to Active.</li>
          <li>Active → Accepted (when there are temporary connection problems
            that the CM is aware of and able to recover from)</li>
          <li>any state → Ended (when the call is terminated
            normally, or when an error occurs that the CM is unable to recover
            from)</li>
        </ul>

        <p>Clients MAY consider unknown values from this enum to be an
          error - additional values will not be defined after the Call
          specification is declared to be stable.</p>
      </tp:docstring>

      <tp:enumvalue suffix="Unknown" value="0">
        <tp:docstring>
          The call state is not known. This call state MUST NOT appear as a
          value of the <tp:member-ref>CallState</tp:member-ref> property, but
          MAY be used by client code to represent calls whose state is as yet
          unknown.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Pending_Initiator" value="1">
        <tp:docstring>
          The initiator of the call hasn't accepted the call yet. This state
          only makes sense for outgoing calls, where it means that the local
          user has not yet sent any signalling messages to the remote user(s),
          and will not do so until <tp:member-ref>Accept</tp:member-ref> is
          called.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Initialising" value="2">
        <tp:docstring>
          Progress has been made in placing the call, but the
          contact has not been made aware of the call yet. This corresponds to SIP's
          status code 183 Session Progress, and should be used for the period
          where the CM is waiting for the streaming implementation to
          initialise (before sending the initial INVITE or equivalent) and when the
          outgoing call has reached a gateway or ICE negotiation is pending.
          UIs should not produce a dialtone or start ringing if the call is in
          this state.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Initialised" value="3">
        <tp:docstring>
          In the outgoing case: at least one called user has been alerted
          about the call (a SIP 180 (Ringing) packet or equivalent has been
          received) but none have answered, so the call cannot go to Accepted
          (use <tp:value-ref type="Call_Member_Flags">Ringing</tp:value-ref> to determine which
          members have been informed and which haven't, if you care). UIs
          SHOULD produce a dialtone for outgoing calls in this state.

          In the incoming case, the local user should be informed of the call
          as soon as the call reaches this state (and
          <tp:member-ref>SetRinging</tp:member-ref> should be called
          to inform the CM that this has happened, so that it can relay this
          fact to the caller using a SIP 180 (Ringing) packet or equivalent).
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Accepted" value="4">
        <tp:docstring>
          The contact being called has accepted the call, but the call is not
          in the Active state (The most common reason for this is that the
          streaming implementation hasn't connected yet).
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Active" value="5">
        <tp:docstring>
          The contact being called has accepted the call, and discourse between
          at least two parties should now be possible.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Ended" value="6">
        <tp:docstring>
          The call has ended, either via normal termination or an error.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u">
      <tp:docstring>
        A set of flags representing additional information than is available
        in <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make
        sense in a particular (or may explain why a call is in a specific
        state).
      </tp:docstring>
      <tp:flag suffix="Locally_Held" value="1">
        <tp:docstring>
          The call has been put on hold by the local user, e.g. using
          the <tp:dbus-ref namespace="ofdT.Channel.Interface"
          >Hold</tp:dbus-ref> interface. This flag SHOULD only be set
          if there is at least one Content, and all Contents are
          locally held.

          <tp:rationale>
            Otherwise, in transient situations where some but not all contents
            are on hold, UIs would falsely indicate that the call as a whole
            is on hold, which could lead to the user saying something they'll
            regret, while under the impression that the other contacts can't
            hear them!

            This flag exists as a simplified proxy for <tp:dbus-ref
            namespace="ofdT.Channel.Interface.Hold"
              >HoldStateChanged</tp:dbus-ref>,
            to reduce the number of signals that need to be
            listened to by a simple UI.
          </tp:rationale>
        </tp:docstring>
      </tp:flag>

      <tp:flag suffix="Locally_Ringing" value="2">
        <tp:docstring>
          This flag exists for observability of the
          <tp:member-ref>SetRinging</tp:member-ref> method (e.g. so that
          loggers can tell whether the call got as far as alerting the user,
          or whether something went wrong before then). It should be set when
          the SetRinging is called, and unset when the call leaves
          <tp:value-ref type="Call_State">Initialised</tp:value-ref>.
        </tp:docstring>
      </tp:flag>

      <tp:flag suffix="Locally_Queued" value="4">
        <tp:docstring>
          This flag exists for observability of the
          <tp:member-ref>SetQueued</tp:member-ref> method. It should be set
          when the SetQueued is called, and unset when the call leaves
          <tp:value-ref type="Call_State">Initialising</tp:value-ref> or
          <tp:value-ref type="Call_State">Initialised</tp:value-ref>.
        </tp:docstring>
      </tp:flag>

      <tp:flag suffix="Forwarded" value="8">
        <tp:docstring>
          The initiator of the call originally called a contact other than the
          current recipient of the call, but the call was then forwarded or
          diverted. This flag only makes sense on outgoing calls. It SHOULD be
          set or unset according to informational messages from other
          contacts.
        </tp:docstring>
      </tp:flag>

      <tp:flag suffix="Clearing" value="16">
        <tp:docstring>
          This flag only occurs when the CallState is Ended. The call with
          this flag set has ended, but not all resources corresponding to the
          call have been freed yet.

          Depending on the protocol there might be some audible feedback while
          the clearing flag is set.

          <tp:rationale>
            In calls following the ITU-T Q.931 standard there is a period of
            time between the call ending and the underlying channel being
            completely free for re-use.
          </tp:rationale>
        </tp:docstring>
      </tp:flag>

    </tp:flags>

    <property name="CallStateDetails"
      tp:name-for-bindings="Call_State_Details" type="a{sv}" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A map used to provide optional extensible details for the
          <tp:member-ref>CallState</tp:member-ref>,
          <tp:member-ref>CallFlags</tp:member-ref> and/or
          <tp:member-ref>CallStateReason</tp:member-ref>.</p>

        <p>Well-known keys and their corresponding value types include:</p>

        <dl>
          <dt>hangup-message - s</dt>
          <dd>An optional human-readable message sent when the call was ended,
            corresponding to the Message argument to the
            <tp:member-ref>Hangup</tp:member-ref> method. This is only
            applicable when the call state is <tp:value-ref type="Call_State">Ended</tp:value-ref>.
            <tp:rationale>
              XMPP Jingle can send such messages.
            </tp:rationale>
          </dd>

          <dt>queue-message - s</dt>
          <dd>An optional human-readable message sent when the local contact
            is being held in a queue. This is only applicable when
            <tp:value-ref type="Call_Flags">Locally_Queued</tp:value-ref> is in the call flags.
            <tp:rationale>
              SIP 182 notifications can have human-readable messages attached.
            </tp:rationale>
          </dd>

          <dt>debug-message - s</dt>
          <dd>A message giving further details of any error indicated by the
            <tp:member-ref>CallStateReason</tp:member-ref>. This will not
            normally be localized or suitable for display to users, and is only
            applicable when the call state is
            <tp:value-ref type="Call_State">Ended</tp:value-ref>.</dd>

          <dt>balance-required - i</dt>
          <dd>Optionally included when a call cannot be connected because
            there is <tp:error-ref>InsufficientBalance</tp:error-ref>,
            indicating what the required balance would be to place this call.
            The value of this key has the same units and scale as
            <tp:dbus-ref namespace="ofdT.Connection.Interface.Balance">AccountBalance</tp:dbus-ref>.
            </dd>

          <dt>forwarded-to - u</dt>
          <dd>Optionally included when the
            <tp:member-ref>CallStateReason</tp:member-ref> is
            Forwarded. It indicates the handle to whom the Call was
            forwarded.</dd>

          <dt>forwarded-to-id - s</dt>
          <dd>The string that would result from inspecting the
            <code>forwarded-to</code> key
            (i.e. the contact's identifier in the IM protocol).</dd>
        </dl>
      </tp:docstring>
    </property>

    <property name="CallState" type="u" access="read"
      tp:name-for-bindings="Call_State" tp:type="Call_State">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The current high-level state of this call. The
          <tp:member-ref>CallFlags</tp:member-ref> provide additional
          information, and the <tp:member-ref>CallStateReason</tp:member-ref>
          and <tp:member-ref>CallStateDetails</tp:member-ref> explain the
          reason for the current values for those properties.</p>

        <p>Note that when in a conference call, this property is
          purely to show your state in joining the call. The receiver
          (or remote contact) in this context is the conference server
          itself. The property does not change when other call members'
          states change.</p>

        <p>Clients MAY consider unknown values in this property to be an
          error.</p>
      </tp:docstring>
    </property>

    <property name="CallFlags" type="u" access="read"
      tp:name-for-bindings="Call_Flags" tp:type="Call_Flags">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Flags representing the status of the call as a whole,
          providing more specific information than the
          <tp:member-ref>CallState</tp:member-ref>.</p>

        <p>Clients are expected to ignore unknown flags in this property,
          without error.</p>

        <p>When an ongoing call is active and not on hold or has any
          other problems, this property will be 0.</p>
      </tp:docstring>
    </property>

    <tp:enum name="Call_State_Change_Reason" type="u">
      <tp:docstring>
        A simple representation of the reason for a change in the call's
        state, which may be used by simple clients, or used as a fallback
        when the DBus_Reason member of a <tp:type>Call_State_Reason</tp:type>
        struct is not understood.
      </tp:docstring>

      <tp:enumvalue suffix="Unknown" value="0">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          We just don't know. Unknown values of this enum SHOULD also be
          treated like this.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Progress_Made" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          Situation normal. Progress has been made in the setup/teardown of
          the call (and it didn't require any user interaction).
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="User_Requested" value="2">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The change was requested by the contact indicated by the Actor
            member of a <tp:type>Call_State_Reason</tp:type> struct.</p>

          <p>The DBus_Reason SHOULD be the empty string if the call
            was terminated normally, but MAY be a non-empty error name
            to indicate error-like call termination reasons (kicked from
            a conference by a moderator, etc.).</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Forwarded" value="3">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The call was forwarded. If known, the handle of the
          contact the call was forwarded to will be indicated by the
          "forwarded-to" member of a
          <tp:member-ref>CallStateDetails</tp:member-ref> dictionnary
          in the <tp:member-ref>CallStateChanged</tp:member-ref>
          signal.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Rejected" value="4">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The <tp:member-ref>CallState</tp:member-ref> changed from
            <tp:value-ref type="Call_State">Initialised</tp:value-ref> or
            <tp:value-ref type="Call_State">Ended</tp:value-ref> (or a content's direction
            changed) because it was rejected by the remote user.</p>
          <p>Corresponds to <tp:error-ref>Rejected</tp:error-ref></p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="No_Answer" value="5">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The <tp:member-ref>CallState</tp:member-ref> changed from
            <tp:value-ref type="Call_State">Initialised</tp:value-ref> or
            <tp:value-ref type="Call_State">Ended</tp:value-ref> because the initiator
            ended the call before the receiver accepted it. With an
            incoming call this state change reason signifies a missed
            call, or one that was picked up elsewhere before it was
            picked up here.</p>
          <p>Corresponds to <tp:error-ref>NoAnswer</tp:error-ref> or
            <tp:error-ref>PickedUpElsewhere</tp:error-ref></p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Invalid_Contact" value="6">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The <tp:member-ref>CallState</tp:member-ref> changed because one
            of the addresses does not exist on the network.</p>
          <p>Corresponds to <tp:error-ref>DoesNotExist</tp:error-ref></p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Permission_Denied" value="7">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The <tp:member-ref>CallState</tp:member-ref> changed because the
          local user is not authorised.</p>
          <p>Corresponds to <tp:error-ref>PermissionDenied</tp:error-ref> or
            <tp:error-ref>InsufficientBalance</tp:error-ref>
            </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Busy" value="8">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The <tp:member-ref>CallState</tp:member-ref> changed from
            <tp:value-ref type="Call_State">Initialised</tp:value-ref>
            <tp:value-ref type="Call_State">Ended</tp:value-ref> because the receiver is busy
            (e.g. is already engaged in another call, and has not placed the
            initiator in a call-waiting queue).</p>
          <p>Corresponds to <tp:error-ref>Busy</tp:error-ref></p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Internal_Error" value="9">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There has been an unexpected error in either the CM or some other
            local component.</p>
          <p>Corresponds to <tp:error-ref>Confused</tp:error-ref> or
          <tp:error-ref>Media.StreamingError</tp:error-ref>
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Service_Error" value="10">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There has been an unexpected error in the server or some other
            remote component.</p>
          <p>Corresponds to
            <tp:error-ref>ServiceConfused</tp:error-ref>
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Network_Error" value="11">
        <tp:added version="0.21.2"/>
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There has been a network error related to the CM or the
            signalling part of the call (compare and contrast:
            Streaming_Error).</p>
          <p>Corresponds to
            <tp:error-ref>NetworkError</tp:error-ref></p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Media_Error" value="12">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Some aspect of the content is unsupported so has to be
            removed from the call.</p>
          <p>Corresponds to <tp:error-ref>Media.UnsupportedType</tp:error-ref>
            or <tp:error-ref>Media.CodecsIncompatible</tp:error-ref>
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Connectivity_Error" value="13">
        <tp:docstring>
          <p>It was not possible for the streaming implementation to connect
            to any of the users participating in this call or content.</p>
          <p>Corresponds to <tp:error-ref>ConnectionFailed</tp:error-ref> or
            <tp:error-ref>ConnectionLost</tp:error-ref></p>
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:struct name="Call_State_Reason">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A description of the reason for a change to the
          <tp:member-ref>CallState</tp:member-ref> and/or
          <tp:member-ref>CallFlags</tp:member-ref>.</p>
      </tp:docstring>

      <tp:member type="u" tp:type="Contact_Handle" name="Actor">
        <tp:docstring>
          The contact responsible for the change, or 0 if no contact was
          responsible.
        </tp:docstring>
      </tp:member>

      <tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason">
        <tp:docstring>
          The reason, chosen from a limited set of possibilities defined by
          the Telepathy specification. If
          <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref> then
          the Actor member will dictate whether it was the local user or
          a remote contact responsible.
        </tp:docstring>
      </tp:member>

      <tp:member type="s" tp:type="DBus_Error_Name" name="DBus_Reason">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A specific reason for the change, which may be a D-Bus error in
            the Telepathy namespace, a D-Bus error in any other namespace
            (for implementation-specific errors), or the empty string to
            indicate that the state change was not an error.</p>

          <p>This SHOULD be an empty string for changes to any state other
            than Ended.</p>

          <p>The errors Cancelled and Terminated SHOULD NOT be used here;
            an empty string SHOULD be used instead.</p>

          <tp:rationale>
            <p>Those error names are used to indicate normal call
              termination by the local user or another user, respectively,
              in contexts where a D-Bus error name must appear.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:member>

      <tp:member type="s" name="Message">
        <tp:docstring>
          An optional debug message, to expediate debugging the potentially
          many processes involved in a call. This may be communicated across
          the network in protocols that support doing so, but it is not
          essential.
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <property name="CallStateReason" tp:name-for-bindings="Call_State_Reason"
      type="(uuss)" access="read"  tp:type="Call_State_Reason">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The reason for the last change to the
          <tp:member-ref>CallState</tp:member-ref> and/or
          <tp:member-ref>CallFlags</tp:member-ref>. The
          <tp:member-ref>CallStateDetails</tp:member-ref> MAY provide additional
          information.</p>
      </tp:docstring>
    </property>

    <signal name="CallStateChanged"
            tp:name-for-bindings="Call_State_Changed">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when the state of the call as a whole changes.</p>

        <p>This signal is emitted for any change in the properties
          corresponding to its arguments, even if the other properties
          referenced remain unchanged.</p>
      </tp:docstring>

      <arg name="Call_State" type="u" tp:type="Call_State">
        <tp:docstring>
          The new value of the <tp:member-ref>CallState</tp:member-ref>
          property.
        </tp:docstring>
      </arg>

      <arg name="Call_Flags" type="u" tp:type="Call_Flags">
        <tp:docstring>
          The new value of the <tp:member-ref>CallFlags</tp:member-ref>
          property.
        </tp:docstring>
      </arg>

      <arg name="Call_State_Reason" type="(uuss)" tp:type="Call_State_Reason">
        <tp:docstring>
          The new value of the <tp:member-ref>CallStateReason</tp:member-ref>
          property.
        </tp:docstring>
      </arg>

      <arg name="Call_State_Details" type="a{sv}">
        <tp:docstring>
          The new value of the <tp:member-ref>CallStateDetails</tp:member-ref>
          property.
        </tp:docstring>
      </arg>
    </signal>

    <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming"
        type="b" access="read" tp:immutable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If this property is True, all of the media streaming is done by some
          mechanism outside the scope of Telepathy.</p>

        <tp:rationale>
          <p>A connection manager might be intended for a specialized hardware
            device, which will take care of the audio streaming (e.g.
            telepathy-ring, which uses GSM hardware which does the actual
            audio streaming for the call).</p>
        </tp:rationale>

        <p>If this is False, the handler is responsible for doing the actual
          media streaming for at least some contents itself. Those contents
          will have the <tp:dbus-ref namespace="ofdT.Call1.Content.Interface"
          >Media</tp:dbus-ref> interface, to communicate the necessary
          information to a streaming implementation. Connection managers SHOULD
          operate like this, if possible.</p>

        <tp:rationale>
          <p>Many connection managers (such as telepathy-gabble) only do the
            call signalling, and expect the client to do the actual streaming
            using something like
            <a href="http://farsight.freedesktop.org/">Farsight</a>, to improve
            latency and allow better UI integration.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <tp:flags type="u" name="Call_Member_Flags" value-prefix="Call_Member_Flag">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A set of flags representing the status of a remote contact in a
          call.</p>

        <p>It is protocol- and client-specific whether a particular contact
          will ever have a particular flag set on them, and Telepathy clients
          SHOULD NOT assume that a flag will ever be set.</p>

        <tp:rationale>
          <p>180 Ringing in SIP, and its equivalent in XMPP, are optional
            informational messages, and implementations are not required
            to send them. The same applies to the messages used to indicate
            hold state.</p>
        </tp:rationale>
      </tp:docstring>

      <tp:flag suffix="Ringing" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The remote contact's client has told us that the contact has been
            alerted about the call but has not responded.</p>

          <tp:rationale>
            <p>This is a flag per member, not a flag for the call as a whole,
              because in Muji conference calls, you could invite someone and
              have their state be "ringing" for a while.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:flag>

      <tp:flag suffix="Held" value="2">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The call member has put this call on hold.</p>

          <tp:rationale>
            <p>This is a flag per member, not a flag for the call as a whole,
              because in conference calls, any member could put the conference
              on hold.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:flag>

      <tp:flag suffix="Conference_Host" value="4">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          This contact has merged this call into a conference. Note that GSM
          provides a notification when the remote party merges a call into a
          conference, but not when it is split out again; thus, this flag can
          only indicate that the call has been part of a conference at some
          point. If a GSM connection manager receives a notification that a
          call has been merged into a conference a second time, it SHOULD
          represent this by clearing and immediately re-setting this flag on
          the remote contact.
        </tp:docstring>
      </tp:flag>
    </tp:flags>

    <tp:mapping name="Call_Member_Map" array-name="Call_Member_Map_List">
      <tp:docstring>A mapping from handles to their current state in the call.
        </tp:docstring>
      <tp:member type="u" tp:type="Handle" name="key"/>
      <tp:member type="u" tp:type="Call_Member_Flags" name="Flag"/>
    </tp:mapping>

    <signal name="CallMembersChanged"
      tp:name-for-bindings="Call_Members_Changed">
      <tp:docstring>
        Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property
        changes in any way, either because contacts have been added to the
        call, contacts have been removed from the call, or contacts' flags
        have changed.
      </tp:docstring>

      <arg name="Flags_Changed" type="a{uu}" tp:type="Call_Member_Map">
        <tp:docstring>
          A map from members of the call to their new call member flags,
          including at least the members who have been added to
          <tp:member-ref>CallMembers</tp:member-ref>, and the members whose
          flags have changed.
        </tp:docstring>
      </arg>
      <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The identifiers of the contacts in the <var>Flags_Changed</var> map.
        </tp:docstring>
      </arg>
      <arg name="Removed"  type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          A list of members who have left the call, i.e. keys to be removed
          from <tp:member-ref>CallMembers</tp:member-ref>.
        </tp:docstring>
      </arg>
      <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason">
        <tp:docstring>
          A structured reason for the change.
        </tp:docstring>
      </arg>
    </signal>

    <property name="CallMembers" tp:name-for-bindings="Call_Members"
      type="a{uu}" access="read" tp:type="Call_Member_Map">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A mapping from the remote contacts that are part of this call to flags
          describing their status. This mapping never has the local user's handle
          as a key.</p>

        <p>When the call ends, this property should be an empty list,
          and notified with
          <tp:member-ref>CallMembersChanged</tp:member-ref></p>

        <p>If the Call implements
          <tp:dbus-ref namespace="ofdT.Channel.Interface"
          >Group</tp:dbus-ref> and the Group members are
          channel-specific handles, then this call SHOULD also use
          channel-specific handles.</p>

        <p>Anonymous members are exposed as channel-specific handles
          with no owner.</p>
      </tp:docstring>
    </property>

    <property name="MemberIdentifiers" type="a{us}" tp:type="Handle_Identifier_Map"
      access="read" tp:name-for-bindings="Member_Identifiers">
      <tp:docstring>
        The string identifiers for handles mentioned in
        <tp:member-ref>CallMembers</tp:member-ref>, to
        give clients the minimal information necessary to create contacts
        without waiting for round-trips.
      </tp:docstring>
    </property>

    <property name="InitialTransport" tp:name-for-bindings="Initial_Transport"
      type="u" tp:type="Stream_Transport_Type" access="read"
      tp:requestable="yes" tp:immutable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If set on a requested channel, this indicates the transport that
          should be used for this call. Where not applicable, this property
          is defined to be <tp:value-ref type="Stream_Transport_Type">Unknown</tp:value-ref>,
          in particular, on CMs with hardware streaming.</p>

        <tp:rationale>
          When implementing a voip gateway one wants the outgoing leg of the
          gatewayed to have the same transport as the incoming leg. This
          property allows the gateway to request a Call with the right
          transport from the CM.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="InitialAudio" tp:name-for-bindings="Initial_Audio"
      type="b" access="read" tp:immutable="yes" tp:requestable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If set to True in a channel request that will create a new channel,
          the connection manager should immediately attempt to establish an
          audio stream to the remote contact, making it unnecessary for the
          client to call <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">AddContent</tp:dbus-ref>.</p>

        <p>If this property, or InitialVideo, is passed to EnsureChannel
          (as opposed to CreateChannel), the connection manager SHOULD ignore
          these properties when checking whether it can return an existing
          channel as suitable; these properties only become significant when
          the connection manager has decided to create a new channel.</p>

        <p>If True on a requested channel, this indicates that the audio
          stream has already been requested and the client does not need to
          call RequestStreams, although it MAY still do so.</p>

        <p>If True on an unrequested (incoming) channel, this indicates that
          the remote contact initially requested an audio stream; this does
          not imply that that audio stream is still active (as indicated by
          <tp:dbus-ref namespace="ofdT.Channel.Type.Call1"
          >Contents</tp:dbus-ref>).</p>

        <p>The name of this new content can be decided by using the
          <tp:member-ref>InitialAudioName</tp:member-ref> property.</p>

        <p>Connection managers that support the <tp:dbus-ref
          namespace="ofdT.Connection.Interface">ContactCapabilities</tp:dbus-ref>
          interface SHOULD represent the capabilities of receiving audio
          and/or video calls by including a channel class in
          a contact's capabilities with ChannelType = Call
          in the fixed properties dictionary, and InitialAudio and/or
          InitialVideo in the allowed properties list. Clients wishing to
          discover whether a particular contact is likely to be able to
          receive audio and/or video calls SHOULD use this information.</p>

        <tp:rationale>
          <p>Not all clients support video calls, and it would also be
            possible (although unlikely) to have a client which could only
            stream video, not audio.</p>
        </tp:rationale>

        <p>Clients that are willing to receive audio and/or video calls
          SHOULD include the following among their channel classes if
          calling <tp:dbus-ref
          namespace="ofdT.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
          (clients of a <tp:dbus-ref
          namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
          SHOULD instead arrange for the ChannelDispatcher to do this,
          by including the filters in their <tp:dbus-ref
          namespace="ofdT.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
          properties):</p>

        <ul>
          <li>{ ChannelType = Call }</li>
          <li>{ ChannelType = Call, InitialAudio = True }
            if receiving calls with audio is supported</li>
          <li>{ ChannelType = Call, InitialVideo = True }
            if receiving calls with video is supported</li>
        </ul>

        <tp:rationale>
          <p>Connection managers for protocols with capability discovery,
            like XMPP, need this information to advertise the appropriate
            capabilities for their protocol.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="InitialVideo" tp:name-for-bindings="Initial_Video"
      type="b" access="read" tp:immutable="yes" tp:requestable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for
          a video stream. This property is immutable (cannot change).</p>

        <p>In particular, note that if this property is False, this does not
          imply that an active video stream has not been added, only that no
          video stream was active at the time the channel appeared.</p>

        <p>This property is the correct way to discover whether connection
          managers, contacts etc. support video calls; it appears in
          capabilities structures in the same way as InitialAudio.</p>
      </tp:docstring>
    </property>

    <property name="InitialAudioName" tp:name-for-bindings="Initial_Audio_Name"
      type="s" access="read" tp:immutable="yes" tp:requestable="yes">
      <tp:added version="0.21.2"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If <tp:member-ref>InitialAudio</tp:member-ref> is set to
          True, then this property will name the intial audio content
          with the value of this property.</p>

        <tp:rationale>
          <p>Content names are meant to be significant, but if no name
            can be given to initial audio content, then its name cannot
            be meaningful or even localized.</p>
        </tp:rationale>

        <p>If this property is empty or missing from the channel
          request and InitialAudio is True, then the CM must come up
          with a sensible for the content, such as "audio".</p>

        <p>If the protocol has no concept of stream names then this
          property will not show up in the allowed properties list of
          the Requestable Channel Classes for call channels.</p>
      </tp:docstring>
    </property>

    <property name="InitialVideoName" tp:name-for-bindings="Initial_Video_Name"
      type="s" access="read" tp:immutable="yes" tp:requestable="yes">
      <tp:added version="0.21.2"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The same as
          <tp:member-ref>InitialAudioName</tp:member-ref>, but for a
          video stream created by setting
          <tp:member-ref>InitialVideo</tp:member-ref> to True. This
          property is immutable and so cannot change.</p>
      </tp:docstring>
    </property>

    <property name="MutableContents" tp:name-for-bindings="Mutable_Contents"
      type="b" access="read" tp:immutable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If True, a stream of a different content type can be added
        after the Channel has been requested </p>

        <p>If this property is missing, clients SHOULD assume that it is False,
          and thus that the channel's streams cannot be changed once the call
          has started.</p>

        <p>If this property isn't present in the "allowed" set in any of the
          Call entries contact capabilities, then user interfaces MAY choose to
          show a separate "call" option for each class of call.</p>

          <tp:rationale>
            <p>For example, once an audio-only Google Talk call has started,
              it is not possible to add a video stream; both audio and video
              must be requested at the start of the call if video is desired.
              User interfaces may use this pseudo-capability as a hint to
              display separate "Audio call" and "Video call" buttons, rather
              than a single "Call1" button with the option to add and remove
              video once the call has started for contacts without this flag.
            </p>
          </tp:rationale>
      </tp:docstring>
    </property>

    <tp:hct name="audio">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>This client supports audio calls.</p>
      </tp:docstring>
    </tp:hct>

    <tp:hct name="video">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>This client supports video calls.</p>
      </tp:docstring>
    </tp:hct>

    <tp:hct name="gtalk-p2p">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The client can implement streaming for streams whose <tp:dbus-ref
          namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref>
          property is <tp:value-ref type="Stream_Transport_Type">GTalk_P2P</tp:value-ref>.</p>
      </tp:docstring>
    </tp:hct>

    <tp:hct name="ice">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The client can implement streaming for streams whose <tp:dbus-ref
          namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref>
          property is <tp:value-ref type="Stream_Transport_Type">ICE</tp:value-ref>.</p>
      </tp:docstring>
    </tp:hct>

    <tp:hct name="wlm-2009">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The client can implement streaming for streams whose <tp:dbus-ref
          namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref>
          property is <tp:value-ref type="Stream_Transport_Type">WLM_2009</tp:value-ref>.</p>
      </tp:docstring>
    </tp:hct>

    <tp:hct name="shm">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The client can implement streaming for streams whose <tp:dbus-ref
          namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref>
          property is <tp:value-ref type="Stream_Transport_Type">SHM</tp:value-ref>.</p>
      </tp:docstring>
    </tp:hct>

    <tp:hct name="video/h264" is-family="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The client supports media streaming with H264 (etc.).</p>

        <p>This handler capability token is a one of a family
          of similar tokens: for any other audio or video codec whose MIME
          type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
          capability token of this form may exist (the subtype MUST appear
          in lower case in this context). Clients MAY support more
          codecs than they explicitly advertise support for; clients SHOULD
          explicitly advertise support for their preferred codec(s), and
          for codecs like H264 that are, in practice, significant in codec
          negotiation.</p>

        <tp:rationale>
          <p>For instance, the XMPP capability used by the Google Video
            Chat web client to determine whether a client is compatible
            with it requires support for H264 video, so an XMPP
            connection manager that supports this version of Jingle should
            not advertise the Google Video Chat capability unless there
            is at least one installed client that declares that it supports
            <code>video/h264</code> on Call channels.</p>
        </tp:rationale>

        <p>For example, a client could advertise support for audio and video
          calls using Speex, Theora and H264 by having five handler capability
          tokens in its <tp:dbus-ref
          namespace="ofdT.Client.Handler">Capabilities</tp:dbus-ref>
          property:</p>

        <ul>
          <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/audio</code></li>
          <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/audio/speex</code></li>
          <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/video</code></li>
          <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/video/theora</code></li>
          <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/video/h264</code></li>
        </ul>

        <p>Clients MAY have media signalling abilities without explicitly
          supporting any particular codec, and connection managers SHOULD
          support this usage.</p>

        <tp:rationale>
          <p>This is necessary to support gatewaying between two Telepathy
            connections, in which case the available codecs might not be
            known to the gatewaying process.</p>
        </tp:rationale>
      </tp:docstring>
    </tp:hct>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->