@spec candidate_line(XMediaLib.SDP.Candidate.t()) :: String.t()

SDP a=candidate: attribute value (without the a= prefix).

Examples

iex> c = %XMediaLib.SDP.Candidate{
...>   foundation: "1",
...>   component_id: 1,
...>   transport: "udp",
...>   priority: 100,
...>   ip: "192.0.2.1",
...>   port: 5000,
...>   type: "host"
...> }
iex> XGW.ICE.candidate_line(c)
"candidate:1 1 UDP 100 192.0.2.1 5000 typ host"

@spec candidate_priority(candidate_type(), non_neg_integer(), non_neg_integer()) ::
  non_neg_integer()

RFC 8445 section 5.1.2 candidate priority from type, component, local preference.

Examples

iex> XGW.ICE.candidate_priority(:host, 1, 65_535) == XGW.ICE.host_priority(1)
true

@spec coerce_candidate(XMediaLib.SDP.Candidate.t() | String.t()) ::
  {:ok, XMediaLib.SDP.Candidate.t()} | {:error, term()}

Coerces trickle input to %Candidate{}.

@spec endpoint(XMediaLib.SDP.Candidate.t()) :: endpoint()

Returns {ip, port} for a parsed candidate.

Examples

iex> XGW.ICE.endpoint(%XMediaLib.SDP.Candidate{ip: "192.0.2.1", port: 5000})
{{192, 0, 2, 1}, 5000}

@spec format_ip(:inet.ip_address()) :: String.t()

Formats an IPv4/IPv6 tuple as a dotted/colon string for SDP.

Examples

iex> XGW.ICE.format_ip({192, 0, 2, 1})
"192.0.2.1"

@spec foundation(String.t(), :inet.ip_address() | String.t(), String.t()) ::
  String.t()

RFC 8445 section 5.1.1 candidate foundation (stable for agent lifetime).

Hash of (type, base_ip, transport) masked to 32 bits.

Examples

iex> XGW.ICE.foundation("host", {192, 0, 2, 1}, "udp") ==
...>   XGW.ICE.foundation("host", "192.0.2.1", "UDP")
true

@spec host_priority(non_neg_integer(), non_neg_integer()) :: non_neg_integer()

RFC 8445 section 5.1.2 host candidate priority.

local_preference defaults to 65535 (single interface).

Examples

iex> XGW.ICE.host_priority(1, 65_535) == XGW.ICE.candidate_priority(:host, 1, 65_535)
true

@spec local_preference_from_priority(XMediaLib.SDP.Candidate.t()) :: non_neg_integer()

Local preference encoded in a host candidate priority.

@spec merge_remote([XMediaLib.SDP.Candidate.t()], [XMediaLib.SDP.Candidate.t()]) :: [
  XMediaLib.SDP.Candidate.t()
]

Merges remote candidates: dedup by {foundation, component_id, ip, port}, sort descending by priority (RFC 8445).

Examples

iex> low = %XMediaLib.SDP.Candidate{
...>   foundation: "1", component_id: 1, transport: "udp",
...>   priority: 100, ip: "192.0.2.1", port: 5000, type: "host"
...> }
iex> high = %{low | foundation: "2", priority: 200, ip: "192.0.2.2", port: 5001}
iex> Enum.map(XGW.ICE.merge_remote([low], [high, high]), & &1.priority)
[200, 100]

@spec pair_priority(role(), non_neg_integer(), non_neg_integer()) :: non_neg_integer()

RFC 8445 section 6.1.2.1 pair priority from controlling/controlled priorities.

Examples

iex> XGW.ICE.pair_priority(:controlling, 100, 50)
Bitwise.bsl(50, 32) + 2 * 100 + 1

iex> XGW.ICE.pair_priority(:controlled, 100, 50)
Bitwise.bsl(50, 32) + 2 * 100 + 0

@spec prflx_candidate(endpoint(), non_neg_integer(), String.t()) ::
  XMediaLib.SDP.Candidate.t()

Builds a peer-reflexive remote candidate from an inbound check source address.

@spec role(XMediaLib.SDP.Media.setup(), XMediaLib.SDP.Media.setup()) ::
  {:ok, role()} | {:error, :unsupported_setup}

Maps answerer DTLS setup to ICE role for full-ICE answers.

XGW convention (not RFC 8445 pt.5.1.1): offer actpass + answer passive (DTLS server) -> ICE :controlled; offer actpass + answer active -> :controlling. ICE-lite agents are always controlled per RFC 8445 pt.6.1.1 regardless of this helper.

Examples

iex> XGW.ICE.role(:actpass, :passive)
{:ok, :controlled}

iex> XGW.ICE.role(:actpass, :active)
{:ok, :controlling}

iex> XGW.ICE.role(:active, :passive)
{:error, :unsupported_setup}

@spec same_address_family?(XMediaLib.SDP.Candidate.t(), XMediaLib.SDP.Candidate.t()) ::
  boolean()

True when both candidates resolve to the same IP version (IPv4 or IPv6).

Examples

iex> a = %XMediaLib.SDP.Candidate{ip: "192.0.2.1", port: 1}
iex> b = %XMediaLib.SDP.Candidate{ip: "198.51.100.1", port: 2}
iex> XGW.ICE.same_address_family?(a, b)
true

@spec transport_atom(String.t()) :: transport() | nil

Maps SDP transport string to an atom.

Examples

iex> XGW.ICE.transport_atom("UDP")
:udp

@spec type_atom(String.t()) :: candidate_type() | nil

Maps SDP candidate type string to an atom.

Examples

iex> XGW.ICE.type_atom("host")
:host

iex> XGW.ICE.type_atom("nope")
nil

@spec type_preference(candidate_type()) :: non_neg_integer()

RFC 8445 section 5.1.2 type preference for a candidate type.

Examples

iex> XGW.ICE.type_preference(:host)
126

iex> XGW.ICE.type_preference(:relay)
0

@spec usable_endpoint?(XMediaLib.SDP.Candidate.t()) :: boolean()

True when candidate has a parseable, non-unspecified IP (not mDNS / 0.0.0.0).

Examples

iex> XGW.ICE.usable_endpoint?(%XMediaLib.SDP.Candidate{ip: "192.0.2.1", port: 1})
true

iex> XGW.ICE.usable_endpoint?(%XMediaLib.SDP.Candidate{ip: "0.0.0.0", port: 1})
false

@spec valid?(XMediaLib.SDP.Candidate.t()) :: boolean()

Returns true when the candidate has a foundation and allowed type.

Examples

iex> XGW.ICE.valid?(%XMediaLib.SDP.Candidate{
...>   foundation: "1", type: "host", ip: "192.0.2.1", port: 1
...> })
true

iex> XGW.ICE.valid?(%XMediaLib.SDP.Candidate{foundation: nil, type: "host"})
false

@spec validate_mid(map(), [String.t()]) :: :ok | {:error, :media_not_found}

Validates trickle :mid / :mline_index against bundled mids when present.