path: root/spec/Call_Stream_Endpoint.xml

<?xml version="1.0" ?>
<node name="/Call_Stream_Endpoint"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
      modify it under the terms of the GNU Lesser General Public
      License as published by the Free Software Foundation; either
      version 2.1 of the License, or (at your option) any later version.</p>

    <p>This library is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      Lesser General Public License for more details.</p>

    <p>You should have received a copy of the GNU Lesser General Public
      License along with this library; if not, write to the Free Software
      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
      02110-1301, USA.</p>
  </tp:license>

  <interface name="im.telepathy1.Call1.Stream.Endpoint"
    tp:causes-havoc="experimental">
    <tp:added version="0.19.0">(draft 1)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>This object represents an endpoint for a stream. In a one-to-one
        call, there will be one (bidirectional) stream per content and
        one endpoint per stream (as there is only one remote
        contact). In a multi-user call there is a stream for each remote
        contact and each stream has one endpoint as it refers to the one
        physical machine on the other end of the stream.</p>

      <p>The multiple endpoint use case appears when SIP call forking
        is used. Unlike jingle call forking (which is just making
        multiple jingle calls to different resources appear as one
        call), SIP call forking is actually done at the server so you
        have one stream to the remote contact and then and endpoint for
        each SIP client to be called.</p>
    </tp:docstring>

    <property name="RemoteCredentials"
      tp:name-for-bindings="Remote_Credentials"
      type="(ss)" tp:type="Stream_Credentials" access="read">
      <tp:docstring>
        The ICE credentials used for all candidates. If each candidate
        has different credentials, then this property SHOULD be ("",
        ""). Per-candidate credentials are set in the
        <tp:type>Candidate</tp:type>'s
        <tp:type>Candidate_Info</tp:type> a{sv}.
      </tp:docstring>
    </property>

    <signal name="RemoteCredentialsSet"
      tp:name-for-bindings="Remote_Credentials_Set">
      <arg name="Username" type="s">
        <tp:docstring>
          The username set.
        </tp:docstring>
      </arg>
      <arg name="Password" type="s">
        <tp:docstring>
          The password set.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Emitted when the remote ICE credentials for the endpoint are
        set. If each candidate has different credentials, then this
        signal will never be fired.
      </tp:docstring>
    </signal>

    <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates"
      type="a(usua{sv})" tp:type="Candidate[]" access="read">
      <tp:docstring>
        A list of candidates for this endpoint.
      </tp:docstring>
    </property>

    <signal name="RemoteCandidatesAdded"
      tp:name-for-bindings="Remote_Candidates_Added">
      <tp:docstring>
        Emitted when remote candidates are added to the
        <tp:member-ref>RemoteCandidates</tp:member-ref> property.
      </tp:docstring>
      <arg name="Candidates"
        type="a(usua{sv})" tp:type="Candidate[]">
        <tp:docstring>
          The candidates that were added.
        </tp:docstring>
      </arg>
    </signal>

    <tp:struct name="Candidate_Pair" array-name="Candidate_Pair_List">
      <tp:docstring>A Pair of candidates.</tp:docstring>
      <tp:member name="Local" type="(usua{sv})" tp:type="Candidate">
        <tp:docstring>The local candidate.</tp:docstring>
      </tp:member>
      <tp:member name="Remote" type="(usua{sv})" tp:type="Candidate">
        <tp:docstring>The remote candidate.</tp:docstring>
      </tp:member>
    </tp:struct>

    <signal name="CandidatePairSelected"
      tp:name-for-bindings="Candidate_Pair_Selected">
      <tp:docstring>
        Emitted when a candidate is selected for use in the stream by the
        controlling side of an ICE session.
        The controlled side should call
        <tp:member-ref>AcceptSelectedCandidatePair</tp:member-ref> or
        <tp:member-ref>RejectSelectedCandidatePair</tp:member-ref> when
        connectivity checks have either succeeded or failed for this candidate
        pair. See also: <tp:member-ref>SelectedCandidatePairs</tp:member-ref>.
      </tp:docstring>
      <arg name="Local_Candidate"
        type="(usua{sv})" tp:type="Candidate">
        <tp:docstring>
          The local candidate that has been selected.
        </tp:docstring>
      </arg>
      <arg name="Remote_Candidate"
        type="(usua{sv})" tp:type="Candidate">
        <tp:docstring>
          The remote candidate that has been selected.
        </tp:docstring>
      </arg>
    </signal>

    <property name="SelectedCandidatePairs"
      tp:name-for-bindings="Selected_Candidate_Pairs"
      type="a((usua{sv})(usua{sv}))" tp:type="Candidate_Pair[]"
      access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The candidates that have been selected for use to stream packets
        to the remote contact for each component of the stream.
        Change notification is given via the
        the <tp:member-ref>CandidatePairSelected</tp:member-ref> signal.</p>

        <p>Note to client implementors (from <a
        href="http://tools.ietf.org/html/rfc5245#section-9.2.2.3">RFC 5245
        section 9.2.2.3</a>):</p>

        <blockquote>
          <p>If at least one of the pairs is In-Progress, the agent SHOULD wait
          for those checks to complete, and as each completes, redo the
          processing in this section until there are no losing pairs.</p>
        </blockquote>

        <p>Also note that some or all of the local candidates in this list may
        represent a peer-reflexive candidate that do not appear in
        <tp:dbus-ref namespace="imt1.Call1.Stream.Interface.Media"
        >LocalCandidates</tp:dbus-ref>.</p>

        <p>See <a href='http://tools.ietf.org/html/rfc5245#appendix-B.6'>RFC
        5245 Appendix B.6.</a> for more details about why this is.</p>
      </tp:docstring>
    </property>

    <method name="SetSelectedCandidatePair"
      tp:name-for-bindings="Set_Selected_Candidate_Pair">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Update the entry in
        <tp:member-ref>SelectedCandidatePairs</tp:member-ref>
        for a particular component, and signal it to the remote side.</p>

        <p>This method should only be called by the controlling side of an
        ICE session. See <tp:member-ref>CandidatePairSelected</tp:member-ref>
        for details.</p>

        <tp:rationale>
          <p>In the SDP offer/answer model, this signalling will take place as
          generating an updated offer.
          Note that updates may be queued up until information about all
          components of all streams is gathered.</p>
        </tp:rationale>
      </tp:docstring>
      <arg name="Local_Candidate"
        type="(usua{sv})" tp:type="Candidate" direction="in">
        <tp:docstring>
          The local candidate that has been selected.
        </tp:docstring>
      </arg>
      <arg name="Remote_Candidate"
        type="(usua{sv})" tp:type="Candidate" direction="in">
        <tp:docstring>
          The remote candidate that has been selected.
        </tp:docstring>
      </arg>
      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.InvalidArgument"/>
      </tp:possible-errors>
    </method>

    <tp:enum name="Stream_Endpoint_State" type="u">
      <tp:docstring>
        Represents the state of ICE negotiation for a single component of a
        stream to an endpoint.
      </tp:docstring>
      <tp:enumvalue suffix="Connecting" value="0">
        <tp:docstring>
          Candidate gathering and connectivity checks are in progress.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Provisionally_Connected" value="1">
        <tp:docstring>
          The streaming implementation has found at least one working
          candidate pair. It is possible to send media at this point, but the
          controlling side has yet to negotiate the final candidates for use
          in this call.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Fully_Connected" value="2">
        <tp:docstring>
          This component of the stream is connected, and an updated offer has
          been sent and accepted (finalising the candidates to be used for the
          call). This should be set by the CM in response to
          <tp:member-ref>AcceptSelectedCandidatePair</tp:member-ref>.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Exhausted_Candidates" value="3">
        <tp:docstring>
          The streaming implementation has tried connecting to all of the
          available candidates and none of them have connected. This is
          distinct from Failed, because the CM might be able to provide more
          candidates later (more likely in XMPP than SIP).
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Failed" value="4">
        <tp:docstring>
          The CM and streaming implementation are in agreement that it is
          impossible to connect to this endpoint. This value should only be
          set by the CM.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:mapping name="Component_State_Map">
      <tp:member name="Component" type="u" tp:type="Stream_Component"/>
      <tp:member name="State" type="u" tp:type="Stream_Endpoint_State"/>
    </tp:mapping>

    <property name="EndpointState" tp:name-for-bindings="Endpoint_State"
      type="a{uu}" tp:type="Component_State_Map"
      access="read">
      <tp:docstring>
        The state of ICE negotiation with this Endpoint for each component of
        the stream.
      </tp:docstring>
    </property>

    <signal name="EndpointStateChanged"
      tp:name-for-bindings="Endpoint_State_Changed">
      <tp:docstring>
        Emitted when the <tp:member-ref>EndpointState</tp:member-ref>
        property changes.
      </tp:docstring>
      <arg name="Component" type="u" tp:type="Stream_Component">
        <tp:docstring>
          The component whose state has changed.
        </tp:docstring>
      </arg>
      <arg name="State" type="u" tp:type="Stream_Endpoint_State">
        <tp:docstring>
          The new state of this component.
        </tp:docstring>
      </arg>
    </signal>

    <method name="SetEndpointState"
      tp:name-for-bindings="Set_Endpoint_State">
      <tp:docstring>
        Change the <tp:member-ref>EndpointState</tp:member-ref> of the
        endpoint.
      </tp:docstring>
      <arg direction="in" name="Component" type="u" tp:type="Stream_Component">
        <tp:docstring>
          The component whose state needs updating.
        </tp:docstring>
      </arg>
      <arg direction="in" name="State" type="u" tp:type="Stream_Endpoint_State">
        <tp:docstring>
          The new state of this component.
        </tp:docstring>
      </arg>
      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.InvalidArgument"/>
        <tp:error name="im.telepathy1.Error.NotAvailable"/>
      </tp:possible-errors>
    </method>

    <method name="AcceptSelectedCandidatePair"
      tp:name-for-bindings="Accept_Selected_Candidate_Pair">
      <tp:docstring>
        Called in response to
        <tp:member-ref>CandidatePairSelected</tp:member-ref> if/when this
        candidate pair is known to have passed its connectivity checks.
      </tp:docstring>
      <arg name="Local_Candidate"
        type="(usua{sv})" tp:type="Candidate" direction="in">
        <tp:docstring>
          The local candidate that has been selected.
        </tp:docstring>
      </arg>
      <arg name="Remote_Candidate"
        type="(usua{sv})" tp:type="Candidate" direction="in">
        <tp:docstring>
          The remote candidate that has been selected.
        </tp:docstring>
      </arg>
      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.InvalidArgument"/>
      </tp:possible-errors>
    </method>

    <method name="RejectSelectedCandidatePair"
      tp:name-for-bindings="Reject_Selected_Candidate_Pair">
      <tp:docstring>
        Called in response to
        <tp:member-ref>CandidatePairSelected</tp:member-ref> if/when this
        candidate pair is known to have failed its connectivity checks.
      </tp:docstring>
      <arg name="Local_Candidate"
        type="(usua{sv})" tp:type="Candidate" direction="in">
        <tp:docstring>
          The local candidate that has been selected.
        </tp:docstring>
      </arg>
      <arg name="Remote_Candidate"
        type="(usua{sv})" tp:type="Candidate" direction="in">
        <tp:docstring>
          The remote candidate that has been selected.
        </tp:docstring>
      </arg>
      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.InvalidArgument"/>
      </tp:possible-errors>
    </method>

    <property name="Transport" tp:name-for-bindings="Transport"
      type="u" tp:type="Stream_Transport_Type" access="read">
      <tp:docstring>
        The transport type for the stream endpoint. This can be
        different from the transport of the Stream in the case where
        of falling back from <tp:value-ref
        type="Stream_Transport_Type">ICE</tp:value-ref> to
        <tp:value-ref
        type="Stream_Transport_Type">Raw_UDP</tp:value-ref>.
      </tp:docstring>
    </property>

    <property name="Controlling" tp:name-for-bindings="Controlling"
      type="b" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>
        The local side is taking the controlling role (as defined by ICE RFC
        5245). Change notification is given via the
        <tp:member-ref>ControllingChanged</tp:member-ref> signal.</p>

        <tp:rationale>In ICE, the Caller is normally in controlling mode (and
        the Callee in controlled-mode), except if the Caller is doing ICE-Lite,
        in which case it's reversed. The Controlling side is responsible for
        selecting nominated pairs, and generating updated offers upon
        conclusion of ICE.</tp:rationale>
      </tp:docstring>
    </property>

    <method name="SetControlling"
      tp:name-for-bindings="Set_Controlling">
      <tp:docstring>
        Set whether the local side is taking the Controlling role. Note that
        if there are multiple endpoints (e.g. SIP call forking) it may be the
        case that all endpoints need to have the same controlling/controlled
        orientation.
      </tp:docstring>
      <arg name="Controlling" type="b" direction="in">
        <tp:docstring>
          The new value of <tp:member-ref>Controlling</tp:member-ref>.
        </tp:docstring>
      </arg>
    </method>

    <signal name="ControllingChanged"
      tp:name-for-bindings="Controlling_Changed">
      <tp:docstring>
        The value of <tp:member-ref>Controlling</tp:member-ref> has changed.
      </tp:docstring>
      <arg name="Controlling" type="b">
        <tp:docstring>
          The new value of <tp:member-ref>Controlling</tp:member-ref>.
        </tp:docstring>
      </arg>
    </signal>

    <property name="IsICELite" tp:name-for-bindings="Is_ICE_Lite"
      type="b" access="read">
      <tp:docstring>
        The Remote side is an ICE Lite endpoint. (The local side is assumed to
        always be an ICE Full implementation.)
      </tp:docstring>
    </property>

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