View Source ExICE.ICEAgent (ex_ice v0.2.0)

ICE Agent.

Not to be confused with Elixir Agent.

Link to this section Summary

Types

Emitted when connection state has changed.

Emitted when gathering process state has changed.

ICE Agent configuration 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.

Restarts ICE.

Starts and links a new ICE agent.

Link to this section 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()]
]

ICE Agent configuration options.

  • ip_filter - filter applied when gathering local candidates
  • stun_servers - list of STUN servers

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.

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