transport.h File Reference

Transport abstraction layer for ACIP protocol. More...

Go to the source code of this file.

Data Structures
struct	acip_transport_methods_t
	Transport method table (virtual function table) More...
struct	acip_transport
	Transport instance structure. More...

Typedefs
typedef struct acip_transport	acip_transport_t
	Forward declaration of transport implementation.

Enumerations
enum	acip_transport_type_t {   ACIP_TRANSPORT_TCP = 1 , ACIP_TRANSPORT_WEBSOCKET = 2 , ACIP_TRANSPORT_WEBRTC = 3 , ACIP_TRANSPORT_HTTP = 4 ,   ACIP_TRANSPORT_QUIC = 5 }
	Transport type enumeration. More...

Functions
void	acip_transport_destroy (acip_transport_t *transport)
	Destroy transport and free all resources.
acip_transport_t *	acip_tcp_transport_create (socket_t sockfd, crypto_context_t *crypto_ctx)
	Create TCP transport from existing socket.
acip_transport_t *	acip_websocket_transport_create (socket_t sockfd, crypto_context_t *crypto_ctx)
	Create WebSocket transport from existing socket.
acip_transport_t *	acip_webrtc_transport_create (struct webrtc_peer_connection *peer_conn, struct webrtc_data_channel *data_channel, crypto_context_t *crypto_ctx)

Detailed Description

Transport abstraction layer for ACIP protocol.

Provides a transport-agnostic interface that allows ACIP protocol handlers to work with any underlying transport (TCP, WebSocket, HTTP, etc.).

DESIGN GOALS:

1. Protocol code never calls socket()/send()/recv() directly
2. Same ACIP handlers work with TCP, WebSocket, or any future transport
3. Transport implementations handle their own connection state
4. Clean separation between protocol logic and transport logic

USAGE PATTERN:

// Create TCP transport
acip_transport_t *tcp = acip_tcp_transport_create(sockfd, crypto_ctx);
 
// Use with ACIP protocol handlers
asciichat_error_t result = acip_send_ascii_frame(tcp, frame_data, frame_size);
 
// Or WebSocket transport (future)
acip_transport_t *ws = acip_websocket_transport_create(ws_handle, crypto_ctx);
asciichat_error_t result = acip_send_ascii_frame(ws, frame_data, frame_size);
 
// Cleanup
acip_transport_destroy(tcp);

MEMORY OWNERSHIP:

• Transport owns its connection state
• send() does NOT take ownership of data (caller must keep it valid)
• recv() allocates buffer, caller must free via out_allocated_buffer
• destroy() cleans up all transport resources

Author

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

Date

January 2026

Definition in file transport.h.

Typedef Documentation

acip_transport_t

typedef struct acip_transport acip_transport_t

Forward declaration of transport implementation.

Opaque handle to transport-specific state. Each transport implementation defines its own state structure.

Definition at line 73 of file transport.h.

Enumeration Type Documentation

acip_transport_type_t

enum acip_transport_type_t

Transport type enumeration.

Identifies which transport implementation is being used. Useful for debugging and conditional logic.

Enumerator
ACIP_TRANSPORT_TCP	Raw TCP socket.
ACIP_TRANSPORT_WEBSOCKET	WebSocket over TCP.
ACIP_TRANSPORT_WEBRTC	WebRTC DataChannel (P2P)
ACIP_TRANSPORT_HTTP	HTTP long-polling (future)
ACIP_TRANSPORT_QUIC	QUIC/UDP (future)

Definition at line 59 of file transport.h.

             {
  ACIP_TRANSPORT_TCP = 1,       
  ACIP_TRANSPORT_WEBSOCKET = 2, 
  ACIP_TRANSPORT_WEBRTC = 3,    
  ACIP_TRANSPORT_HTTP = 4,      
  ACIP_TRANSPORT_QUIC = 5       
} acip_transport_type_t;

Function Documentation

acip_tcp_transport_create()

acip_transport_t * acip_tcp_transport_create	(	socket_t	sockfd,
		crypto_context_t *	crypto_ctx
	)

Create TCP transport from existing socket.

Parameters

sockfd	Connected socket descriptor
crypto_ctx	Optional crypto context (may be NULL)

Returns

Transport instance or NULL on error

Note

Caller retains socket ownership (transport doesn't close on destroy)

Definition at line 208 of file tcp/transport.c.

                                                                                           {
  if (sockfd == INVALID_SOCKET_VALUE) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
    return NULL;
  }
 
  // Allocate transport structure
  acip_transport_t *transport = SAFE_MALLOC(sizeof(acip_transport_t), acip_transport_t *);
  if (!transport) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate TCP transport");
    return NULL;
  }
 
  // Allocate TCP-specific data
  tcp_transport_data_t *tcp_data = SAFE_MALLOC(sizeof(tcp_transport_data_t), tcp_transport_data_t *);
  if (!tcp_data) {
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate TCP transport data");
    return NULL;
  }
 
  // Initialize TCP data
  tcp_data->sockfd = sockfd;
  tcp_data->is_connected = true;
 
  // Initialize transport
  transport->methods = &tcp_methods;
  transport->crypto_ctx = crypto_ctx;
  transport->impl_data = tcp_data;
 
  log_debug("Created TCP transport for socket %d (crypto: %s)", sockfd, crypto_ctx ? "enabled" : "disabled");
 
  return transport;
}

References acip_transport::crypto_ctx, ERROR_INVALID_PARAM, ERROR_MEMORY, acip_transport::impl_data, INVALID_SOCKET_VALUE, tcp_transport_data_t::is_connected, log_debug, acip_transport::methods, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, and tcp_transport_data_t::sockfd.

Referenced by server_connection_establish(), and server_main().

acip_transport_destroy()

void acip_transport_destroy

(

acip_transport_t *

transport

)

Destroy transport and free all resources.

Parameters

transport

Transport to destroy (may be NULL)

Note

Calls close() first if still connected

Frees the transport structure itself

Safe to pass NULL

Definition at line 247 of file tcp/transport.c.

                                                         {
  if (!transport) {
    return;
  }
 
  // Close if still connected
  if (transport->methods && transport->methods->close && transport->methods->is_connected &&
      transport->methods->is_connected(transport)) {
    transport->methods->close(transport);
  }
 
  // Call custom destroy implementation if provided
  if (transport->methods && transport->methods->destroy_impl) {
    transport->methods->destroy_impl(transport);
  }
 
  // Free implementation data
  if (transport->impl_data) {
    SAFE_FREE(transport->impl_data);
  }
 
  // Free transport structure
  SAFE_FREE(transport);
 
  log_debug("Destroyed ACIP transport");
}

References acip_transport_methods_t::close, acip_transport_methods_t::destroy_impl, acip_transport::impl_data, acip_transport_methods_t::is_connected, log_debug, acip_transport::methods, and SAFE_FREE.

Referenced by connection_context_cleanup(), server_connection_close(), server_connection_set_transport(), and server_main().

acip_webrtc_transport_create()

acip_transport_t * acip_webrtc_transport_create	(	struct webrtc_peer_connection *	peer_conn,
		struct webrtc_data_channel *	data_channel,
		crypto_context_t *	crypto_ctx
	)

Definition at line 374 of file webrtc/transport.c.

                                                                             {
  if (!peer_conn || !data_channel) {
    SET_ERRNO(ERROR_INVALID_PARAM, "peer_conn and data_channel are required");
    return NULL;
  }
 
  // Allocate transport structure
  acip_transport_t *transport = SAFE_MALLOC(sizeof(acip_transport_t), acip_transport_t *);
  if (!transport) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate WebRTC transport");
    return NULL;
  }
 
  // Allocate WebRTC-specific data
  webrtc_transport_data_t *wrtc_data = SAFE_MALLOC(sizeof(webrtc_transport_data_t), webrtc_transport_data_t *);
  if (!wrtc_data) {
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate WebRTC transport data");
    return NULL;
  }
 
  // Create receive queue
  wrtc_data->recv_queue = ringbuffer_create(sizeof(webrtc_recv_msg_t), WEBRTC_RECV_QUEUE_SIZE);
  if (!wrtc_data->recv_queue) {
    SAFE_FREE(wrtc_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_MEMORY, "Failed to create receive queue");
    return NULL;
  }
 
  // Initialize synchronization primitives
  if (mutex_init(&wrtc_data->queue_mutex) != 0) {
    ringbuffer_destroy(wrtc_data->recv_queue);
    SAFE_FREE(wrtc_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_INTERNAL, "Failed to initialize queue mutex");
    return NULL;
  }
 
  if (cond_init(&wrtc_data->queue_cond) != 0) {
    mutex_destroy(&wrtc_data->queue_mutex);
    ringbuffer_destroy(wrtc_data->recv_queue);
    SAFE_FREE(wrtc_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_INTERNAL, "Failed to initialize queue condition variable");
    return NULL;
  }
 
  if (mutex_init(&wrtc_data->state_mutex) != 0) {
    cond_destroy(&wrtc_data->queue_cond);
    mutex_destroy(&wrtc_data->queue_mutex);
    ringbuffer_destroy(wrtc_data->recv_queue);
    SAFE_FREE(wrtc_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_INTERNAL, "Failed to initialize state mutex");
    return NULL;
  }
 
  // Initialize WebRTC data
  wrtc_data->peer_conn = peer_conn;
  wrtc_data->data_channel = data_channel;
  wrtc_data->is_connected = false; // Will be set to true in on_open callback
 
  // Register DataChannel callbacks
  webrtc_datachannel_callbacks_t callbacks = {
      .on_open = webrtc_on_open,
      .on_close = webrtc_on_close,
      .on_error = webrtc_on_error,
      .on_message = webrtc_on_message,
      .user_data = wrtc_data,
  };
 
  asciichat_error_t result = webrtc_datachannel_set_callbacks(data_channel, &callbacks);
  if (result != ASCIICHAT_OK) {
    mutex_destroy(&wrtc_data->state_mutex);
    cond_destroy(&wrtc_data->queue_cond);
    mutex_destroy(&wrtc_data->queue_mutex);
    ringbuffer_destroy(wrtc_data->recv_queue);
    SAFE_FREE(wrtc_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_INTERNAL, "Failed to set DataChannel callbacks");
    return NULL;
  }
 
  // Initialize transport
  transport->methods = &webrtc_methods;
  transport->crypto_ctx = crypto_ctx;
  transport->impl_data = wrtc_data;
 
  log_info("Created WebRTC transport (crypto: %s)", crypto_ctx ? "enabled" : "disabled");
 
  return transport;
}

References ASCIICHAT_OK, cond_destroy(), cond_init(), acip_transport::crypto_ctx, webrtc_transport_data_t::data_channel, ERROR_INTERNAL, ERROR_INVALID_PARAM, ERROR_MEMORY, acip_transport::impl_data, webrtc_transport_data_t::is_connected, log_info, acip_transport::methods, mutex_destroy(), mutex_init(), webrtc_datachannel_callbacks_t::on_open, webrtc_transport_data_t::peer_conn, webrtc_transport_data_t::queue_cond, webrtc_transport_data_t::queue_mutex, webrtc_transport_data_t::recv_queue, ringbuffer_create(), ringbuffer_destroy(), SAFE_FREE, SAFE_MALLOC, SET_ERRNO, webrtc_transport_data_t::state_mutex, webrtc_datachannel_set_callbacks(), and WEBRTC_RECV_QUEUE_SIZE.

acip_websocket_transport_create()

acip_transport_t * acip_websocket_transport_create	(	socket_t	sockfd,
		crypto_context_t *	crypto_ctx
	)

Create WebSocket transport from existing socket.

Parameters

sockfd	Connected socket descriptor (after WebSocket handshake)
crypto_ctx	Optional crypto context (may be NULL)

Returns

Transport instance or NULL on error

Note

Socket must have completed WebSocket handshake

Caller retains socket ownership

Definition at line 32 of file websocket/transport.c.

                                                                                                 {
  (void)sockfd;
  (void)crypto_ctx;
 
  log_error("WebSocket transport not yet implemented");
  SET_ERRNO(ERROR_INTERNAL, "WebSocket transport is not yet implemented");
 
  return NULL;
}

References ERROR_INTERNAL, log_error, and SET_ERRNO.