View Source ExICE.ICEAgent (ex_ice v0.6.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

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 local credentials.

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.

Starts and links a new ICE agent.

Stops ICE agent and all of its sockets.

Types

Link to this type

connection_state_change()

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

Link to this type

gathering_state_change()

View Source
@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()),
  stun_servers: [String.t()],
  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 candidates
  • stun_servers - list of STUN servers
  • 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.

@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, binary()}}

Messages sent by the ExICE.

Functions

Link to this function

add_remote_candidate(ice_agent, candidate)

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

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

end_of_candidates(ice_agent)

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

Link to this function

gather_candidates(ice_agent)

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

Link to this function

get_local_credentials(ice_agent)

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

Gets local credentials.

They remain unchanged until ICE restart.

@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.
Link to this function

on_connection_state_change(ice_agent, send_to)

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

Configures where to send connection state change notifications.

Link to this function

on_data(ice_agent, send_to)

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

Configures where to send data.

Link to this function

on_gathering_state_change(ice_agent, send_to)

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

Configures where to send gathering state change notifications.

Link to this function

on_new_candidate(ice_agent, send_to)

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

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.

Link to this function

send_data(ice_agent, data)

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

Sends data.

Can only be called after moving to the connected state.

Link to this function

set_remote_credentials(ice_agent, ufrag, passwd)

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

Sets remote credentials.

Call to this function is mandatory to start connectivity checks.

Link to this function

start_link(role, opts \\ [])

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