handlers.h File Reference

ACIP protocol packet handlers (transport-agnostic). More...

Go to the source code of this file.

Data Structures
struct	acip_client_callbacks_t
	Client-side packet handler callbacks. More...
struct	acip_server_callbacks_t
	Server-side packet handler callbacks. More...

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.
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 (transport-agnostic).

Provides handler functions for all ACIP packet types (6000-6199). Handlers are transport-agnostic - they work with any acip_transport_t.

DESIGN PATTERN:

Handlers use callback pattern to decouple protocol logic from application logic. Applications register callbacks for events they care about.

Example usage:

// Define application callbacks
void my_on_ascii_frame(const ascii_frame_packet_t *frame, const void *data, size_t len, void *ctx) {
  // Render frame to terminal
}
 
// Register callbacks
acip_client_callbacks_t callbacks = {
  .on_ascii_frame = my_on_ascii_frame,
  .app_ctx = my_app_state
};
 
// Process incoming packet
acip_handle_client_packet(transport, type, payload, payload_len, &callbacks);

Author

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

Date

January 2026

Definition in file handlers.h.

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().