path: root/spec/Call_Stream.xml

<?xml version="1.0" ?>
<node name="/Call_Stream"
  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.Stream">
    <tp:added version="0.19.0">(draft 1)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>One stream inside a <tp:dbus-ref
      namespace="ofdT.Call1">Content</tp:dbus-ref>.  A stream is
      a single flow of packets to and from a single remote endpoint.
      If your call connects to multiple people, you could have
      multiple streams.</p>
      <p>For protocols that support muting streams separately, this object MAY
      also implement the <tp:dbus-ref
      namespace="ofdT.Call1.Interface">Mute</tp:dbus-ref> interface</p>
    </tp:docstring>

    <method name="SetSending" tp:name-for-bindings="Set_Sending">
      <tp:docstring>
        Set the stream to start or stop sending media from the local
        user to other contacts.
      </tp:docstring>

      <arg name="Send" type="b" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If True, the
            <tp:member-ref>LocalSendingState</tp:member-ref> should
            change to <tp:value-ref type="Sending_State">Sending</tp:value-ref>, if it isn't
            already.</p>

          <p>If False, the
            <tp:member-ref>LocalSendingState</tp:member-ref> should
            change to <tp:value-ref type="Sending_State">None</tp:value-ref>, if it isn't
            already.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" />
        <tp:error name="org.freedesktop.Telepathy.Error.NotYet">
          <tp:docstring>If the call has not been accepted yet, calling
            SetSending(True) is an error. See
            <tp:member-ref>LocalSendingState</tp:member-ref> for details.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving">
      <tp:docstring>
        <p>Request that a remote contact stops or starts sending on
          this stream.</p>

        <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref>
          property defines whether the protocol allows the local user to
          request the other side start sending on this stream.</p>
      </tp:docstring>

      <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Contact from which sending is requested</p>
        </tp:docstring>
      </arg>

      <arg name="Receive" type="b" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If true, request that the given contact starts to send media.
            If false, request that the given contact stops sending media.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The request contact is valid but is not involved in this
            stream.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The protocol does not allow the local user to request the
            other side starts sending on this stream.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <signal name="RemoteMembersChanged"
        tp:name-for-bindings="Remote_Members_Changed">
      <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed>
      <tp:changed version="0.21.3">renamed from MembersChanged to RemoteMembersChanged</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes.
      </tp:docstring>

      <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map">
        <tp:docstring>
          A mapping from channel-specific handles to their updated sending
          state, whose keys include at least the members who were added,
          and the members whose states 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>Updates</var> map.
        </tp:docstring>
      </arg>
      <arg name="Removed" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          The channel-specific handles that were removed from the keys
          of the <tp:member-ref>RemoteMembers</tp:member-ref>
          property, as a result of the contact leaving this stream
        </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>

    <signal name="LocalSendingStateChanged"
        tp:name-for-bindings="Local_Sending_State_Changed">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes.
      </tp:docstring>

      <arg name="State" type="u" tp:type="Sending_State">
        <tp:docstring>
          The new value of
          <tp:member-ref>LocalSendingState</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>

    <tp:enum name="Sending_State" type="u">
      <tp:docstring>
        Enum indicating whether a contact is sending media.
      </tp:docstring>

      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>
          The contact is not sending media and has not been asked to
          do so.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Pending_Send" value="1">
        <tp:docstring>
          The contact has been asked to start sending media.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Sending" value="2">
        <tp:docstring>
          The contact is sending media.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Pending_Stop_Sending" value="3">
        <tp:docstring>
          The contact has been asked to stop sending media.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:mapping name="Contact_Sending_State_Map">
      <tp:docstring>
        A map from a contact to his or her sending state.
      </tp:docstring>
      <tp:member name="Contact" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          The contact handle.
        </tp:docstring>
      </tp:member>
      <tp:member name="Sending" type="u" tp:type="Sending_State">
         <tp:docstring>
           The sending state of the contact.
         </tp:docstring>
      </tp:member>
    </tp:mapping>

    <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 stream, such as <tp:dbus-ref
            namespace="ofdT.Call1">Stream.Interface.Media</tp:dbus-ref>.
          This SHOULD NOT include the Stream interface itself, and cannot
          change once the stream has been created.</p>
      </tp:docstring>
    </property>

    <property name="RemoteMembers" tp:name-for-bindings="Remote_Members"
        type="a{uu}" access="read" tp:type="Contact_Sending_State_Map">
      <tp:changed version="0.21.2">renamed from Senders</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A map from remote contacts to their sending state.</p>

        <p>Media sent to this stream will be sent to all members listed here.
          All members listed here will also appear in <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">CallMembers</tp:dbus-ref>,
          and each CallMembers member will be listed in at most one Stream per
          Content. Therefore, to hide things from a member of the
          call, UIs only need to mute one Stream per Content.</p>

        <p>Contacts' handles in this map indicate whether they are
          sending media to this stream. Sending_State_Pending_Send indicates
          contacts who are not sending but have been asked to do so. The
          local user's sending state is shown in <tp:member-ref
          >LocalSendingState</tp:member-ref>.</p>

        <p>This mapping is also used by the streaming implementation to map
          from <tp:dbus-ref namespace="ofdT.Call1.Content"
          >MediaDescription</tp:dbus-ref>s to Streams. In this use-case,
          all of the senders in this stream will be represented in
          <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media"
          >RemoteMediaDescriptions</tp:dbus-ref>. This use-case should not
          affect anything that does not handle media streaming.</p>
      </tp:docstring>
    </property>

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

    <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State"
        type="u" access="read" tp:type="Sending_State">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The local user's sending state. Media sent on this stream
          should be assumed to be received, directly or indirectly, by
          every other contact in the
          <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change
          notification is given via the
          <tp:member-ref>LocalSendingStateChanged</tp:member-ref>
          signal.</p>

        <tp:rationale>
          Implementations of the first Call draft had the self handle
          in the <tp:member-ref>RemoteMembers</tp:member-ref> (then
          called Members) map and this showed that it's annoying
          having to keep track of the self handle so that it can be
          special-cased.
        </tp:rationale>

        <p>A value of <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> for
          this property indicates that the other side requested the
          local user start sending media (which can be done by calling either
          <tp:member-ref>SetSending</tp:member-ref> or <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref>).</p>

        <p>When <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref> is
          called, all streams with a local sending state of
          <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> and the associated
          <tp:dbus-ref namespace="ofdT.Call1.Content"
          >Disposition</tp:dbus-ref> set to
          <tp:value-ref type="Call_Content_Disposition">Initial</tp:value-ref> are
          automatically set to sending.</p>
      </tp:docstring>
    </property>

    <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving"
        type="b" access="read" tp:immutable="yes">
      <tp:added version="0.21.2"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If true, the user can request that a remote contact starts
          sending on this stream.</p>

        <tp:rationale>Not all protocols allow the user to ask the
          other side to start sending media.</tp:rationale>
      </tp:docstring>
    </property>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->