diff options
Diffstat (limited to 'spec/Call_Stream_Endpoint.xml')
| -rw-r--r-- | spec/Call_Stream_Endpoint.xml | 284 |
1 files changed, 251 insertions, 33 deletions
diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml index cf1783d1e..2aa7e52f3 100644 --- a/spec/Call_Stream_Endpoint.xml +++ b/spec/Call_Stream_Endpoint.xml @@ -20,7 +20,7 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT" + <interface name="org.freedesktop.Telepathy.Call1.Stream.Endpoint" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> @@ -92,39 +92,99 @@ </arg> </signal> - <signal name="CandidateSelected" - tp:name-for-bindings="Candidate_Selected"> + <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. + 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="Candidate" + <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 candidate that has been selected. + The remote candidate that has been selected. </tp:docstring> </arg> </signal> - <property name="SelectedCandidate" - tp:name-for-bindings="Selected_Candidate" - type="(usua{sv})" tp:type="Candidate" access="read"> - <tp:docstring> - The candidate that has been selected for use to stream packets - to the remote contact. Change notification is given via the - the <tp:member-ref>CandidateSelected</tp:member-ref> 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="ofdT.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="SetSelectedCandidate" - tp:name-for-bindings="Set_Selected_Candidate"> - <tp:docstring> - Set the value of - <tp:member-ref>CandidateSelected</tp:member-ref>. + <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="Candidate" + <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 candidate that has been selected. + The remote candidate that has been selected. </tp:docstring> </arg> <tp:possible-errors> @@ -132,36 +192,95 @@ </tp:possible-errors> </method> - <property name="StreamState" tp:name-for-bindings="Stream_State" - type="u" tp:type="Media_Stream_State" + <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 stream state of the endpoint. + The state of ICE negotiation with this Endpoint for each component of + the stream. </tp:docstring> </property> - <signal name="StreamStateChanged" - tp:name-for-bindings="Stream_State_Changed"> + <signal name="EndpointStateChanged" + tp:name-for-bindings="Endpoint_State_Changed"> <tp:docstring> - Emitted when the <tp:member-ref>StreamState</tp:member-ref> + Emitted when the <tp:member-ref>EndpointState</tp:member-ref> property changes. </tp:docstring> - <arg name="state" type="u" tp:type="Media_Stream_State"> + <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 <tp:member-ref>StreamState</tp:member-ref> value. + The new state of this component. </tp:docstring> </arg> </signal> - <method name="SetStreamState" - tp:name-for-bindings="Set_Stream_State"> + <method name="SetEndpointState" + tp:name-for-bindings="Set_Endpoint_State"> <tp:docstring> - Change the <tp:member-ref>StreamState</tp:member-ref> of the + Change the <tp:member-ref>EndpointState</tp:member-ref> of the endpoint. </tp:docstring> - <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"> + <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 requested stream state. + The new state of this component. </tp:docstring> </arg> <tp:possible-errors> @@ -170,6 +289,54 @@ </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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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> @@ -177,6 +344,57 @@ </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: --> |