handlers.c File Reference

ACIP protocol packet handlers implementation. More...

Go to the source code of this file.

Data Structures
struct	handler_hash_entry_t
	Hash table entry for packet type to handler mapping. More...

Macros
#define	NETWORK_ACIP_HANDLERS_MSG_BUFFER_SIZE   512
#define	NETWORK_ACIP_HANDLERS_HEX_BUFFER_SIZE   512
#define	HANDLER_HASH_SIZE   32
#define	CLIENT_HANDLER_COUNT   20
#define	SERVER_HANDLER_COUNT   21
#define	HANDLER_HASH(type)

Typedefs
typedef asciichat_error_t(*	acip_client_handler_func_t) (const void *payload, size_t payload_len, const acip_client_callbacks_t *callbacks)
typedef asciichat_error_t(*	acip_server_handler_func_t) (const void *payload, size_t payload_len, void *client_ctx, const acip_server_callbacks_t *callbacks)

Functions
asciichat_error_t	acip_handle_client_packet (acip_transport_t *transport, packet_type_t type, const void *payload, size_t payload_len, const acip_client_callbacks_t *callbacks)
	Client-side packet handler callbacks.
const char *	acip_packet_type_name (uint16_t type)
	Get human-readable name for packet type.
asciichat_error_t	acip_handle_server_packet (acip_transport_t *transport, packet_type_t type, const void *payload, size_t payload_len, void *client_ctx, const acip_server_callbacks_t *callbacks)
	Handle incoming packet on server side.

Detailed Description

ACIP protocol packet handlers implementation.

Implements packet dispatching for both client and server sides. Uses O(1) array-based dispatch instead of O(n) switch statements. Parses packet payloads and dispatches to registered callbacks.

Author

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

Date

January 2026

Definition in file handlers.c.

Macro Definition Documentation

CLIENT_HANDLER_COUNT

#define CLIENT_HANDLER_COUNT   20

Definition at line 47 of file handlers.c.

HANDLER_HASH

#define HANDLER_HASH

(

type

)

Value:

((type) % HANDLER_HASH_SIZE)

Definition at line 60 of file handlers.c.

HANDLER_HASH_SIZE

#define HANDLER_HASH_SIZE   32

Definition at line 46 of file handlers.c.

NETWORK_ACIP_HANDLERS_HEX_BUFFER_SIZE

#define NETWORK_ACIP_HANDLERS_HEX_BUFFER_SIZE   512

Definition at line 15 of file handlers.c.

NETWORK_ACIP_HANDLERS_MSG_BUFFER_SIZE

#define NETWORK_ACIP_HANDLERS_MSG_BUFFER_SIZE   512

Definition at line 14 of file handlers.c.

SERVER_HANDLER_COUNT

#define SERVER_HANDLER_COUNT   21

Definition at line 48 of file handlers.c.

Typedef Documentation

acip_client_handler_func_t

typedef asciichat_error_t(* acip_client_handler_func_t) (const void *payload, size_t payload_len, const acip_client_callbacks_t *callbacks)

Definition at line 34 of file handlers.c.

acip_server_handler_func_t

typedef asciichat_error_t(* acip_server_handler_func_t) (const void *payload, size_t payload_len, void *client_ctx, const acip_server_callbacks_t *callbacks)

Definition at line 37 of file handlers.c.

Function Documentation

acip_handle_client_packet()

asciichat_error_t acip_handle_client_packet	(	acip_transport_t *	transport,
		packet_type_t	type,
		const void *	payload,
		size_t	payload_len,
		const acip_client_callbacks_t *	callbacks )

Client-side packet handler callbacks.

Server-side packet handler callbacks

Handle incoming packet on client side

Dispatches packet to appropriate callback based on type. Transport-agnostic - works with TCP, WebSocket, etc.

Parameters

transport	Transport instance
type	Packet type
payload	Packet payload
payload_len	Payload length
callbacks	Application callbacks

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 203 of file handlers.c.

                                                                                                          {
  stats_runtime_packet(transport ? transport->stats_peer : NULL, type, payload_len, false, true);
  if (!transport || !callbacks) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or callbacks");
  }
  (void)transport;
 
  // ACDS broadcasts participant lifecycle notifications to peers. The generic
  // client callback set does not expose them, so ignore them while keeping the
  // signaling receive loop alive for subsequent SDP and ICE packets.
  if (type == PACKET_TYPE_ACIP_PARTICIPANT_JOINED || type == PACKET_TYPE_ACIP_PARTICIPANT_LEFT) {
    return ASCIICHAT_OK;
  }
 
  // O(1) dispatch via hash table lookup
  int idx = handler_hash_lookup(g_client_handler_hash, type);
  if (idx < 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Unhandled client packet type: %d", type);
  }
 
  return g_client_handlers[idx](payload, payload_len, callbacks);
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, PACKET_TYPE_ACIP_PARTICIPANT_JOINED, PACKET_TYPE_ACIP_PARTICIPANT_LEFT, SET_ERRNO, acip_transport::stats_peer, and stats_runtime_packet().

Referenced by acip_client_receive_and_dispatch(), and session_protocol_dispatch().

acip_handle_server_packet()

asciichat_error_t acip_handle_server_packet	(	acip_transport_t *	transport,
		packet_type_t	type,
		const void *	payload,
		size_t	payload_len,
		void *	client_ctx,
		const acip_server_callbacks_t *	callbacks )

Handle incoming packet on server side.

Dispatches packet to appropriate callback based on type. Transport-agnostic - works with TCP, WebSocket, etc.

Parameters

transport	Transport instance
type	Packet type
payload	Packet payload
payload_len	Payload length
client_ctx	Per-client context (e.g., client_info_t*)
callbacks	Application callbacks

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 799 of file handlers.c.

                                                                                      {
  stats_runtime_packet(transport ? transport->stats_peer : NULL, type, payload_len, false, true);
  if (!transport || !callbacks) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or callbacks");
  }
  (void)transport;
 
  // DEBUG: Log all packet types received
  log_dev("ACIP_HANDLE: type=%d payload_len=%zu", type, payload_len);
 
  // O(1) dispatch via hash table lookup
  int idx = handler_hash_lookup(g_server_handler_hash, type);
  if (idx < 0) {
    log_error("ACIP_HANDLER_NOT_FOUND: No handler for packet type=%d (0x%04x, name=%s)", type, type,
              acip_packet_type_name(type));
    return SET_ERRNO(ERROR_INVALID_PARAM, "Unhandled server packet type: %d", type);
  }
 
  log_dev("HANDLER_DISPATCH: type=%d (%s), handler_idx=%d, payload=%zu bytes", type, acip_packet_type_name(type), idx,
          payload_len);
  asciichat_error_t result = g_server_handlers[idx](payload, payload_len, client_ctx, callbacks);
 
  if (result != ASCIICHAT_OK) {
    log_error("❌ [HANDLER_ERROR] Handler failed: type=%d (%s), result=%s", type, acip_packet_type_name(type),
              asciichat_error_format(NULL, result));
  } else {
    log_dev("HANDLER_COMPLETE: type=%d (%s), payload=%zu bytes", type, acip_packet_type_name(type), payload_len);
  }
 
  return result;
}

References acip_packet_type_name(), asciichat_error_format(), ASCIICHAT_OK, ERROR_INVALID_PARAM, log_dev, log_error, SET_ERRNO, acip_transport::stats_peer, and stats_runtime_packet().

Referenced by acip_server_receive_and_dispatch(), handle_image_frame_h264_packet(), and server_dispatch_packet().

acip_packet_type_name()

const char * acip_packet_type_name

(

uint16_t

type

)

Get human-readable name for packet type.

Parameters

type	Packet type from packet_type_t enum

Returns

String name or "UNKNOWN"

Definition at line 648 of file handlers.c.

                                                 {
  switch (type) {
  case PACKET_TYPE_PROTOCOL_VERSION:
    return "PROTOCOL_VERSION";
  case PACKET_TYPE_CRYPTO_CLIENT_HELLO:
    return "CRYPTO_CLIENT_HELLO";
  case PACKET_TYPE_CRYPTO_CAPABILITIES:
    return "CRYPTO_CAPABILITIES";
  case PACKET_TYPE_CRYPTO_PARAMETERS:
    return "CRYPTO_PARAMETERS";
  case PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT:
    return "CRYPTO_KEY_EXCHANGE_INIT";
  case PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP:
    return "CRYPTO_KEY_EXCHANGE_RESP";
  case PACKET_TYPE_CRYPTO_AUTH_CHALLENGE:
    return "CRYPTO_AUTH_CHALLENGE";
  case PACKET_TYPE_CRYPTO_AUTH_RESPONSE:
    return "CRYPTO_AUTH_RESPONSE";
  case PACKET_TYPE_CRYPTO_AUTH_FAILED:
    return "CRYPTO_AUTH_FAILED";
  case PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP:
    return "CRYPTO_SERVER_AUTH_RESP";
  case PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE:
    return "CRYPTO_HANDSHAKE_COMPLETE";
  case PACKET_TYPE_CRYPTO_NO_ENCRYPTION:
    return "CRYPTO_NO_ENCRYPTION";
  case PACKET_TYPE_ENCRYPTED:
    return "ENCRYPTED";
  case PACKET_TYPE_CRYPTO_REKEY_REQUEST:
    return "CRYPTO_REKEY_REQUEST";
  case PACKET_TYPE_CRYPTO_REKEY_RESPONSE:
    return "CRYPTO_REKEY_RESPONSE";
  case PACKET_TYPE_CRYPTO_REKEY_COMPLETE:
    return "CRYPTO_REKEY_COMPLETE";
  case PACKET_TYPE_SIZE_MESSAGE:
    return "SIZE_MESSAGE";
  case PACKET_TYPE_AUDIO_MESSAGE:
    return "AUDIO_MESSAGE";
  case PACKET_TYPE_TEXT_MESSAGE:
    return "TEXT_MESSAGE";
  case PACKET_TYPE_ERROR_MESSAGE:
    return "ERROR_MESSAGE";
  case PACKET_TYPE_REMOTE_LOG:
    return "REMOTE_LOG";
  case PACKET_TYPE_ASCII_FRAME:
    return "ASCII_FRAME";
  case PACKET_TYPE_IMAGE_FRAME:
    return "IMAGE_FRAME";
  case PACKET_TYPE_IMAGE_FRAME_H265:
    return "IMAGE_FRAME_H265";
  case PACKET_TYPE_IMAGE_FRAME_H264:
    return "IMAGE_FRAME_H264";
  case PACKET_TYPE_AUDIO_BATCH:
    return "AUDIO_BATCH";
  case PACKET_TYPE_AUDIO_OPUS_BATCH:
    return "AUDIO_OPUS_BATCH";
  case PACKET_TYPE_CLIENT_CAPABILITIES:
    return "CLIENT_CAPABILITIES";
  case PACKET_TYPE_PING:
    return "PING";
  case PACKET_TYPE_PONG:
    return "PONG";
  case PACKET_TYPE_CLIENT_JOIN:
    return "CLIENT_JOIN";
  case PACKET_TYPE_CLIENT_LEAVE:
    return "CLIENT_LEAVE";
  case PACKET_TYPE_STREAM_START:
    return "STREAM_START";
  case PACKET_TYPE_STREAM_STOP:
    return "STREAM_STOP";
  case PACKET_TYPE_CLEAR_CONSOLE:
    return "CLEAR_CONSOLE";
  case PACKET_TYPE_SERVER_STATE:
    return "SERVER_STATE";
  case PACKET_TYPE_ACIP_SESSION_CREATE:
    return "ACIP_SESSION_CREATE";
  case PACKET_TYPE_ACIP_SESSION_CREATED:
    return "ACIP_SESSION_CREATED";
  case PACKET_TYPE_ACIP_SESSION_LOOKUP:
    return "ACIP_SESSION_LOOKUP";
  case PACKET_TYPE_ACIP_SESSION_INFO:
    return "ACIP_SESSION_INFO";
  case PACKET_TYPE_ACIP_SESSION_JOIN:
    return "ACIP_SESSION_JOIN";
  case PACKET_TYPE_ACIP_SESSION_JOINED:
    return "ACIP_SESSION_JOINED";
  case PACKET_TYPE_ACIP_SESSION_LEAVE:
    return "ACIP_SESSION_LEAVE";
  case PACKET_TYPE_ACIP_SESSION_END:
    return "ACIP_SESSION_END";
  case PACKET_TYPE_ACIP_SESSION_RECONNECT:
    return "ACIP_SESSION_RECONNECT";
  case PACKET_TYPE_ACIP_WEBRTC_SDP:
    return "ACIP_WEBRTC_SDP";
  case PACKET_TYPE_ACIP_WEBRTC_ICE:
    return "ACIP_WEBRTC_ICE";
  case PACKET_TYPE_ACIP_STRING_RESERVE:
    return "ACIP_STRING_RESERVE";
  case PACKET_TYPE_ACIP_STRING_RESERVED:
    return "ACIP_STRING_RESERVED";
  case PACKET_TYPE_ACIP_STRING_RENEW:
    return "ACIP_STRING_RENEW";
  case PACKET_TYPE_ACIP_STRING_RELEASE:
    return "ACIP_STRING_RELEASE";
  case PACKET_TYPE_ACIP_PARTICIPANT_LIST:
    return "ACIP_PARTICIPANT_LIST";
  case PACKET_TYPE_ACIP_RING_COLLECT:
    return "ACIP_RING_COLLECT";
  case PACKET_TYPE_ACIP_NETWORK_QUALITY:
    return "ACIP_NETWORK_QUALITY";
  case PACKET_TYPE_ACIP_HOST_ANNOUNCEMENT:
    return "ACIP_HOST_ANNOUNCEMENT";
  case PACKET_TYPE_ACIP_HOST_DESIGNATED:
    return "ACIP_HOST_DESIGNATED";
  case PACKET_TYPE_ACIP_SETTINGS_SYNC:
    return "ACIP_SETTINGS_SYNC";
  case PACKET_TYPE_ACIP_SETTINGS_ACK:
    return "ACIP_SETTINGS_ACK";
  case PACKET_TYPE_ACIP_HOST_LOST:
    return "ACIP_HOST_LOST";
  case PACKET_TYPE_ACIP_FUTURE_HOST_ELECTED:
    return "ACIP_FUTURE_HOST_ELECTED";
  case PACKET_TYPE_ACIP_PARTICIPANT_JOINED:
    return "ACIP_PARTICIPANT_JOINED";
  case PACKET_TYPE_ACIP_PARTICIPANT_LEFT:
    return "ACIP_PARTICIPANT_LEFT";
  case PACKET_TYPE_ACIP_BANDWIDTH_TEST:
    return "ACIP_BANDWIDTH_TEST";
  case PACKET_TYPE_ACIP_BANDWIDTH_RESULT:
    return "ACIP_BANDWIDTH_RESULT";
  case PACKET_TYPE_ACIP_BROADCAST_ACK:
    return "ACIP_BROADCAST_ACK";
  case PACKET_TYPE_RING_MEMBERS:
    return "RING_MEMBERS";
  case PACKET_TYPE_STATS_COLLECTION_START:
    return "STATS_COLLECTION_START";
  case PACKET_TYPE_STATS_UPDATE:
    return "STATS_UPDATE";
  case PACKET_TYPE_RING_ELECTION_RESULT:
    return "RING_ELECTION_RESULT";
  case PACKET_TYPE_STATS_ACK:
    return "STATS_ACK";
  case PACKET_TYPE_ACIP_DISCOVERY_PING:
    return "ACIP_DISCOVERY_PING";
  case PACKET_TYPE_ACIP_ERROR:
    return "ACIP_ERROR";
  default:
    return "UNKNOWN";
  }
}

References PACKET_TYPE_ACIP_BANDWIDTH_RESULT, PACKET_TYPE_ACIP_BANDWIDTH_TEST, PACKET_TYPE_ACIP_BROADCAST_ACK, PACKET_TYPE_ACIP_DISCOVERY_PING, PACKET_TYPE_ACIP_ERROR, PACKET_TYPE_ACIP_FUTURE_HOST_ELECTED, PACKET_TYPE_ACIP_HOST_ANNOUNCEMENT, PACKET_TYPE_ACIP_HOST_DESIGNATED, PACKET_TYPE_ACIP_HOST_LOST, PACKET_TYPE_ACIP_NETWORK_QUALITY, PACKET_TYPE_ACIP_PARTICIPANT_JOINED, PACKET_TYPE_ACIP_PARTICIPANT_LEFT, PACKET_TYPE_ACIP_PARTICIPANT_LIST, PACKET_TYPE_ACIP_RING_COLLECT, PACKET_TYPE_ACIP_SESSION_CREATE, PACKET_TYPE_ACIP_SESSION_CREATED, PACKET_TYPE_ACIP_SESSION_END, PACKET_TYPE_ACIP_SESSION_INFO, PACKET_TYPE_ACIP_SESSION_JOIN, PACKET_TYPE_ACIP_SESSION_JOINED, PACKET_TYPE_ACIP_SESSION_LEAVE, PACKET_TYPE_ACIP_SESSION_LOOKUP, PACKET_TYPE_ACIP_SESSION_RECONNECT, PACKET_TYPE_ACIP_SETTINGS_ACK, PACKET_TYPE_ACIP_SETTINGS_SYNC, PACKET_TYPE_ACIP_STRING_RELEASE, PACKET_TYPE_ACIP_STRING_RENEW, PACKET_TYPE_ACIP_STRING_RESERVE, PACKET_TYPE_ACIP_STRING_RESERVED, PACKET_TYPE_ACIP_WEBRTC_ICE, PACKET_TYPE_ACIP_WEBRTC_SDP, PACKET_TYPE_ASCII_FRAME, PACKET_TYPE_AUDIO_BATCH, PACKET_TYPE_AUDIO_MESSAGE, PACKET_TYPE_AUDIO_OPUS_BATCH, PACKET_TYPE_CLEAR_CONSOLE, PACKET_TYPE_CLIENT_CAPABILITIES, PACKET_TYPE_CLIENT_JOIN, PACKET_TYPE_CLIENT_LEAVE, PACKET_TYPE_CRYPTO_AUTH_CHALLENGE, PACKET_TYPE_CRYPTO_AUTH_FAILED, PACKET_TYPE_CRYPTO_AUTH_RESPONSE, PACKET_TYPE_CRYPTO_CAPABILITIES, PACKET_TYPE_CRYPTO_CLIENT_HELLO, PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP, PACKET_TYPE_CRYPTO_NO_ENCRYPTION, PACKET_TYPE_CRYPTO_PARAMETERS, PACKET_TYPE_CRYPTO_REKEY_COMPLETE, PACKET_TYPE_CRYPTO_REKEY_REQUEST, PACKET_TYPE_CRYPTO_REKEY_RESPONSE, PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP, PACKET_TYPE_ENCRYPTED, PACKET_TYPE_ERROR_MESSAGE, PACKET_TYPE_IMAGE_FRAME, PACKET_TYPE_IMAGE_FRAME_H264, PACKET_TYPE_IMAGE_FRAME_H265, PACKET_TYPE_PING, PACKET_TYPE_PONG, PACKET_TYPE_PROTOCOL_VERSION, PACKET_TYPE_REMOTE_LOG, PACKET_TYPE_RING_ELECTION_RESULT, PACKET_TYPE_RING_MEMBERS, PACKET_TYPE_SERVER_STATE, PACKET_TYPE_SIZE_MESSAGE, PACKET_TYPE_STATS_ACK, PACKET_TYPE_STATS_COLLECTION_START, PACKET_TYPE_STATS_UPDATE, PACKET_TYPE_STREAM_START, PACKET_TYPE_STREAM_STOP, and PACKET_TYPE_TEXT_MESSAGE.

Referenced by acip_handle_server_packet(), and ascii_otel_packet().