Interface Call1.Stream.Endpoint

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

Methods

SetSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing
SetEndpointState (u: Component, u: State) → nothing
AcceptSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing
RejectSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing
SetControlling (b: Controlling) → nothing

Signals

RemoteCredentialsSet (s: Username, s: Password)
RemoteCandidatesAdded (a(usua{sv}): Candidates)
CandidatePairSelected ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate)
EndpointStateChanged (u: Component, u: State)
ControllingChanged (b: Controlling)

Properties

RemoteCredentials (ss) (Stream_Credentials) Read only
RemoteCandidates a(usua{sv}) (Candidate_List) Read only
SelectedCandidatePairs a((usua{sv})(usua{sv})) (Candidate_Pair_List) Read only
EndpointState a{uu} (Component_State_Map) Read only
Transport u (Stream_Transport_Type) Read only
Controlling b Read only
IsICELite b Read only

Types

Stream_Endpoint_State Enum u
Component_State_Map Mapping a{uu}
Candidate_Pair Struct ((usua{sv})(usua{sv}))
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Added in 0.19.0. (draft 1)

Description

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.

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.

Methods

(Permalink)

SetSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing

Parameters

  • Local_Candidate — (usua{sv}) (Candidate)
    • The local candidate that has been selected.
  • Remote_Candidate — (usua{sv}) (Candidate)
    • The remote candidate that has been selected.

Update the entry in SelectedCandidatePairs for a particular component, and signal it to the remote side.

This method should only be called by the controlling side of an ICE session. See CandidatePairSelected for details.

Rationale:

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.

Possible Errors

(Permalink)

SetEndpointState (u: Component, u: State) → nothing

Parameters

Change the EndpointState of the endpoint.

Possible Errors

  • Invalid Argument
    • Raised when one of the provided arguments is invalid.
  • Not Available
    • Raised when the requested functionality is temporarily unavailable.
(Permalink)

AcceptSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing

Parameters

  • Local_Candidate — (usua{sv}) (Candidate)
    • The local candidate that has been selected.
  • Remote_Candidate — (usua{sv}) (Candidate)
    • The remote candidate that has been selected.
Called in response to CandidatePairSelected if/when this candidate pair is known to have passed its connectivity checks.

Possible Errors

(Permalink)

RejectSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing

Parameters

  • Local_Candidate — (usua{sv}) (Candidate)
    • The local candidate that has been selected.
  • Remote_Candidate — (usua{sv}) (Candidate)
    • The remote candidate that has been selected.
Called in response to CandidatePairSelected if/when this candidate pair is known to have failed its connectivity checks.

Possible Errors

(Permalink)

SetControlling (b: Controlling) → nothing

Parameters

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.

Signals

(Permalink)

RemoteCredentialsSet (s: Username, s: Password)

Parameters

  • Username — s
    • The username set.
  • Password — s
    • The password set.
Emitted when the remote ICE credentials for the endpoint are set. If each candidate has different credentials, then this signal will never be fired.
(Permalink)

RemoteCandidatesAdded (a(usua{sv}): Candidates)

Parameters

  • Candidates — a(usua{sv}) (Candidate_List)
    • The candidates that were added.
Emitted when remote candidates are added to the RemoteCandidates property.
(Permalink)

CandidatePairSelected ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate)

Parameters

  • Local_Candidate — (usua{sv}) (Candidate)
    • The local candidate that has been selected.
  • Remote_Candidate — (usua{sv}) (Candidate)
    • The remote candidate that has been selected.
Emitted when a candidate is selected for use in the stream by the controlling side of an ICE session. The controlled side should call AcceptSelectedCandidatePair or RejectSelectedCandidatePair when connectivity checks have either succeeded or failed for this candidate pair. See also: SelectedCandidatePairs.
(Permalink)

EndpointStateChanged (u: Component, u: State)

Parameters

Emitted when the EndpointState property changes.
(Permalink)

ControllingChanged (b: Controlling)

Parameters

The value of Controlling has changed.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

RemoteCredentials — (ss) (Stream_Credentials)

Read only
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 Candidate's Candidate_Info a{sv}.
(Permalink)

RemoteCandidates — a(usua{sv}) (Candidate_List)

Read only
A list of candidates for this endpoint.
(Permalink)

SelectedCandidatePairs — a((usua{sv})(usua{sv})) (Candidate_Pair_List)

Read only

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 CandidatePairSelected signal.

Note to client implementors (from RFC 5245 section 9.2.2.3):

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.

Also note that some or all of the local candidates in this list may represent a peer-reflexive candidate that do not appear in LocalCandidates.

See RFC 5245 Appendix B.6. for more details about why this is.

(Permalink)

EndpointState — a{uu} (Component_State_Map)

Read only
The state of ICE negotiation with this Endpoint for each component of the stream.
(Permalink)

Transport — u (Stream_Transport_Type)

Read only
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 ICE to Raw_UDP.
(Permalink)

Controlling — b

Read only

The local side is taking the controlling role (as defined by ICE RFC 5245). Change notification is given via the ControllingChanged signal.

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.
(Permalink)

IsICELite — b

Read only
The Remote side is an ICE Lite endpoint. (The local side is assumed to always be an ICE Full implementation.)

Types

Enum (Permalink)

Stream_Endpoint_State — u

Represents the state of ICE negotiation for a single component of a stream to an endpoint.
  • Connecting (0)
    • Candidate gathering and connectivity checks are in progress.
  • Provisionally_Connected (1)
    • 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.
  • Fully_Connected (2)
    • 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 AcceptSelectedCandidatePair.
  • Exhausted_Candidates (3)
    • 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).
  • Failed (4)
    • 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.
Mapping (Permalink)

Component_State_Map — a{uu}

Struct (Permalink)

Candidate_Pair — ((usua{sv})(usua{sv}))

A Pair of candidates.
  • Local — (usua{sv}) (Candidate)
    • The local candidate.
  • Remote — (usua{sv}) (Candidate)
    • The remote candidate.