ice.c File Reference

ICE candidate gathering and exchange. More...

Go to the source code of this file.

Macros
#define	PCRE2_CODE_UNIT_WIDTH   8

Functions
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.
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_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.
asciichat_error_t	ice_gather_candidates (const ice_config_t *config)
	Start ICE candidate gathering.
asciichat_error_t	ice_add_remote_candidate (webrtc_peer_connection_t *pc, const ice_candidate_t *candidate, const char *mid)
	Add remote candidate to peer connection.
bool	ice_is_connected (webrtc_peer_connection_t *pc)
	Check ICE connection state.
asciichat_error_t	ice_get_selected_pair_impl (webrtc_peer_connection_t *pc, ice_candidate_t *local_candidate, ice_candidate_t *remote_candidate)
	Get selected ICE candidate pair (C++ implementation)
asciichat_error_t	ice_get_selected_pair (webrtc_peer_connection_t *pc, ice_candidate_t *local_candidate, ice_candidate_t *remote_candidate)
	Get selected candidate pair.

Detailed Description

ICE candidate gathering and exchange.

Implements ICE candidate collection from STUN/TURN servers and relay via ACDS signaling.

Date

January 2026

Definition in file ice.c.

Macro Definition Documentation

PCRE2_CODE_UNIT_WIDTH

#define PCRE2_CODE_UNIT_WIDTH   8

Definition at line 19 of file ice.c.

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 420 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[512];
  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, 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 101 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 133 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 26 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 320 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 386 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 459 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_get_selected_pair_impl()

asciichat_error_t ice_get_selected_pair_impl	(	webrtc_peer_connection_t *	pc,
		ice_candidate_t *	local_candidate,
		ice_candidate_t *	remote_candidate
	)

Get selected ICE candidate pair (C++ implementation)

This function uses libdatachannel's C++ API to retrieve the selected candidate pair, which is not available in the C API.

Definition at line 58 of file ice_selected_pair.cpp.

                                                                                {
  if (!pc) {
    return ERROR_INVALID_PARAM;
  }
 
  try {
    // Get the libdatachannel peer connection ID using helper function
    int rtc_id = webrtc_get_rtc_id(pc);
    if (rtc_id < 0) {
      return ERROR_INVALID_PARAM;
    }
 
    // Query selected candidate pair from libdatachannel
    // Note: This requires libdatachannel to have the selected candidate pair available
    char local_buf[512];
    char remote_buf[512];
 
    // Try to get the selected local candidate
    if (rtcGetSelectedCandidatePair(rtc_id, local_buf, sizeof(local_buf), remote_buf, sizeof(remote_buf)) < 0) {
      // No pair selected yet, or error accessing it
      return ERROR_INVALID_STATE;
    }
 
    // Parse local candidate if requested
    if (local_candidate) {
      std::string local_str(local_buf);
      asciichat_error_t err = parse_datachannel_candidate(local_str, local_candidate);
      if (err != ASCIICHAT_OK) {
        return err;
      }
    }
 
    // Parse remote candidate if requested
    if (remote_candidate) {
      std::string remote_str(remote_buf);
      asciichat_error_t err = parse_datachannel_candidate(remote_str, remote_candidate);
      if (err != ASCIICHAT_OK) {
        return err;
      }
    }
 
    return ASCIICHAT_OK;
 
  } catch (const std::exception &e) {
    return ERROR_NETWORK;
  } catch (...) {
    return ERROR_NETWORK;
  }
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NETWORK, and webrtc_get_rtc_id().

Referenced by ice_get_selected_pair().

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 445 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 316 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 41 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().