View Source ExICE.ICEAgent (ex_ice v0.8.3)

ICE Agent.

Not to be confused with Elixir Agent.

Summary

Types

connection_state_change()

Emitted when connection state has changed.

gathering_state_change()

Emitted when gathering process state has changed.

ip_filter()

Filter applied when gathering host candidates.

opts()

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.

role()

ICE agent role.

signal()

Messages sent by the ExICE.

Functions

add_remote_candidate(ice_agent, candidate)

Adds a remote candidate.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

end_of_candidates(ice_agent)

Informs ICE agent that a remote side finished its gathering process.

gather_candidates(ice_agent)

Starts ICE gathering process.

get_local_candidates(ice_agent)

Gets all local candidates that have already been gathered.

get_local_credentials(ice_agent)

Gets local credentials.

get_remote_candidates(ice_agent)

Gets all remote candidates.

get_stats(ice_agent)

Gathers ICE agent statistics.

on_connection_state_change(ice_agent, send_to)

Configures where to send connection state change notifications.

on_data(ice_agent, send_to)

Configures where to send data.

on_gathering_state_change(ice_agent, send_to)

Configures where to send gathering state change notifications.

on_new_candidate(ice_agent, send_to)

Configures where to send new candidates.

restart(ice_agent)

Restarts ICE.

send_data(ice_agent, data)

Sends data.

set_remote_credentials(ice_agent, ufrag, passwd)

Sets remote credentials.

start_link(role, opts \\ [])

Starts and links a new ICE agent.

stop(ice_agent)

Stops ICE agent and all of its sockets.

Types

connection_state_change()

@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.

gathering_state_change()

@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.

ip_filter()

@type ip_filter() :: (:inet.ip_address() -> boolean())

Filter applied when gathering host candidates.

opts()

@type opts() :: [
  ip_filter: ip_filter(),
  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 host candidates
ports - ports that will be used when gathering host candidates, otherwise the ports are chosen by the OS
ice_servers - list of STUN/TURN servers
ice_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 spawns ExICE.
on_connection_state_change - where to send connection state change notifications. Defaults to a process that spawns ExICE.
on_data - where to send data. Defaults to a process that spawns ExICE.
on_new_candidate - where to send new candidates. Defaults to a process that spawns ExICE.

Currently, there is no support for local relay (TURN) candidates however, remote relay candidates work correctly.

role()

@type role() :: :controlling | :controlled

ICE agent role.

:controlling agent is responsible for nominating a pair.

signal()

@type signal() ::
  {:ex_ice, pid(),
   gathering_state_change()
   | connection_state_change()
   | {:data, binary()}
   | {:new_candidate, String.t()}}

Messages sent by the ExICE.

Functions

add_remote_candidate(ice_agent, candidate)

@spec add_remote_candidate(pid(), String.t()) :: :ok

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.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

end_of_candidates(ice_agent)

@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.

gather_candidates(ice_agent)

@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.

get_local_candidates(ice_agent)

@spec get_local_candidates(pid()) :: [String.t()]

Gets all local candidates that have already been gathered.

get_local_credentials(ice_agent)

@spec get_local_credentials(pid()) :: {:ok, ufrag :: binary(), pwd :: binary()}

Gets local credentials.

They remain unchanged until ICE restart.

get_remote_candidates(ice_agent)

@spec get_remote_candidates(pid()) :: [String.t()]

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

get_stats(ice_agent)

@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.

on_connection_state_change(ice_agent, send_to)

@spec on_connection_state_change(pid(), pid() | nil) :: :ok

Configures where to send connection state change notifications.

on_data(ice_agent, send_to)

@spec on_data(pid(), pid() | nil) :: :ok

Configures where to send data.

on_gathering_state_change(ice_agent, send_to)

@spec on_gathering_state_change(pid(), pid() | nil) :: :ok

Configures where to send gathering state change notifications.

on_new_candidate(ice_agent, send_to)

@spec on_new_candidate(pid(), pid() | nil) :: :ok

Configures where to send new candidates.

restart(ice_agent)

@spec restart(pid()) :: :ok

Restarts ICE.

If there were any valid pairs in the previous ICE session, data can still be sent.

send_data(ice_agent, data)

@spec send_data(pid(), binary()) :: :ok

Sends data.

Can only be called after moving to the connected state.

set_remote_credentials(ice_agent, ufrag, passwd)

@spec set_remote_credentials(pid(), binary(), binary()) :: :ok

Sets remote credentials.

Call to this function is mandatory to start connectivity checks.

start_link(role, opts \\ [])

@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.

stop(ice_agent)

@spec stop(pid()) :: :ok

Stops ICE agent and all of its sockets.