ice.h File Reference

ICE (Interactive Connectivity Establishment) for WebRTC. More...

Go to the source code of this file.

Data Structures
struct	ice_candidate_t
	Single ICE candidate for connectivity. More...
struct	ice_config_t
	Credentials and callback used while gathering ICE candidates. More...

Macros
#define	NETWORK_WEBRTC_ICE_FOUNDATION_BUFFER_SIZE   32
#define	NETWORK_WEBRTC_ICE_RADDR_BUFFER_SIZE   64
#define	NETWORK_WEBRTC_ICE_EXTENSIONS_BUFFER_SIZE   256

Typedefs
typedef asciichat_error_t(*	ice_send_candidate_callback_t) (const ice_candidate_t *candidate, const char *mid, void *user_data)
	Single ICE candidate for connectivity.

Enumerations
enum	ice_candidate_type_t { ICE_CANDIDATE_HOST = 0 , ICE_CANDIDATE_SRFLX = 1 , ICE_CANDIDATE_PRFLX = 2 , ICE_CANDIDATE_RELAY = 3 }
	Credentials and callback used while gathering ICE candidates. More...
enum	ice_protocol_t { ICE_PROTOCOL_UDP = 0 , ICE_PROTOCOL_TCP = 1 }
	ICE candidate transport protocol. More...
enum	ice_tcp_type_t { ICE_TCP_TYPE_ACTIVE = 0 , ICE_TCP_TYPE_PASSIVE = 1 , ICE_TCP_TYPE_SO = 2 }
	ICE candidate TCP type (if applicable). More...

Functions
asciichat_error_t	ice_gather_candidates (const ice_config_t *config)
	Start ICE candidate gathering.
asciichat_error_t	ice_parse_candidate (const char *line, ice_candidate_t *candidate)
	Parse ICE candidate from attribute string.
asciichat_error_t	ice_format_candidate (const ice_candidate_t *candidate, char *line, size_t line_size)
	Format ICE candidate to attribute string.
uint32_t	ice_calculate_priority (ice_candidate_type_t type, uint16_t local_preference, uint8_t component_id)
	Calculate candidate priority.
uint32_t	ice_calculate_priority_for_candidate (const ice_candidate_t *candidate)
	Calculate candidate priority with IP-aware local preference.
asciichat_error_t	ice_add_remote_candidate (struct webrtc_peer_connection *pc, const ice_candidate_t *candidate, const char *mid)
	Add remote candidate to peer connection.
bool	ice_is_connected (struct webrtc_peer_connection *pc)
	Check ICE connection state.
int	webrtc_get_rtc_id (struct webrtc_peer_connection *pc)
	Get the internal libdatachannel peer connection ID.
asciichat_error_t	ice_get_selected_pair (struct webrtc_peer_connection *pc, ice_candidate_t *local_candidate, ice_candidate_t *remote_candidate)
	Get selected candidate pair.
const char *	ice_candidate_type_name (ice_candidate_type_t type)
	Get human-readable candidate type name.
const char *	ice_protocol_name (ice_protocol_t protocol)
	Get human-readable protocol name.

Detailed Description

ICE (Interactive Connectivity Establishment) for WebRTC.

Handles ICE candidate gathering, exchange, and connectivity checking. ICE is the mechanism that allows WebRTC peers to discover and connect across NATs and firewalls using STUN and TURN servers.

ICE Candidate Types

Host candidates: Local IP addresses

• Direct connection if both peers on same network

Server-reflexive (srflx) candidates: NAT-discovered addresses

• Obtained from STUN server
• Allows hole punching across NATs

Peer-reflexive (prflx) candidates: Discovered during connectivity checks

• May emerge when direct STUN-based connection works

Relay candidates: TURN relay server addresses

• Guaranteed to work through any firewall
• Last resort for restrictive networks

ICE Candidate Exchange

1. Gathering phase: Collect candidates from all sources
   • Host candidates (network interfaces)
   • STUN server response
   • TURN relay addresses
2. Signaling phase: Send candidates to peer via ACDS relay
   • Each candidate sent as ACIP_WEBRTC_ICE packet
   • Order: host first, then srflx, then relay
3. Connectivity checking: Verify which candidates work
   • WebRTC agent tests each candidate pair
   • Selects best pair (lowest latency, highest bandwidth)
4. Connection: Data flows through selected candidate pair
   • May change during session (ICE restart)

Integration with ACDS

ICE candidates are sent via ACDS signaling relay:

• PACKET_TYPE_ACIP_WEBRTC_ICE for each candidate
• Peer decodes and adds to peer connection
• Peer agent tests connectivity with received candidates

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Definition in file ice.h.

Macro Definition Documentation

NETWORK_WEBRTC_ICE_EXTENSIONS_BUFFER_SIZE

#define NETWORK_WEBRTC_ICE_EXTENSIONS_BUFFER_SIZE   256

Definition at line 60 of file ice.h.

NETWORK_WEBRTC_ICE_FOUNDATION_BUFFER_SIZE

#define NETWORK_WEBRTC_ICE_FOUNDATION_BUFFER_SIZE   32

Definition at line 58 of file ice.h.

NETWORK_WEBRTC_ICE_RADDR_BUFFER_SIZE

#define NETWORK_WEBRTC_ICE_RADDR_BUFFER_SIZE   64

Definition at line 59 of file ice.h.

Typedef Documentation

ice_send_candidate_callback_t

typedef asciichat_error_t(* ice_send_candidate_callback_t) (const ice_candidate_t *candidate, const char *mid, void *user_data)

Single ICE candidate for connectivity.

Callback for sending ICE candidate to peer

Called by ICE agent when a new candidate is discovered. Implementation should send via ACDS relay.

Parameters

candidate	Discovered candidate
mid	Media stream ID (e.g., "0" for audio, "1" for video)
user_data	User context pointer

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 161 of file ice.h.

Enumeration Type Documentation

ice_candidate_type_t

enum ice_candidate_type_t

Credentials and callback used while gathering ICE candidates.

ICE candidate type enumeration (RFC 5245)

Enumerator
ICE_CANDIDATE_HOST	Host candidate (local IP address).
ICE_CANDIDATE_SRFLX	Server-reflexive (NAT-discovered via STUN).
ICE_CANDIDATE_PRFLX	Peer-reflexive (discovered during checks).
ICE_CANDIDATE_RELAY	Relay candidate (TURN server).

Definition at line 81 of file ice.h.

             {
  ICE_CANDIDATE_HOST = 0,  
  ICE_CANDIDATE_SRFLX = 1, 
  ICE_CANDIDATE_PRFLX = 2, 
  ICE_CANDIDATE_RELAY = 3, 
} ice_candidate_type_t;

ice_protocol_t

enum ice_protocol_t

ICE candidate transport protocol.

Enumerator
ICE_PROTOCOL_UDP
ICE_PROTOCOL_TCP

Definition at line 91 of file ice.h.

             {
  ICE_PROTOCOL_UDP = 0,
  ICE_PROTOCOL_TCP = 1,
} ice_protocol_t;

ice_tcp_type_t

enum ice_tcp_type_t

ICE candidate TCP type (if applicable).

Enumerator
ICE_TCP_TYPE_ACTIVE	Actively opens connection.
ICE_TCP_TYPE_PASSIVE	Passively waits for connection.
ICE_TCP_TYPE_SO	Simultaneous open.

Definition at line 99 of file ice.h.

             {
  ICE_TCP_TYPE_ACTIVE = 0,  
  ICE_TCP_TYPE_PASSIVE = 1, 
  ICE_TCP_TYPE_SO = 2,      
} ice_tcp_type_t;

Function Documentation

ice_add_remote_candidate()

asciichat_error_t ice_add_remote_candidate	(	struct webrtc_peer_connection *	pc,
		const ice_candidate_t *	candidate,
		const char *	mid )

Add remote candidate to peer connection.

Called when receiving candidate from peer. The WebRTC agent will test connectivity with this candidate.

Parameters

pc	Peer connection to add candidate to
candidate	Remote candidate from peer
mid	Media stream ID

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 423 of file ice.c.

                                                            {
  if (!pc || !candidate || !mid) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid remote candidate parameters");
  }
 
  // Validate candidate has required fields
  if (candidate->ip_address[0] == '\0' || candidate->port == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Candidate missing IP address or port");
  }
 
  log_debug("ICE: Adding remote candidate %s:%u (type=%s, foundation=%s) on mid=%s", candidate->ip_address,
            candidate->port, ice_candidate_type_name(candidate->type), candidate->foundation, mid);
 
  // Format candidate to SDP attribute line for libdatachannel
  char candidate_line[NETWORK_WEBRTC_ICE_CANDIDATE_LINE_BUFFER_SIZE];
  asciichat_error_t err = ice_format_candidate(candidate, candidate_line, sizeof(candidate_line));
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  // Delegate to WebRTC layer
  return webrtc_add_remote_candidate(pc, candidate_line, mid);
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ice_candidate_t::foundation, ice_candidate_type_name(), ice_format_candidate(), ice_candidate_t::ip_address, log_debug, NETWORK_WEBRTC_ICE_CANDIDATE_LINE_BUFFER_SIZE, ice_candidate_t::port, SET_ERRNO, ice_candidate_t::type, and webrtc_add_remote_candidate().

ice_calculate_priority()

uint32_t ice_calculate_priority	(	ice_candidate_type_t	type,
		uint16_t	local_preference,
		uint8_t	component_id )

Calculate candidate priority.

Implements RFC 5245 priority formula: priority = (2^24 * typePreference) + (2^8 * localPreference) + (256 - componentID)

Parameters

type	Candidate type (determines typePreference)
local_preference	Local preference (0-65535, higher = preferred)
component_id	Component ID (1 or 2)

Returns

Calculated priority

Definition at line 104 of file ice.c.

                                                                                                            {
  // RFC 5245: priority = (2^24 * typePreference) + (2^8 * localPreference) + (256 - componentID)
 
  // Type preference (higher is better):
  // - Host: 126 (most preferred, lowest latency)
  // - SRFLX: 100 (STUN-discovered address)
  // - PRFLX: 110 (discovered during connectivity checks)
  // - Relay: 0 (least preferred, uses bandwidth)
 
  uint8_t type_preference = 0;
  switch (type) {
  case ICE_CANDIDATE_HOST:
    type_preference = 126;
    break;
  case ICE_CANDIDATE_SRFLX:
    type_preference = 100;
    break;
  case ICE_CANDIDATE_PRFLX:
    type_preference = 110;
    break;
  case ICE_CANDIDATE_RELAY:
  default:
    type_preference = 0;
    break;
  }
 
  uint32_t priority =
      (((uint32_t)type_preference) << 24) | (((uint32_t)local_preference) << 8) | (256 - (uint32_t)component_id);
 
  return priority;
}

References ICE_CANDIDATE_HOST, ICE_CANDIDATE_PRFLX, ICE_CANDIDATE_RELAY, and ICE_CANDIDATE_SRFLX.

Referenced by ice_calculate_priority_for_candidate().

ice_calculate_priority_for_candidate()

uint32_t ice_calculate_priority_for_candidate

(

const ice_candidate_t *

candidate

)

Calculate candidate priority with IP-aware local preference.

Automatically determines local_preference based on IP address classification:

• LAN addresses (192.168.x.x, 10.x.x.x, etc.): Highest priority (65535)
• Localhost (127.x.x.x, ::1): High priority (65000)
• Internet (public IPs): Medium priority (32768)
• Unknown/invalid: Lowest priority (0)

This prioritization improves connection establishment by preferring:

1. Local network peers (lowest latency, no NAT)
2. Public IPs (direct connectivity)
3. Unknown addresses (fallback)

Parameters

candidate

ICE candidate with IP address to classify

Returns

Calculated priority using RFC 5245 formula with IP-based local preference

Example

ice_candidate_t candidate = {
  .type = ICE_CANDIDATE_HOST,
  .ip_address = "192.168.1.100",
  .component_id = 1
};
uint32_t priority = ice_calculate_priority_for_candidate(&candidate);
// Returns high priority due to LAN address

Definition at line 136 of file ice.c.

                                                                                {
  if (!candidate) {
    return 0;
  }
 
  // Calculate local preference based on IP classification
  uint16_t local_pref = ice_calculate_local_preference_by_ip(candidate->ip_address);
 
  // Use standard RFC 5245 priority formula with IP-aware local preference
  return ice_calculate_priority(candidate->type, local_pref, (uint8_t)candidate->component_id);
}

References ice_candidate_t::component_id, ice_calculate_priority(), ice_candidate_t::ip_address, and ice_candidate_t::type.

ice_candidate_type_name()

const char * ice_candidate_type_name

(

ice_candidate_type_t

type

)

Get human-readable candidate type name.

Parameters

type	Candidate type

Returns

Static string (e.g., "host", "srflx", "relay")

Definition at line 29 of file ice.c.

                                                               {
  switch (type) {
  case ICE_CANDIDATE_HOST:
    return "host";
  case ICE_CANDIDATE_SRFLX:
    return "srflx";
  case ICE_CANDIDATE_PRFLX:
    return "prflx";
  case ICE_CANDIDATE_RELAY:
    return "relay";
  default:
    return "unknown";
  }
}

References ICE_CANDIDATE_HOST, ICE_CANDIDATE_PRFLX, ICE_CANDIDATE_RELAY, and ICE_CANDIDATE_SRFLX.

Referenced by ice_add_remote_candidate(), and ice_format_candidate().

ice_format_candidate()

asciichat_error_t ice_format_candidate	(	const ice_candidate_t *	candidate,
		char *	line,
		size_t	line_size )

Format ICE candidate to attribute string.

Converts ice_candidate_t structure to SDP attribute line.

Parameters

candidate	Candidate to format
line	Output buffer for SDP line (without "a=candidate:" prefix)
line_size	Size of output buffer

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 323 of file ice.c.

                                                                                                       {
  if (!candidate || !line || line_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid candidate format parameters");
  }
 
  // Format: foundation component protocol priority ip port typ type [raddr rport] [tcptype type]
  // Example: 1 1 udp 2130706431 192.168.1.1 54321 typ host
  // Example with raddr: 1 1 udp 2130706431 203.0.113.45 54321 typ srflx raddr 192.168.1.1 rport 12345
 
  int written = safe_snprintf(line, line_size, "%s %u %s %u %s %u typ %s", candidate->foundation,
                              candidate->component_id, ice_protocol_name(candidate->protocol), candidate->priority,
                              candidate->ip_address, candidate->port, ice_candidate_type_name(candidate->type));
 
  if (written < 0 || (size_t)written >= line_size) {
    return SET_ERRNO(ERROR_BUFFER_FULL, "Candidate line too large for buffer");
  }
 
  size_t remaining = line_size - (size_t)written;
  char *pos = line + written;
 
  // 2. If srflx/prflx/relay: append raddr and rport
  if (candidate->type == ICE_CANDIDATE_SRFLX || candidate->type == ICE_CANDIDATE_PRFLX ||
      candidate->type == ICE_CANDIDATE_RELAY) {
    if (candidate->raddr[0] != '\0') {
      int appended = safe_snprintf(pos, remaining, " raddr %s rport %u", candidate->raddr, candidate->rport);
      if (appended < 0 || (size_t)appended >= remaining) {
        return SET_ERRNO(ERROR_BUFFER_FULL, "Cannot append raddr/rport to candidate line");
      }
      pos += appended;
      remaining -= (size_t)appended;
    }
  }
 
  // 3. If TCP: append tcptype
  if (candidate->protocol == ICE_PROTOCOL_TCP) {
    const char *tcptype_str = "passive"; // default
    if (candidate->tcp_type == ICE_TCP_TYPE_ACTIVE) {
      tcptype_str = "active";
    } else if (candidate->tcp_type == ICE_TCP_TYPE_SO) {
      tcptype_str = "so";
    }
 
    int appended = safe_snprintf(pos, remaining, " tcptype %s", tcptype_str);
    if (appended < 0 || (size_t)appended >= remaining) {
      return SET_ERRNO(ERROR_BUFFER_FULL, "Cannot append tcptype to candidate line");
    }
    pos += appended;
    remaining -= (size_t)appended;
  }
 
  // 4. Append any extensions
  if (candidate->extensions[0] != '\0') {
    int appended = safe_snprintf(pos, remaining, " %s", candidate->extensions);
    if (appended < 0 || (size_t)appended >= remaining) {
      return SET_ERRNO(ERROR_BUFFER_FULL, "Cannot append extensions to candidate line");
    }
  }
 
  // 5. Ensure line is null-terminated (snprintf already does this)
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ice_candidate_t::component_id, ERROR_BUFFER_FULL, ERROR_INVALID_PARAM, ice_candidate_t::extensions, ice_candidate_t::foundation, ICE_CANDIDATE_PRFLX, ICE_CANDIDATE_RELAY, ICE_CANDIDATE_SRFLX, ice_candidate_type_name(), ice_protocol_name(), ICE_PROTOCOL_TCP, ICE_TCP_TYPE_ACTIVE, ICE_TCP_TYPE_SO, ice_candidate_t::ip_address, ice_candidate_t::port, ice_candidate_t::priority, ice_candidate_t::protocol, ice_candidate_t::raddr, ice_candidate_t::rport, safe_snprintf(), SET_ERRNO, ice_candidate_t::tcp_type, and ice_candidate_t::type.

Referenced by ice_add_remote_candidate().

ice_gather_candidates()

asciichat_error_t ice_gather_candidates

(

const ice_config_t *

config

)

Start ICE candidate gathering.

Initiates gathering of candidates from all sources:

• Host candidates (network interfaces)
• STUN server (server-reflexive)
• TURN relay

Candidates are reported via callback as they're discovered.

Parameters

config

ICE gathering configuration

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 389 of file ice.c.

                                                                    {
  if (!config) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid ICE config");
  }
 
  if (!config->send_callback) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ICE config missing send_callback");
  }
 
  log_debug("ICE: Starting candidate gathering (ufrag=%s, pwd=%s)", config->ufrag, config->pwd);
 
  // NOTE: libdatachannel (juice) handles ICE candidate gathering internally.
  // This function is a placeholder for the callback-based API.
  // The actual gathering happens in the peer_manager when you:
  //   1. Create peer connection with rtcCreatePeerConnection()
  //   2. Set ice candidate callback with rtcSetIceCandidateCallback()
  //   3. libdatachannel automatically gathers candidates from:
  //      - Local interfaces (host candidates)
  //      - STUN servers (server-reflexive candidates)
  //      - TURN servers (relay candidates)
  //   4. When a candidate is found, rtcSetIceCandidateCallback() is called
  //   5. Application (webrtc.c) formats and sends via ACDS signaling
  //
  // This ice_gather_candidates() function may not be called directly -
  // the gathering happens automatically when peer connection is created.
  // Keeping this for API compatibility.
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_debug, ice_config_t::pwd, ice_config_t::send_callback, SET_ERRNO, and ice_config_t::ufrag.

ice_get_selected_pair()

asciichat_error_t ice_get_selected_pair	(	struct webrtc_peer_connection *	pc,
		ice_candidate_t *	local_candidate,
		ice_candidate_t *	remote_candidate )

Get selected candidate pair.

Returns the local and remote candidates that were selected for data flow. Uses libdatachannel's rtcGetSelectedCandidatePair() API via C++ bindings.

Parameters

pc	Peer connection to query
local_candidate	Selected local candidate (output, may be NULL)
remote_candidate	Selected remote candidate (output, may be NULL)

Returns

ASCIICHAT_OK if pair selected, ERROR_INVALID_STATE if no pair selected yet

Definition at line 462 of file ice.c.

                                                                           {
  // Delegate to C++ implementation which uses libdatachannel's C++ API
  return ice_get_selected_pair_impl(pc, local_candidate, remote_candidate);
}

References ice_get_selected_pair_impl().

ice_is_connected()

bool ice_is_connected

(

struct webrtc_peer_connection *

pc

)

Check ICE connection state.

Parameters

pc	Peer connection to check

Returns

true if connected, false otherwise

Definition at line 448 of file ice.c.

                                                    {
  if (!pc) {
    return false;
  }
 
  // Check peer connection state
  webrtc_state_t state = webrtc_get_state(pc);
  return (state == WEBRTC_STATE_CONNECTED);
}

References webrtc_get_state(), and WEBRTC_STATE_CONNECTED.

ice_parse_candidate()

asciichat_error_t ice_parse_candidate	(	const char *	line,
		ice_candidate_t *	candidate )

Parse ICE candidate from attribute string.

Converts SDP candidate attribute line to ice_candidate_t structure.

Format: a=candidate:foundation component protocol priority ip port typ type [raddr rport] [extensions]

Parameters

line	SDP candidate line (without "a=candidate:" prefix)
candidate	Parsed candidate (output)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 319 of file ice.c.

                                                                                    {
  return ice_parse_candidate_pcre2(line, candidate);
}

ice_protocol_name()

const char * ice_protocol_name

(

ice_protocol_t

protocol

)

Get human-readable protocol name.

Parameters

protocol

Protocol type

Returns

Static string (e.g., "udp", "tcp")

Definition at line 44 of file ice.c.

                                                       {
  switch (protocol) {
  case ICE_PROTOCOL_UDP:
    return "udp";
  case ICE_PROTOCOL_TCP:
    return "tcp";
  default:
    return "unknown";
  }
}

References ICE_PROTOCOL_TCP, and ICE_PROTOCOL_UDP.

Referenced by ice_format_candidate().

webrtc_get_rtc_id()

int webrtc_get_rtc_id

(

webrtc_peer_connection_t *

pc

)

Get the internal libdatachannel peer connection ID.

Helper function for C++ code that needs access to internal rtc_id without exposing the full structure definition.

Parameters

pc	Peer connection to query

Returns

libdatachannel peer connection ID, or -1 if pc is NULL

Helper function for C++ code that needs access to internal rtc_id without exposing the full structure definition.

Parameters

pc	Peer connection

Returns

libdatachannel peer connection ID, or -1 if pc is NULL

Definition at line 1062 of file lib/network/webrtc/webrtc.c.

                                                    {
  if (!pc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid null peer connectiont");
    return -1;
  }
  return pc->rtc_id;
}