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
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
- Invalid Argument
Raised when one of the provided arguments is invalid.
(Permalink)
SetEndpointState (u: Component, u: State) → nothing
Parameters
- Component — u (Stream_Component)
- State — u (Stream_Endpoint_State)
The component whose state needs updating.
The new state of this component.
Change the EndpointState of the
endpoint.
Possible Errors
- Invalid Argument
- Not Available
Raised when one of the provided arguments is invalid.
Raised when the requested functionality is temporarily unavailable.
(Permalink)
AcceptSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing
Parameters
Called in response to
CandidatePairSelected if/when this
candidate pair is known to have passed its connectivity checks.
Possible Errors
- Invalid Argument
Raised when one of the provided arguments is invalid.
(Permalink)
RejectSelectedCandidatePair ((usua{sv}): Local_Candidate, (usua{sv}): Remote_Candidate) → nothing
Parameters
Called in response to
CandidatePairSelected if/when this
candidate pair is known to have failed its connectivity checks.
Possible Errors
- Invalid Argument
Raised when one of the provided arguments is invalid.
(Permalink)
SetControlling (b: Controlling) → nothing
Parameters
- Controlling — b
The new value of Controlling.
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
- Password — s
The username set.
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
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
- Component — u (Stream_Component)
- State — u (Stream_Endpoint_State)
The component whose state has changed.
The new state of this component.
Emitted when the EndpointState
property changes.
(Permalink)
ControllingChanged (b: Controlling)
Parameters
- Controlling — b
The new value of Controlling.
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.
(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)
- Provisionally_Connected (1)
- Fully_Connected (2)
- Exhausted_Candidates (3)
- Failed (4)
Candidate gathering and connectivity checks are in progress.
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.
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.
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).
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}
- Component — u (Stream_Component)
- State — u (Stream_Endpoint_State)