@spec allocate_turn_channel(pid(), pid()) :: {:ok, non_neg_integer()}

Allocates the next TURN channel number unique on this Listener socket.

@spec bind_remote(pid(), pid(), {:inet.ip_address(), :inet.port_number()}) :: :ok

Maps remote {ip, port} to peer_pid for RTP/RTCP/DTLS demux.

@spec bind_turn_channel(pid(), pid(), non_neg_integer()) :: :ok

Maps TURN ChannelData channel to peer_pid.

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

Maps local ICE ufrag to peer_pid for STUN Binding demux.

@spec cert_paths(pid()) :: {String.t(), String.t()}

Returns {certfile, keyfile} paths for DTLS handshakes.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec gather_candidates(
  pid(),
  keyword()
) :: %{
  host: [XMediaLib.SDP.Candidate.t()],
  srflx: [XMediaLib.SDP.Candidate.t()],
  relay: [XMediaLib.SDP.Candidate.t()]
}

Gathers host, srflx, and relay candidates within timeout_ms.

Returns %{host: [...], srflx: [...], relay: [...]}.

@spec gather_opts(pid()) :: keyword()

Host gather options configured at listener start.

@spec gather_timeout_ms(pid()) :: non_neg_integer()

Pre-answer srflx gather timeout in milliseconds.

@spec host_candidate(pid()) :: XMediaLib.SDP.Candidate.t()

Host ICE candidate with highest priority for the listener UDP socket.

@spec host_candidate_line(pid()) :: String.t()

SDP a=candidate: attribute value (without prefix) for the highest-priority host.

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

SDP a=candidate: lines for all gathered host candidates (without prefix).

@spec host_candidates(pid()) :: [XMediaLib.SDP.Candidate.t()]

All host ICE candidates for the listener UDP socket (multi-interface).

@spec ice_tcp_enabled?(pid()) :: boolean()

Returns true when ICE-TCP passive candidates are enabled.

@spec listen_sock(pid()) :: :ssl.sslsocket()

Returns the SSL listen socket for DTLS accept (shared UDP via Transport).

@spec local_fingerprint(pid()) :: String.t()

SHA-256 fingerprint of the listener DTLS certificate (SDP format).

@spec port(pid()) :: :inet.port_number()

Bound port of the shared UDP socket.

@spec register_peer(pid(), pid()) :: :ok

Registers peer_pid for demux (monitor only until bind_* keys are set).

@spec relay_candidate_lines(
  pid(),
  keyword()
) :: [String.t()]

SDP a=candidate: lines for relay candidates gathered within the timeout.

@spec relay_only?(pid()) :: boolean()

When true, answer SDP may omit host/srflx locals (relay-only / zero-public-port).

@spec send(pid(), :inet.ip_address(), :inet.port_number(), binary()) :: :ok

Sends a UDP datagram on the listener socket (STUN replies, etc.).

@spec send_datagram(pid(), :inet.ip_address(), :inet.port_number(), binary()) ::
  :ok | {:error, term()}

Sends a UDP datagram and waits for :gen_udp.send/4 result (outbound media).

@spec send_tcp_stun(pid(), XGW.ICE.endpoint(), binary()) :: :ok | {:error, term()}

Sends a framed STUN message over an established ICE-TCP connection to peer_addr.

@spec sockname(pid()) :: {:inet.ip_address(), :inet.port_number()}

Bound socket {ip, port}.

@spec srflx_candidate_lines(
  pid(),
  keyword()
) :: [String.t()]

SDP a=candidate: lines for srflx candidates gathered within the timeout.

@spec start_link(keyword()) :: {:ok, pid()} | {:error, term()}

Starts a UDP listener on ip / port (use port: 0 for an ephemeral bind).

Optional gather opts: :advertised_ip, :advertised_ips, :include_loopback, :stun_servers, :gather_timeout_ms, :turn_servers, :relay_only, TURN credential opts, :ice_tcp_enabled, :ice_tcp_port.

@spec stun_binding(
  pid(),
  :inet.ip_address(),
  :inet.port_number(),
  non_neg_integer(),
  binary() | nil
) :: {:ok, binary()} | {:error, term()}

Sends a STUN Binding request on the listener socket and waits for a response.

Optional fifth argument is pre-encoded request wire (defaults to plain Binding).

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

Configured STUN server URIs for srflx gather.

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

SDP a=candidate: lines for passive TCP host candidates.

@spec tcp_candidates(pid()) :: [XMediaLib.SDP.Candidate.t()]

Passive ICE-TCP host candidates (empty when ICE-TCP is disabled).

@spec tcp_connect_stun(pid(), XGW.ICE.endpoint(), binary()) :: :ok | {:error, term()}

Connects to peer_addr over TCP if needed and sends a framed STUN message.

@spec tcp_port(pid()) :: :inet.port_number() | nil

Returns the bound ICE-TCP listen port when enabled, else nil.

@spec turn_credentials(pid()) :: keyword()

TURN credential options for relay gather.

@spec turn_request(
  pid(),
  :inet.ip_address(),
  :inet.port_number(),
  non_neg_integer(),
  binary()
) :: {:ok, binary()} | {:error, term()}

Sends a STUN/TURN request on the listener socket and waits for a response.

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

Configured TURN server URIs for relay gather.

@spec udp_sock(pid()) :: port()

Returns the shared UDP socket used for STUN/RTP and DTLS cb_info.

@spec unregister_peer(pid(), pid()) :: :ok

Removes peer_pid and all demux keys that pointed at it.