View Source ExICE.ICEAgent (ex_ice v0.8.1)
ICE Agent.
Not to be confused with Elixir Agent.
Summary
Types
Emitted when connection state has changed.
Emitted when gathering process state has changed.
ICE Agent configuration options.
All notifications are by default sent to a process that spawns ExICE
.
This behavior can be overwritten using the following options.
ICE agent role.
Messages sent by the ExICE.
Functions
Adds a remote candidate.
Returns a specification to start this module under a supervisor.
Informs ICE agent that a remote side finished its gathering process.
Starts ICE gathering process.
Gets all local candidates that have already been gathered.
Gets local credentials.
Gets all remote candidates.
Gathers ICE agent statistics.
Configures where to send connection state change notifications.
Configures where to send data.
Configures where to send gathering state change notifications.
Configures where to send new candidates.
Restarts ICE.
Sends data.
Sets remote credentials.
Starts and links a new ICE agent.
Stops ICE agent and all of its sockets.
Types
@type connection_state_change() ::
{:connection_state_change, :checking | :connected | :completed | :failed}
Emitted when connection state has changed.
For exact meaning refer to the W3C WebRTC standard, sec. 5.6.4.
@type gathering_state_change() ::
{:gathering_state_change, :new | :gathering | :complete}
Emitted when gathering process state has changed.
For exact meaning refer to the W3C WebRTC standard, sec 5.6.3.
@type opts() :: [ ip_filter: (:inet.ip_address() -> boolean()), ports: Enumerable.t(non_neg_integer()), ice_servers: [ %{ :urls => [String.t()] | String.t(), optional(:username) => String.t(), optional(:credential) => String.t() } ], ice_transport_policy: :all | :relay, on_gathering_state_change: pid() | nil, on_connection_state_change: pid() | nil, on_data: pid() | nil, on_new_candidate: pid() | nil ]
ICE Agent configuration options.
All notifications are by default sent to a process that spawns ExICE
.
This behavior can be overwritten using the following options.
ip_filter
- filter applied when gathering local candidatesports
- ports that will be used when gathering local candidates, otherwise the ports are chosen by the OSice_servers
- list of STUN/TURN serversice_transport_policy
- candidate types to be used.all
- all ICE candidates will be considered (default).relay
- only relay candidates will be considered.
on_gathering_state_change
- where to send gathering state change notifications. Defaults to a process that spawnsExICE
.on_connection_state_change
- where to send connection state change notifications. Defaults to a process that spawnsExICE
.on_data
- where to send data. Defaults to a process that spawnsExICE
.on_new_candidate
- where to send new candidates. Defaults to a process that spawnsExICE
.
Currently, there is no support for local relay (TURN) candidates however, remote relay candidates work correctly.
@type role() :: :controlling | :controlled
ICE agent role.
:controlling
agent is responsible for nominating a pair.
@type signal() :: {:ex_ice, pid(), gathering_state_change() | connection_state_change() | {:data, binary()} | {:new_candidate, String.t()}}
Messages sent by the ExICE.
Functions
Adds a remote candidate.
If an ICE agent has already gathered any local candidates and have remote credentials set, adding a remote candidate will start connectivity checks.
Returns a specification to start this module under a supervisor.
See Supervisor
.
@spec end_of_candidates(pid()) :: :ok
Informs ICE agent that a remote side finished its gathering process.
Call to this function is mandatory to nominate a pair (when an agent is the controlling
one)
and in turn move to the completed
state.
@spec gather_candidates(pid()) :: :ok
Starts ICE gathering process.
Once a new candidate is discovered, it is sent as a message to the controlling process.
See signal/0
for a message structure.
Gets all local candidates that have already been gathered.
Gets local credentials.
They remain unchanged until ICE restart.
Gets all remote candidates.
This includes candidates supplied by add_remote_candidate/2
and candidates
discovered during ICE connection establishment process (so called prflx
candidates).
@spec get_stats(pid()) :: %{ bytes_sent: non_neg_integer(), bytes_received: non_neg_integer(), packets_sent: non_neg_integer(), packets_received: non_neg_integer(), state: atom(), role: atom(), local_ufrag: binary(), local_candidates: [ExICE.Candidate.t()], remote_candidates: [ExICE.Candidate.t()], candidate_pairs: [ExICE.CandidatePair.t()] }
Gathers ICE agent statistics.
bytes_sent
- data bytes sent. This does not include connectivity checks and UDP/IP header sizes.bytes_received
- data bytes received. This does not include connectivity checks and UDP/IP header sizes.packets_sent
- data packets sent. This does not include connectivity checks.packets_received
- data packets received. This does not include connectivity checks.candidate_pairs
- list of current candidate pairs. Changes after doing an ICE restart.
Configures where to send connection state change notifications.
Configures where to send data.
Configures where to send gathering state change notifications.
Configures where to send new candidates.
@spec restart(pid()) :: :ok
Restarts ICE.
If there were any valid pairs in the previous ICE session, data can still be sent.
Sends data.
Can only be called after moving to the connected
state.
Sets remote credentials.
Call to this function is mandatory to start connectivity checks.
@spec start_link(role(), opts()) :: GenServer.on_start()
Starts and links a new ICE agent.
Process calling this function is called a controlling process
and
has to be prepared for receiving ExICE messages described by signal/0
.
@spec stop(pid()) :: :ok
Stops ICE agent and all of its sockets.