WebRTC P2P Connections

WebRTC DataChannel transport for ACIP packets. More...

Files
file	ice_selected_pair.cpp
	C++ implementation for retrieving selected ICE candidate pair.
file	ice.h
	ICE (Interactive Connectivity Establishment) for WebRTC.
file	sdp.h
	SDP (Session Description Protocol) for WebRTC audio/video negotiation.

Data Structures
struct	webrtc_config_t
	WebRTC configuration. More...
struct	webrtc_datachannel_callbacks_t
	DataChannel callback structure. More...

Typedefs
typedef struct webrtc_peer_connection	webrtc_peer_connection_t
typedef struct webrtc_data_channel	webrtc_data_channel_t
typedef void(*	webrtc_state_callback_t) (webrtc_peer_connection_t *pc, webrtc_state_t state, void *user_data)
	Callback for state changes.
typedef void(*	webrtc_local_description_callback_t) (webrtc_peer_connection_t *pc, const char *sdp, const char *type, void *user_data)
	Callback for local SDP offer/answer generation.
typedef void(*	webrtc_local_candidate_callback_t) (webrtc_peer_connection_t *pc, const char *candidate, const char *mid, void *user_data)
	Callback for local ICE candidate discovery.
typedef void(*	webrtc_gathering_state_callback_t) (webrtc_peer_connection_t *pc, webrtc_gathering_state_t state, void *user_data)
	Callback for ICE gathering state changes.
typedef void(*	webrtc_datachannel_open_callback_t) (webrtc_data_channel_t *dc, void *user_data)
	Callback for DataChannel open event.
typedef void(*	webrtc_datachannel_message_callback_t) (webrtc_data_channel_t *dc, const uint8_t *data, size_t size, void *user_data)
	Callback for DataChannel message received.
typedef void(*	webrtc_datachannel_error_callback_t) (webrtc_data_channel_t *dc, const char *error, void *user_data)
	Callback for DataChannel error.

Enumerations
enum	webrtc_state_t {   WEBRTC_STATE_NEW = 0 , WEBRTC_STATE_CONNECTING , WEBRTC_STATE_CONNECTED , WEBRTC_STATE_DISCONNECTED ,   WEBRTC_STATE_FAILED , WEBRTC_STATE_CLOSED }
	WebRTC connection state. More...
enum	webrtc_gathering_state_t { WEBRTC_GATHERING_NEW = 0 , WEBRTC_GATHERING_GATHERING , WEBRTC_GATHERING_COMPLETE }
	ICE gathering state. More...

Functions
asciichat_error_t	webrtc_init (void)
	Initialize WebRTC library (libdatachannel)
void	webrtc_destroy (void)
	Cleanup WebRTC library resources.
asciichat_error_t	webrtc_create_peer_connection (const webrtc_config_t *config, webrtc_peer_connection_t **pc_out)
	Create a new WebRTC peer connection.
void	webrtc_close_peer_connection (webrtc_peer_connection_t *pc)
	Close and destroy a peer connection.
webrtc_state_t	webrtc_get_state (webrtc_peer_connection_t *pc)
	Get current connection state.
webrtc_gathering_state_t	webrtc_get_gathering_state (webrtc_peer_connection_t *pc)
	Get current ICE gathering state.
bool	webrtc_is_gathering_timed_out (webrtc_peer_connection_t *pc, uint32_t timeout_ms)
	Check if ICE gathering has timed out.
void *	webrtc_get_user_data (webrtc_peer_connection_t *pc)
	Get user data pointer from connection.
asciichat_error_t	webrtc_create_offer (webrtc_peer_connection_t *pc)
	Create and set local SDP offer (for connection initiator)
asciichat_error_t	webrtc_set_remote_description (webrtc_peer_connection_t *pc, const char *sdp, const char *type)
	Set remote SDP offer/answer.
asciichat_error_t	webrtc_add_remote_candidate (webrtc_peer_connection_t *pc, const char *candidate, const char *mid)
	Add remote ICE candidate.
asciichat_error_t	webrtc_create_datachannel (webrtc_peer_connection_t *pc, const char *label, webrtc_data_channel_t **dc_out)
	Create a DataChannel (for connection initiator)
asciichat_error_t	webrtc_datachannel_send (webrtc_data_channel_t *dc, const uint8_t *data, size_t size)
	Send data over DataChannel.
asciichat_error_t	webrtc_datachannel_get_buffered_amount (webrtc_data_channel_t *dc, size_t *amount)
asciichat_error_t	webrtc_datachannel_get_max_message_size (webrtc_data_channel_t *dc, size_t *size)
bool	webrtc_datachannel_is_open (webrtc_data_channel_t *dc)
	Check if DataChannel is open and ready.
void	webrtc_datachannel_set_open_state (webrtc_data_channel_t *dc, bool is_open)
	Set DataChannel open state (internal use)
const char *	webrtc_datachannel_get_label (webrtc_data_channel_t *dc)
	Get DataChannel label.
asciichat_error_t	webrtc_datachannel_set_callbacks (webrtc_data_channel_t *dc, const webrtc_datachannel_callbacks_t *callbacks)
	Set DataChannel callbacks.
void	webrtc_close_datachannel (webrtc_data_channel_t *dc)
	Close a DataChannel.
void	webrtc_datachannel_destroy (webrtc_data_channel_t *dc)
	Destroy a DataChannel and free resources.
void	webrtc_peer_connection_close (webrtc_peer_connection_t *pc)
	Close a peer connection.
void	webrtc_peer_connection_destroy (webrtc_peer_connection_t *pc)
	Destroy a peer connection and free resources.
int	webrtc_get_rtc_id (webrtc_peer_connection_t *pc)
	Get the internal libdatachannel peer connection ID.

Detailed Description

WebRTC DataChannel transport for ACIP packets.

Typedef Documentation

webrtc_data_channel_t

typedef struct webrtc_data_channel webrtc_data_channel_t

#include <webrtc.h>

Definition at line 36 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_datachannel_error_callback_t

typedef void(* webrtc_datachannel_error_callback_t) (webrtc_data_channel_t *dc, const char *error, void *user_data)

#include <webrtc.h>

Callback for DataChannel error.

Parameters

dc	Data channel
error	Error message (null-terminated)
user_data	User-provided context pointer

Definition at line 123 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_datachannel_message_callback_t

typedef void(* webrtc_datachannel_message_callback_t) (webrtc_data_channel_t *dc, const uint8_t *data, size_t size, void *user_data)

#include <webrtc.h>

Callback for DataChannel message received.

Parameters

dc	Data channel
data	Message data (binary)
size	Message size in bytes
user_data	User-provided context pointer

Definition at line 114 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_datachannel_open_callback_t

typedef void(* webrtc_datachannel_open_callback_t) (webrtc_data_channel_t *dc, void *user_data)

#include <webrtc.h>

Callback for DataChannel open event.

Parameters

dc	Data channel that opened
user_data	User-provided context pointer

Definition at line 105 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_gathering_state_callback_t

typedef void(* webrtc_gathering_state_callback_t) (webrtc_peer_connection_t *pc, webrtc_gathering_state_t state, void *user_data)

#include <webrtc.h>

Callback for ICE gathering state changes.

Parameters

pc	Peer connection
state	New gathering state
user_data	User-provided context pointer

Definition at line 97 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_local_candidate_callback_t

typedef void(* webrtc_local_candidate_callback_t) (webrtc_peer_connection_t *pc, const char *candidate, const char *mid, void *user_data)

#include <webrtc.h>

Callback for local ICE candidate discovery.

Parameters

pc	Peer connection
candidate	ICE candidate string (null-terminated)
mid	Media stream ID (null-terminated)
user_data	User-provided context pointer

Application should send this candidate to the remote peer via signaling channel (ACDS).

Definition at line 88 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_local_description_callback_t

typedef void(* webrtc_local_description_callback_t) (webrtc_peer_connection_t *pc, const char *sdp, const char *type, void *user_data)

#include <webrtc.h>

Callback for local SDP offer/answer generation.

Parameters

pc	Peer connection
sdp	SDP string (null-terminated)
type	SDP type ("offer" or "answer")
user_data	User-provided context pointer

Application should send this SDP to the remote peer via signaling channel (ACDS).

Definition at line 76 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_peer_connection_t

typedef struct webrtc_peer_connection webrtc_peer_connection_t

#include <webrtc.h>

Definition at line 35 of file include/ascii-chat/network/webrtc/webrtc.h.

webrtc_state_callback_t

typedef void(* webrtc_state_callback_t) (webrtc_peer_connection_t *pc, webrtc_state_t state, void *user_data)

#include <webrtc.h>

Callback for state changes.

Parameters

pc	Peer connection
state	New connection state
user_data	User-provided context pointer

Definition at line 65 of file include/ascii-chat/network/webrtc/webrtc.h.

Enumeration Type Documentation

webrtc_gathering_state_t

enum webrtc_gathering_state_t

#include <webrtc.h>

ICE gathering state.

Enumerator
WEBRTC_GATHERING_NEW	Not started.
WEBRTC_GATHERING_GATHERING	Gathering candidates.
WEBRTC_GATHERING_COMPLETE	All candidates gathered.

Definition at line 53 of file include/ascii-chat/network/webrtc/webrtc.h.

             {
  WEBRTC_GATHERING_NEW = 0,   
  WEBRTC_GATHERING_GATHERING, 
  WEBRTC_GATHERING_COMPLETE   
} webrtc_gathering_state_t;

webrtc_state_t

enum webrtc_state_t

#include <webrtc.h>

WebRTC connection state.

Enumerator
WEBRTC_STATE_NEW	Connection created but not started.
WEBRTC_STATE_CONNECTING	ICE gathering/connection in progress.
WEBRTC_STATE_CONNECTED	DataChannel established and ready.
WEBRTC_STATE_DISCONNECTED	Connection lost.
WEBRTC_STATE_FAILED	Connection failed (fatal)
WEBRTC_STATE_CLOSED	Connection closed cleanly.

Definition at line 41 of file include/ascii-chat/network/webrtc/webrtc.h.

             {
  WEBRTC_STATE_NEW = 0,      
  WEBRTC_STATE_CONNECTING,   
  WEBRTC_STATE_CONNECTED,    
  WEBRTC_STATE_DISCONNECTED, 
  WEBRTC_STATE_FAILED,       
  WEBRTC_STATE_CLOSED        
} webrtc_state_t;

Function Documentation

webrtc_add_remote_candidate()

asciichat_error_t webrtc_add_remote_candidate	(	webrtc_peer_connection_t *	pc,
		const char *	candidate,
		const char *	mid
	)

#include <webrtc.h>

Add remote ICE candidate.

Parameters

pc	Peer connection
candidate	ICE candidate string (null-terminated)
mid	Media stream ID (null-terminated, can be empty)

Returns

ASCIICHAT_OK on success, error code on failure

Adds a remote ICE candidate received via signaling channel.

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

                                                                                                                    {
  if (!pc || !candidate) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  log_debug("  [4] Before libdatachannel - candidate: '%s' (len=%zu)", candidate, strlen(candidate));
  log_debug("  [4] Before libdatachannel - mid: '%s' (len=%zu)", mid ? mid : "(null)", mid ? strlen(mid) : 0);
 
  int result = rtcAddRemoteCandidate(pc->rtc_id, candidate, mid);
  if (result != RTC_ERR_SUCCESS) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to add remote ICE candidate (rtc error %d)", result);
  }
 
  log_debug("Added remote ICE candidate (pc_id=%d)", pc->rtc_id);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, log_debug, webrtc_peer_connection::rtc_id, and SET_ERRNO.

Referenced by ice_add_remote_candidate(), and webrtc_peer_manager_handle_ice().

webrtc_close_datachannel()

void webrtc_close_datachannel

(

webrtc_data_channel_t *

dc

)

#include <webrtc.h>

Close a DataChannel.

Parameters

dc	Data channel to close

Closes the channel gracefully. Safe to call with NULL pointer.

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

                                                         {
  if (!dc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "DataChannel is NULL");
    return;
  }
  if (dc->rtc_id < 0) {
    atomic_store_bool(&dc->is_open, false);
    return;
  }
 
  // Save the ID before deleting the native channel.
  int dc_id = dc->rtc_id;
 
  rtcDeleteDataChannel(dc_id);
  log_debug("Closed DataChannel (dc_id=%d)", dc_id);
  dc->rtc_id = -1;
  atomic_store_bool(&dc->is_open, false);
}

References atomic_store_bool(), ERROR_INVALID_PARAM, webrtc_data_channel::is_open, log_debug, webrtc_data_channel::rtc_id, and SET_ERRNO.

Referenced by webrtc_close_peer_connection(), and webrtc_datachannel_destroy().

webrtc_close_peer_connection()

void webrtc_close_peer_connection

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

Close and destroy a peer connection.

Parameters

pc	Peer connection to close

Closes the connection gracefully and frees all resources. Safe to call with NULL pointer.

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

                                                                {
  if (!pc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid peer connection");
    return;
  }
 
  // Close data channel if exists
  if (pc->dc) {
    webrtc_close_datachannel(pc->dc);
    pc->dc = NULL;
  }
 
  // Close peer connection
  rtcDeletePeerConnection(pc->rtc_id);
  log_debug("Closed WebRTC peer connection (id=%d)", pc->rtc_id);
 
  SAFE_FREE(pc);
}

References webrtc_peer_connection::dc, ERROR_INVALID_PARAM, log_debug, webrtc_peer_connection::rtc_id, SAFE_FREE, SET_ERRNO, and webrtc_close_datachannel().

webrtc_create_datachannel()

asciichat_error_t webrtc_create_datachannel	(	webrtc_peer_connection_t *	pc,
		const char *	label,
		webrtc_data_channel_t **	dc_out
	)

#include <webrtc.h>

Create a DataChannel (for connection initiator)

Parameters

pc	Peer connection
label	Channel label (e.g., "acip")
dc_out	Output parameter for data channel handle

Returns

ASCIICHAT_OK on success, error code on failure

Creates a new DataChannel. The initiator should create the channel, while the responder receives it via the datachannel callback.

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

                                                                            {
  if (!pc || !label || !dc_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  // Native peers use DCEP. Browser offers advertise the separately negotiated
  // ACIP channel and are handled in webrtc_set_remote_description().
  int dc_id = rtcCreateDataChannel(pc->rtc_id, label);
  if (dc_id < 0) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to create data channel (rtc error %d)", dc_id);
  }
 
  // Allocate wrapper
  webrtc_data_channel_t *dc = SAFE_CALLOC(1, sizeof(webrtc_data_channel_t), webrtc_data_channel_t *);
  if (!dc) {
    rtcDeleteDataChannel(dc_id);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate data channel wrapper");
  }
 
  dc->rtc_id = dc_id;
  dc->pc = pc;
  atomic_store_bool(&dc->is_open, false);
 
  // Set up callbacks
  rtcSetUserPointer(dc_id, dc);
  rtcSetOpenCallback(dc_id, on_datachannel_open_adapter);
  rtcSetMessageCallback(dc_id, on_datachannel_message_adapter);
  rtcSetErrorCallback(dc_id, on_datachannel_error_adapter);
 
  pc->dc = dc;
  *dc_out = dc;
 
  // Register data channel with debug naming system
  NAMED_REGISTER_DATACHANNEL(dc, label, NULL);
 
  log_debug("Created DataChannel '%s' (dc_id=%d, pc_id=%d)", label, dc_id, pc->rtc_id);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_store_bool(), webrtc_peer_connection::dc, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, webrtc_data_channel::is_open, log_debug, NAMED_REGISTER_DATACHANNEL, webrtc_data_channel::pc, webrtc_peer_connection::rtc_id, webrtc_data_channel::rtc_id, SAFE_CALLOC, and SET_ERRNO.

webrtc_create_offer()

asciichat_error_t webrtc_create_offer

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

Create and set local SDP offer (for connection initiator)

Parameters

pc	Peer connection

Returns

ASCIICHAT_OK on success, error code on failure

Triggers ICE gathering and local description callback with the SDP offer. Use this when initiating a connection to a remote peer.

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

                                                                    {
  if (!pc) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid peer connection");
  }
 
  // Set local description with NULL type to trigger offer generation
  int result = rtcSetLocalDescription(pc->rtc_id, NULL);
  if (result != RTC_ERR_SUCCESS) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to create SDP offer (rtc error %d)", result);
  }
 
  log_debug("Creating SDP offer (pc_id=%d)", pc->rtc_id);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, log_debug, webrtc_peer_connection::rtc_id, and SET_ERRNO.

webrtc_create_peer_connection()

asciichat_error_t webrtc_create_peer_connection	(	const webrtc_config_t *	config,
		webrtc_peer_connection_t **	pc_out
	)

#include <webrtc.h>

Create a new WebRTC peer connection.

Parameters

config	Configuration including ICE servers and callbacks
pc_out	Output parameter for peer connection handle

Returns

ASCIICHAT_OK on success, error code on failure

Creates a new peer connection with the specified configuration. The connection starts in WEBRTC_STATE_NEW state.

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

                                                                                                                  {
  if (!config || !pc_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid config or output parameter");
  }
  *pc_out = NULL;
  if ((config->stun_count && !config->stun_servers) || (config->turn_count && !config->turn_servers)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ICE server counts require server arrays");
  }
  if ((config->turn_username != NULL) != (config->turn_credential != NULL)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "TURN overrides require both username and credential");
  }
 
  if (!lifecycle_is_initialized(&g_webrtc_lc)) {
    return SET_ERRNO(ERROR_INIT, "WebRTC library not initialized");
  }
  if (config->relay_only && config->turn_count == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Relay only requires a TURN server with credentials");
  }
  for (size_t i = 0; i < config->turn_count; i++) {
    const turn_server_t *server = &config->turn_servers[i];
    const char *username = config->turn_username ? config->turn_username : server->username;
    const char *credential = config->turn_credential ? config->turn_credential : server->credential;
    if (!username[0] || !credential[0] || strlen(username) > 127 || strlen(credential) > 127) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "TURN server requires both username and credential");
    }
    if (strncmp(server->url, "turn:", 5) != 0 && strncmp(server->url, "turns:", 6) != 0) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "TURN server URL must start with turn: or turns:");
    }
  }
 
  // Allocate peer connection wrapper
  webrtc_peer_connection_t *pc = SAFE_CALLOC(1, sizeof(webrtc_peer_connection_t), webrtc_peer_connection_t *);
  if (!pc) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate peer connection");
  }
 
  pc->config = *config; // Copy config
  atomic_store_u64(&pc->state, WEBRTC_STATE_NEW);
  pc->dc = NULL;
 
  // Build ICE server list for libdatachannel
  const char **ice_servers = NULL;
  size_t ice_count = 0;
  char *turn_urls = NULL;
 
  if (config->stun_count > 0 || config->turn_count > 0) {
    ice_count = config->stun_count + config->turn_count;
    ice_servers = SAFE_MALLOC(ice_count * sizeof(char *), const char **);
    if (!ice_servers) {
      SAFE_FREE(pc);
      return SET_ERRNO(ERROR_MEMORY, "Failed to allocate ICE server list");
    }
 
    // Add STUN servers
    for (size_t i = 0; i < config->stun_count; i++) {
      ice_servers[i] = config->stun_servers[i].host;
    }
 
    // Add TURN servers
    if (config->turn_count > 0) {
      turn_urls = SAFE_CALLOC(config->turn_count, 1024, char *);
      if (!turn_urls) {
        SAFE_FREE(ice_servers);
        SAFE_FREE(pc);
        return SET_ERRNO(ERROR_MEMORY, "Failed to allocate authenticated TURN URLs");
      }
    }
    for (size_t i = 0; i < config->turn_count; i++) {
      const turn_server_t *server = &config->turn_servers[i];
      char username[128 * 3];
      char credential[128 * 3];
      encode_turn_userinfo(config->turn_username ? config->turn_username : server->username, username,
                           sizeof(username));
      encode_turn_userinfo(config->turn_credential ? config->turn_credential : server->credential, credential,
                           sizeof(credential));
      const char *address = strchr(server->url, ':') + 1;
      while (*address == '/')
        address++;
      SAFE_SNPRINTF(turn_urls + i * 1024, 1024, "%.*s%s:%s@%s", (int)(strchr(server->url, ':') - server->url + 1),
                    server->url, username, credential, address);
      ice_servers[config->stun_count + i] = turn_urls + i * 1024;
    }
  }
 
  // Create libdatachannel configuration
  rtcConfiguration rtc_config;
  memset(&rtc_config, 0, sizeof(rtc_config));
  rtc_config.bindAddress = config->bind_address;
  rtc_config.iceServers = ice_servers;
  rtc_config.iceServersCount = (int)ice_count;
  rtc_config.iceTransportPolicy = config->relay_only ? RTC_TRANSPORT_POLICY_RELAY : RTC_TRANSPORT_POLICY_ALL;
  if (rtc_config.bindAddress && rtc_config.bindAddress[0]) {
    log_info("Binding WebRTC ICE sockets to %s", rtc_config.bindAddress);
  }
 
  // Create peer connection
  int pc_id = rtcCreatePeerConnection(&rtc_config);
  SAFE_FREE(turn_urls);
 
  // Free ICE server list (libdatachannel makes a copy)
  if (ice_servers) {
    SAFE_FREE(ice_servers);
  }
 
  if (pc_id < 0) {
    SAFE_FREE(pc);
    return SET_ERRNO(ERROR_NETWORK, "Failed to create peer connection (rtc error %d)", pc_id);
  }
 
  pc->rtc_id = pc_id;
 
  // Initialize gathering state
  atomic_store_u64(&pc->gathering_state, WEBRTC_GATHERING_NEW);
  atomic_store_u64(&pc->gathering_start_time_ms, 0);
 
  // Set up callbacks
  rtcSetUserPointer(pc_id, pc);
  rtcSetStateChangeCallback(pc_id, on_state_change_adapter);
  rtcSetGatheringStateChangeCallback(pc_id, on_gathering_state_change_adapter);
  rtcSetLocalDescriptionCallback(pc_id, on_local_description_adapter);
  rtcSetLocalCandidateCallback(pc_id, on_local_candidate_adapter);
  rtcSetDataChannelCallback(pc_id, on_datachannel_adapter);
 
  /* Register peer connection with named registry */
  char pc_name[64];
  snprintf(pc_name, sizeof(pc_name), "webrtc_peer_connection:%d", pc_id);
  NAMED_REGISTER(pc, pc_name, "webrtc_peer_connection_t", "0x%tx", NULL);
 
  *pc_out = pc;
  log_debug("Created WebRTC peer connection (id=%d)", pc_id);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_store_u64(), webrtc_config_t::bind_address, webrtc_peer_connection::config, webrtc_peer_connection::dc, ERROR_INIT, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, webrtc_peer_connection::gathering_start_time_ms, webrtc_peer_connection::gathering_state, lifecycle_is_initialized(), log_debug, log_info, NAMED_REGISTER, webrtc_config_t::relay_only, webrtc_peer_connection::rtc_id, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, SAFE_SNPRINTF, SET_ERRNO, webrtc_peer_connection::state, webrtc_config_t::stun_count, webrtc_config_t::stun_servers, webrtc_config_t::turn_count, webrtc_config_t::turn_credential, turn_server_t, webrtc_config_t::turn_servers, webrtc_config_t::turn_username, WEBRTC_GATHERING_NEW, and WEBRTC_STATE_NEW.

webrtc_datachannel_destroy()

void webrtc_datachannel_destroy

(

webrtc_data_channel_t *

dc

)

#include <webrtc.h>

Destroy a DataChannel and free resources.

Parameters

dc	Data channel to destroy

Frees all resources associated with the DataChannel. Automatically closes the channel if still open. Safe to call with NULL pointer.

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

                                                           {
  if (!dc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid null data channel");
    return;
  }
 
  // Close if still open, then free the wrapper.
  webrtc_close_datachannel(dc);
  SAFE_FREE(dc);
}

References ERROR_INVALID_PARAM, SAFE_FREE, SET_ERRNO, and webrtc_close_datachannel().

webrtc_datachannel_get_buffered_amount()

asciichat_error_t webrtc_datachannel_get_buffered_amount	(	webrtc_data_channel_t *	dc,
		size_t *	amount
	)

#include <webrtc.h>

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

                                                                                                    {
  if (!dc || dc->rtc_id < 0 || !amount)
    return SET_ERRNO(ERROR_INVALID_PARAM, "DataChannel and amount are required");
  int result = rtcGetBufferedAmount(dc->rtc_id);
  if (result < 0)
    return SET_ERRNO(ERROR_NETWORK, "Failed to query DataChannel buffered amount");
  *amount = (size_t)result;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, webrtc_data_channel::rtc_id, and SET_ERRNO.

webrtc_datachannel_get_label()

const char * webrtc_datachannel_get_label

(

webrtc_data_channel_t *

dc

)

#include <webrtc.h>

Get DataChannel label.

Parameters

dc	Data channel

Returns

Label string (null-terminated), or NULL on error

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

                                                                    {
  if (!dc || dc->rtc_id < 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "DataChannel is NULL");
    return NULL;
  }
 
  static char label[256];
  int result = rtcGetDataChannelLabel(dc->rtc_id, label, sizeof(label));
  if (result < 0) {
    return NULL;
  }
 
  return label;
}

References ERROR_INVALID_PARAM, webrtc_data_channel::rtc_id, and SET_ERRNO.

webrtc_datachannel_get_max_message_size()

asciichat_error_t webrtc_datachannel_get_max_message_size	(	webrtc_data_channel_t *	dc,
		size_t *	size
	)

#include <webrtc.h>

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

                                                                                                   {
  if (!dc || dc->rtc_id < 0 || !size)
    return SET_ERRNO(ERROR_INVALID_PARAM, "DataChannel and max message size are required");
  int result = rtcMaxMessageSize(dc->rtc_id);
  if (result <= 0)
    return SET_ERRNO(ERROR_NETWORK, "Failed to query DataChannel max message size");
  *size = (size_t)result;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, webrtc_data_channel::rtc_id, and SET_ERRNO.

webrtc_datachannel_is_open()

bool webrtc_datachannel_is_open

(

webrtc_data_channel_t *

dc

)

#include <webrtc.h>

Check if DataChannel is open and ready.

Parameters

dc	Data channel

Returns

true if open, false otherwise

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

                                                           {
  if (!dc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "DataChannel is NULL");
    return false;
  }
  return dc->rtc_id >= 0 && atomic_load_bool(&dc->is_open);
}

References atomic_load_bool(), ERROR_INVALID_PARAM, webrtc_data_channel::is_open, webrtc_data_channel::rtc_id, and SET_ERRNO.

webrtc_datachannel_send()

asciichat_error_t webrtc_datachannel_send	(	webrtc_data_channel_t *	dc,
		const uint8_t *	data,
		size_t	size
	)

#include <webrtc.h>

Send data over DataChannel.

Parameters

dc	Data channel
data	Data buffer (binary)
size	Data size in bytes

Returns

ASCIICHAT_OK on success, error code on failure

Sends binary data over the DataChannel. Returns error if channel is not open.

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

                                                                                                       {
  if (!dc || dc->rtc_id < 0 || !data) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (!atomic_load_bool(&dc->is_open)) {
    log_error("★ WEBRTC_DATACHANNEL_SEND: Channel not open! size=%zu, dc->rtc_id=%d", size, dc ? dc->rtc_id : -1);
    return SET_ERRNO(ERROR_NETWORK, "DataChannel not open");
  }
 
  // Log packet details at network layer (debug level for normal operation)
  if (size >= 20) {
    const uint8_t *pkt = (const uint8_t *)data;
    log_dev("★ RTCSENDMESSAGE_BEFORE: dc_id=%d, size=%zu, first_20_bytes: %02x%02x%02x%02x %02x%02x%02x%02x "
            "%02x%02x%02x%02x %02x%02x%02x%02x %02x%02x%02x%02x",
            dc->rtc_id, size, pkt[0], pkt[1], pkt[2], pkt[3], pkt[4], pkt[5], pkt[6], pkt[7], pkt[8], pkt[9], pkt[10],
            pkt[11], pkt[12], pkt[13], pkt[14], pkt[15], pkt[16], pkt[17], pkt[18], pkt[19]);
  } else {
    log_dev("★ RTCSENDMESSAGE_BEFORE: dc_id=%d, size=%zu (too small to log content)", dc->rtc_id, size);
  }
 
  int result = rtcSendMessage(dc->rtc_id, (const char *)data, (int)size);
 
  log_dev("★ RTCSENDMESSAGE_AFTER: dc_id=%d, rtcSendMessage returned %d for size=%zu", dc->rtc_id, result, size);
 
  if (result < 0) {
    log_error("★ WEBRTC_DATACHANNEL_SEND: FAILED with error code %d", result);
    return SET_ERRNO(ERROR_NETWORK, "Failed to send data (rtc error %d)", result);
  }
 
  log_dev("★ WEBRTC_DATACHANNEL_SEND: SUCCESS - sent %zu bytes", size);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_load_bool(), ERROR_INVALID_PARAM, ERROR_NETWORK, webrtc_data_channel::is_open, log_dev, log_error, webrtc_data_channel::rtc_id, and SET_ERRNO.

webrtc_datachannel_set_callbacks()

asciichat_error_t webrtc_datachannel_set_callbacks	(	webrtc_data_channel_t *	dc,
		const webrtc_datachannel_callbacks_t *	callbacks
	)

#include <webrtc.h>

Set DataChannel callbacks.

Parameters

dc	Data channel
callbacks	Callback structure

Returns

ASCIICHAT_OK on success, error code on failure

Registers callbacks for DataChannel events. Any NULL callback pointer is ignored.

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

                                                                                                    {
  if (!dc) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "DataChannel is NULL");
  }
 
  if (!callbacks) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Callbacks struct is NULL");
  }
 
  // Store user callbacks in the data channel struct
  dc->user_on_open = callbacks->on_open;
  dc->user_on_close = callbacks->on_close;
  dc->user_on_error = callbacks->on_error;
  dc->user_on_message = callbacks->on_message;
  dc->user_data = callbacks->user_data;
 
  // Register adapter functions with libdatachannel (adapters use correct signature)
  // The adapters will look up our stored callbacks and invoke them with proper types
  if (callbacks->on_open) {
    rtcSetOpenCallback(dc->rtc_id, on_datachannel_open_adapter);
  }
 
  if (callbacks->on_close) {
    rtcSetClosedCallback(dc->rtc_id, on_datachannel_closed_adapter);
  }
 
  if (callbacks->on_error) {
    rtcSetErrorCallback(dc->rtc_id, on_datachannel_error_adapter);
  }
 
  if (callbacks->on_message) {
    rtcSetMessageCallback(dc->rtc_id, on_datachannel_message_adapter);
  }
 
  // Set user pointer to the data channel so adapters can retrieve it
  rtcSetUserPointer(dc->rtc_id, dc);
 
  log_debug("Set DataChannel callbacks (dc_id=%d)", dc->rtc_id);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_debug, webrtc_datachannel_callbacks_t::on_close, webrtc_datachannel_callbacks_t::on_error, webrtc_datachannel_callbacks_t::on_message, webrtc_datachannel_callbacks_t::on_open, webrtc_data_channel::rtc_id, SET_ERRNO, webrtc_datachannel_callbacks_t::user_data, webrtc_data_channel::user_data, webrtc_data_channel::user_on_close, webrtc_data_channel::user_on_error, webrtc_data_channel::user_on_message, and webrtc_data_channel::user_on_open.

Referenced by acip_webrtc_transport_create().

webrtc_datachannel_set_open_state()

void webrtc_datachannel_set_open_state	(	webrtc_data_channel_t *	dc,
		bool	is_open
	)

#include <webrtc.h>

Set DataChannel open state (internal use)

Parameters

dc	Data channel
is_open	Open state to set

Internal function for transport layer to manually set open state when callbacks are replaced after the DataChannel is already open.

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

                                                                                {
  if (!dc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "DataChannel is NULL");
    return;
  }
  atomic_store_bool(&dc->is_open, is_open);
}

References atomic_store_bool(), ERROR_INVALID_PARAM, webrtc_data_channel::is_open, and SET_ERRNO.

Referenced by acip_webrtc_transport_create().

webrtc_destroy()

void webrtc_destroy

(

void

)

#include <webrtc.h>

Cleanup WebRTC library resources.

Should be called at program exit after all connections are closed. Thread-safe and idempotent.

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

                          {
  webrtc_release();
}

webrtc_get_gathering_state()

webrtc_gathering_state_t webrtc_get_gathering_state

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

Get current ICE gathering state.

Parameters

pc	Peer connection

Returns

Current gathering state

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

                                                                                  {
  if (!pc) {
    log_warn("Peer connection is NULL");
    return WEBRTC_GATHERING_NEW;
  }
  return (webrtc_gathering_state_t)atomic_load_u64(&pc->gathering_state);
}

References atomic_load_u64(), webrtc_peer_connection::gathering_state, log_warn, and WEBRTC_GATHERING_NEW.

Referenced by webrtc_peer_manager_check_gathering_timeouts().

webrtc_get_rtc_id()

int webrtc_get_rtc_id

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

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

Returns

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

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

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

References ERROR_INVALID_PARAM, webrtc_peer_connection::rtc_id, and SET_ERRNO.

Referenced by ice_get_selected_pair_impl().

webrtc_get_state()

webrtc_state_t webrtc_get_state

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

Get current connection state.

Parameters

pc	Peer connection

Returns

Current state

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

                                                              {
  if (!pc) {
    log_warn("Peer connection is NULL");
    return WEBRTC_STATE_CLOSED;
  }
  return (webrtc_state_t)atomic_load_u64(&pc->state);
}

References atomic_load_u64(), log_warn, webrtc_peer_connection::state, and WEBRTC_STATE_CLOSED.

Referenced by ice_is_connected(), webrtc_peer_manager_check_gathering_timeouts(), webrtc_peer_manager_get_state(), and webrtc_peer_manager_handle_sdp().

webrtc_get_user_data()

void * webrtc_get_user_data

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

Get user data pointer from connection.

Parameters

pc	Peer connection

Returns

User data pointer (from webrtc_config_t)

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

                                                         {
  if (!pc) {
    log_warn("Peer connection is NULL");
    return NULL;
  }
  return pc->config.user_data;
}

References webrtc_peer_connection::config, log_warn, and webrtc_config_t::user_data.

webrtc_init()

asciichat_error_t webrtc_init

(

void

)

#include <webrtc.h>

Initialize WebRTC library (libdatachannel)

Returns

ASCIICHAT_OK on success, error code on failure

Must be called once before creating any peer connections. Thread-safe and idempotent (safe to call multiple times).

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

                                    {
  return webrtc_ensure_initialized();
}

webrtc_is_gathering_timed_out()

bool webrtc_is_gathering_timed_out	(	webrtc_peer_connection_t *	pc,
		uint32_t	timeout_ms
	)

#include <webrtc.h>

Check if ICE gathering has timed out.

Parameters

pc	Peer connection
timeout_ms	Timeout in milliseconds

Returns

true if gathering is in progress and has exceeded timeout, false otherwise

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

                                                                                      {
  if (!pc) {
    return false;
  }
 
  // Only check timeout if we're actively gathering
  if (atomic_load_u64(&pc->gathering_state) != WEBRTC_GATHERING_GATHERING) {
    return false;
  }
 
  // If gathering hasn't started yet (start_time == 0), no timeout
  uint64_t gathering_start_time_ms = atomic_load_u64(&pc->gathering_start_time_ms);
  if (gathering_start_time_ms == 0) {
    return false;
  }
 
  // Check if elapsed time exceeds timeout
  uint64_t current_time_ms = platform_get_monotonic_time_us() / 1000;
  uint64_t elapsed_ms = current_time_ms - gathering_start_time_ms;
 
  if (elapsed_ms > timeout_ms) {
    return true;
  }
 
  return false;
}

References atomic_load_u64(), webrtc_peer_connection::gathering_start_time_ms, webrtc_peer_connection::gathering_state, platform_get_monotonic_time_us(), and WEBRTC_GATHERING_GATHERING.

Referenced by webrtc_peer_manager_check_gathering_timeouts().

webrtc_peer_connection_close()

void webrtc_peer_connection_close

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

Close a peer connection.

Parameters

pc	Peer connection to close

Closes the peer connection gracefully. Safe to call with NULL pointer.

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

                                                                {
  if (!pc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid null peer connectiont");
    return;
  }
 
  rtcClose(pc->rtc_id);
  log_debug("Closed peer connection (pc_id=%d)", pc->rtc_id);
}

References ERROR_INVALID_PARAM, log_debug, webrtc_peer_connection::rtc_id, and SET_ERRNO.

webrtc_peer_connection_destroy()

void webrtc_peer_connection_destroy

(

webrtc_peer_connection_t *

pc

)

#include <webrtc.h>

Destroy a peer connection and free resources.

Parameters

pc	Peer connection to destroy

Frees all resources associated with the peer connection. Automatically closes the connection if still open. Safe to call with NULL pointer.

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

                                                                  {
  if (!pc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid null peer connectiont");
    return;
  }
 
  // Close and delete peer connection
  rtcDeletePeerConnection(pc->rtc_id);
  log_debug("Destroyed peer connection (pc_id=%d)", pc->rtc_id);
 
  SAFE_FREE(pc);
}

References ERROR_INVALID_PARAM, log_debug, webrtc_peer_connection::rtc_id, SAFE_FREE, and SET_ERRNO.

webrtc_set_remote_description()

asciichat_error_t webrtc_set_remote_description	(	webrtc_peer_connection_t *	pc,
		const char *	sdp,
		const char *	type
	)

#include <webrtc.h>

Set remote SDP offer/answer.

Parameters

pc	Peer connection
sdp	Remote SDP string (null-terminated)
type	SDP type ("offer" or "answer")

Returns

ASCIICHAT_OK on success, error code on failure

Sets the remote peer's SDP. If this is an offer, triggers automatic answer generation via the local description callback.

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

                                                                                                                 {
  if (!pc || !sdp || !type) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  int result = rtcSetRemoteDescription(pc->rtc_id, sdp, type);
  if (result != RTC_ERR_SUCCESS) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to set remote SDP (rtc error %d)", result);
  }
 
  const char *dcmap = strstr(sdp, "a=dcmap:");
  if (strcmp(type, "offer") == 0) {
    log_debug("Remote WebRTC offer DataChannel map: %s", dcmap ? dcmap : "(none)");
  }
  if (strcmp(type, "offer") == 0 && strstr(sdp, "\na=dcmap:0 label=\"acip\"") && !pc->dc) {
    rtcDataChannelInit init = {0};
    init.negotiated = true;
    init.manualStream = true;
    init.stream = 0;
    int dc_id = rtcCreateDataChannelEx(pc->rtc_id, "acip", &init);
    if (dc_id < 0)
      return SET_ERRNO(ERROR_NETWORK, "Failed to create negotiated ACIP channel");
    on_datachannel_adapter(pc->rtc_id, dc_id, pc);
  }
 
  log_debug("Set remote SDP description (pc_id=%d, type=%s)", pc->rtc_id, type);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, webrtc_peer_connection::dc, ERROR_INVALID_PARAM, ERROR_NETWORK, log_debug, webrtc_peer_connection::rtc_id, and SET_ERRNO.

Referenced by webrtc_peer_manager_handle_sdp().