ExLibnice (ExLibnice v0.6.0) View Source

Module that wraps functions from libnice.

For more information about each function please refer to [libnice] documentation.

Link to this section Summary

Types

Fully qualified domain name e.g. "my.domain.com".

Type describing ExLibnice configuration.

Type describing TURN server configuration

Functions

Adds a new stream with n_components components. name is optional but not passing it will influence on SDP string format, see generate_local_sdp/1.

Returns a specification to start this module under a supervisor.

Forget all TURN servers for given component.

Starts gathering candidates process for stream with id stream_id.

Generates a SDP string containing the local candidates and credentials for all streams and components.

Returns local credentials for stream with id stream_id.

Parses a remote SDP string setting credentials and remote candidates for proper streams and components.

Indicates that all remote candidates for stream with id stream_id have been passed.

Removes stream with id stream_id.

Restarts all streams.

Restarts stream with id stream_id.

Sends payload on component with id component_id in stream with id stream_id. Payload has to be in a binary format.

Sets TURN server. Can be called multiple times for the same component to add many TURN servers.

Sets remote candidate for component with id component_id in stream with id stream_id.

Sets remote credentials for stream with stream_id.

Spawns new process responsible for interacting with libnice.

Link to this section Types

Specs

fqdn() :: String.t()

Fully qualified domain name e.g. "my.domain.com".

Specs

opts_t() :: [
  impl: NIF | CNode,
  parent: pid(),
  stun_servers: [stun_server()],
  controlling_mode: boolean(),
  port_range: 0..65535
]

Type describing ExLibnice configuration.

It's a keyword list containing the following keys:

  • impl - implementation to use. Possible values are NIF and CNode. You can also choose impl via config.exs by
    config :ex_libnice, impl: :NIF
  • parent - pid of calling process
  • stun_servers - list of stun servers in form of ip:port
  • controlling_mode - refer to RFC 8445 section 4 - Controlling and Controlled Agent
  • min_port..max_port - the port range to use. Pass 0..0 if you not willing to set it. Passed port range will be set for each newly added stream. At this moment it is not possible to set port range per stream.

Specs

relay_info() :: %{
  server_addr: :inet.ip_address() | fqdn(),
  server_port: 0..65535,
  username: String.t(),
  password: String.t(),
  relay_type: :udp | :tcp | :tls
}

Type describing TURN server configuration

Specs

stun_server() :: %{
  server_addr: :inet.ip_address() | fqdn(),
  server_port: 0..65535
}

Link to this section Functions

Link to this function

add_stream(pid, n_components, name \\ "")

View Source

Specs

add_stream(pid :: pid(), n_components :: integer(), name :: String.t()) ::
  {:ok, integer()}
  | {:error,
     :failed_to_add_stream
     | :invalid_stream_or_duplicate_name
     | :failed_to_attach_recv}

Adds a new stream with n_components components. name is optional but not passing it will influence on SDP string format, see generate_local_sdp/1.

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

forget_relays(pid, stream_id, component_id)

View Source

Specs

forget_relays(pid :: pid(), stream_id :: integer(), component_id :: integer()) ::
  :ok | {:error, :component_not_found}

Forget all TURN servers for given component.

Link to this function

gather_candidates(pid, stream_id)

View Source

Specs

gather_candidates(pid :: pid(), stream_id :: integer()) ::
  :ok | {:error, :invalid_stream_or_allocation}

Starts gathering candidates process for stream with id stream_id.

May cause the parent process receive following messages:

  • {:new_candidate_full, candidate} - new local candidate
  • {:candidate_gathering_done, stream_id} - gathering candidates for stream with stream_id has been done

Specs

generate_local_sdp(pid :: pid()) :: {:ok, sdp :: String.t()}

Generates a SDP string containing the local candidates and credentials for all streams and components.

Notice that:

  • local candidates will be present in the result SDP only if gather_candidates/1 has been invoked previously
  • if a stream is created without a name the 'm' line will contain '-' mark but SDP in this form will not be parsable by parse_remote_sdp/2
Link to this function

get_local_credentials(pid, stream_id)

View Source

Specs

get_local_credentials(pid :: pid(), stream_id :: integer()) ::
  {:ok, credentials :: String.t()} | {:error, :failed_to_get_credentials}

Returns local credentials for stream with id stream_id.

Link to this function

parse_remote_sdp(pid, sdp)

View Source

Specs

parse_remote_sdp(pid :: pid(), sdp :: String.t()) ::
  {:ok, added_cand_num :: integer()} | {:error, :failed_to_parse_sdp}

Parses a remote SDP string setting credentials and remote candidates for proper streams and components.

It is important that m line does not contain - mark but the name of the stream.

Link to this function

peer_candidate_gathering_done(pid, stream_id)

View Source

Specs

peer_candidate_gathering_done(pid :: pid(), stream_id :: integer()) ::
  :ok | {:error, :stream_not_found}

Indicates that all remote candidates for stream with id stream_id have been passed.

After receiving this message components can change their state to FAILED if all their connectivity checks have failed. Not sending this message will cause components stay in CONNECTING state. (In fact there is a bug and components can change their state to FAILED even without sending this message. Please refer to #120

Link to this function

remove_stream(pid, stream_id)

View Source

Specs

remove_stream(pid :: pid(), stream_id :: integer()) :: :ok

Removes stream with id stream_id.

Specs

restart(pid :: pid()) :: :ok | {:error, :failed_to_restart}

Restarts all streams.

Link to this function

restart_stream(pid, stream_id)

View Source

Specs

restart_stream(pid :: pid(), stream_id :: integer()) ::
  :ok | {:error, :failed_to_restart}

Restarts stream with id stream_id.

Link to this function

send_payload(pid, stream_id, component_id, payload)

View Source

Specs

send_payload(
  pid :: pid(),
  stream_id :: integer(),
  component_id :: integer(),
  payload :: binary()
) :: :ok | {:error, :failed_to_send}

Sends payload on component with id component_id in stream with id stream_id. Payload has to be in a binary format.

Link to this function

set_relay_info(pid, stream_id, component_id, relay_info)

View Source

Specs

set_relay_info(
  pid :: pid(),
  stream_id :: integer(),
  component_id :: integer() | [integer()] | :all,
  relay_info :: relay_info() | [relay_info()]
) ::
  :ok
  | {:error,
     :bad_stream_id
     | :bad_relay_type
     | :failed_to_resolve_addr
     | :failed_to_set_turn}

Sets TURN server. Can be called multiple times for the same component to add many TURN servers.

Link to this function

set_remote_candidate(pid, candidate, stream_id, component_id)

View Source

Specs

set_remote_candidate(
  pid :: pid(),
  candidate :: String.t(),
  stream_id :: integer(),
  component_id :: integer()
) :: :ok | {:error, :failed_to_parse_sdp_string | :failed_to_set}

Sets remote candidate for component with id component_id in stream with id stream_id.

Candidate has to be passed as SDP string. May cause the parent process receive following messages:

  • {:new_remote_candidate_full, candidate} - new remote (prflx) candidate
  • {:new_selected_pair, stream_id, component_id, lfoundation, rfoundation} - new selected pair
  • {:component_state_failed, stream_id, component_id} - component with id component_id in stream with id stream_id has changed state to FAILED
  • {:component_state_ready, stream_id, component_id} - component with id component_id in stream with id stream_id has changed state to READY i.e. it is ready to receive and send data
Link to this function

set_remote_credentials(pid, credentials, stream_id)

View Source

Specs

set_remote_credentials(
  pid :: pid(),
  credentials :: String.t(),
  stream_id :: integer()
) :: :ok | {:error, :failed_to_set_credentials}

Sets remote credentials for stream with stream_id.

Credentials have to be passed in form of ufrag pwd.

Specs

start_link(opts :: opts_t()) :: {:ok, pid()}

Spawns new process responsible for interacting with libnice.

Link to this function

stop(pid, reason \\ :normal, timeout \\ :infinity)

View Source

Specs

stop(pid :: pid(), reason :: term(), timeout :: timeout()) :: :ok

Stops and cleans up ExLibnice instance.