client.h File Reference

ACIP client-side protocol API. More...

Go to the source code of this file.

Functions
asciichat_error_t	acip_client_receive_and_dispatch (acip_transport_t *transport, const acip_client_callbacks_t *callbacks)
	Receive packet from server and dispatch to callbacks.
asciichat_error_t	acip_send_image_frame (acip_transport_t *transport, const void *pixel_data, uint32_t width, uint32_t height, uint32_t pixel_format)
	Send image frame to server (client → server)
asciichat_error_t	acip_send_image_frame_h265 (acip_transport_t *transport, h265_encoder_t *encoder, const void *pixel_data, uint32_t width, uint32_t height)
	Send H.265-encoded video frame to server (client → server)
asciichat_error_t	acip_send_client_join (acip_transport_t *transport, uint8_t capabilities)
	Announce client join to server (client → server)
asciichat_error_t	acip_send_client_leave (acip_transport_t *transport)
	Notify server of client leaving (client → server)
asciichat_error_t	acip_send_stream_start (acip_transport_t *transport, uint8_t stream_types)
	Request to start media streaming (client → server)
asciichat_error_t	acip_send_stream_stop (acip_transport_t *transport, uint8_t stream_types)
	Request to stop media streaming (client → server)
asciichat_error_t	acip_send_capabilities (acip_transport_t *transport, const void *cap_data, size_t cap_len)
	Send terminal capabilities to server (client → server)
asciichat_error_t	acip_send_protocol_version (acip_transport_t *transport, const protocol_version_packet_t *version)
	Send protocol version to server (client → server)

Detailed Description

ACIP client-side protocol API.

Client-side API for ascii-chat protocol. Provides functions for:

• Receiving and dispatching packets from server
• Sending image frames to server
• Sending client control messages (join, leave, stream control)
• Sending capabilities and protocol version

Author

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

Date

January 2026

Definition in file include/ascii-chat/network/acip/client.h.

Function Documentation

acip_client_receive_and_dispatch()

asciichat_error_t acip_client_receive_and_dispatch	(	acip_transport_t *	transport,
		const acip_client_callbacks_t *	callbacks
	)

Receive packet from server and dispatch to callbacks.

High-level receive function for client side. Receives a single packet from the transport, handles decryption, and dispatches to appropriate callback handler.

Parameters

transport	Transport instance
callbacks	Callback structure for handling received packets

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 30 of file lib/network/acip/client.c.

                                                                                             {
  if (!transport || !callbacks) {
    log_error("[ACIP_RECV] ❌ INVALID_PARAMS: transport=%p, callbacks=%p", (void *)transport, (void *)callbacks);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or callbacks");
  }
 
  log_debug("[ACIP_RECV] 📥 RECV_START: transport=%p, checking connection state", (void *)transport);
 
  // Check if transport is connected
  if (!transport->methods->is_connected(transport)) {
    log_error("[ACIP_RECV] ❌ NOT_CONNECTED: transport not ready for receive");
    return SET_ERRNO(ERROR_NETWORK, "Transport not connected");
  }
 
  log_debug("[ACIP_RECV] ✅ CONNECTED: transport ready, checking transport type");
 
  packet_envelope_t envelope;
  bool enforce_encryption = (transport->crypto_ctx != NULL);
  log_debug("[ACIP_RECV] 🔐 CRYPTO_MODE: enforce_encryption=%s", enforce_encryption ? "yes" : "no");
 
  socket_t sock = transport->methods->get_socket(transport);
  log_debug("[ACIP_RECV] 🔌 TRANSPORT_SOCKET: socket=%d (INVALID=%d)", sock, INVALID_SOCKET_VALUE);
 
  void *packet_data = NULL;
  void *allocated_buffer = NULL;
  size_t packet_len = 0;
 
  log_debug("[ACIP_RECV] 📥 RECV_CALL: using transport->methods->recv()");
  asciichat_error_t recv_result = acip_transport_recv(transport, &packet_data, &packet_len, &allocated_buffer);
  log_debug("[ACIP_RECV] 📥 RECV_RESULT: error=%d, packet_len=%zu, data=%p, alloc=%p", recv_result, packet_len,
           packet_data, allocated_buffer);
 
  if (recv_result != ASCIICHAT_OK) {
    if (recv_result == ERROR_NETWORK_TIMEOUT) {
      log_debug("[ACIP_RECV] Receive timed out while waiting for signaling data");
    } else {
      log_error("[ACIP_RECV] ❌ RECV_FAILED: error code %d", recv_result);
    }
    return recv_result;
  }
 
  // Parse packet header
  log_debug("[ACIP_RECV] HEADER_CHECK: packet_len=%zu, header_size=%zu", packet_len, sizeof(packet_header_t));
  if (packet_len < sizeof(packet_header_t)) {
    log_error("[ACIP_RECV] ❌ HEADER_TOO_SMALL: %zu < %zu", packet_len, sizeof(packet_header_t));
    buffer_pool_free(NULL, allocated_buffer, packet_len);
    return SET_ERRNO(ERROR_NETWORK, "Packet too small: %zu < %zu", packet_len, sizeof(packet_header_t));
  }
 
  const packet_header_t *header = (const packet_header_t *)packet_data;
  envelope.type = NET_TO_HOST_U16(header->type);
  envelope.len = NET_TO_HOST_U32(header->length);
  envelope.data = (uint8_t *)packet_data + sizeof(packet_header_t);
  envelope.allocated_buffer = allocated_buffer;
  envelope.allocated_size = packet_len;
  envelope.was_encrypted = false;
 
  log_debug("[ACIP_RECV] HEADER_PARSED: type=%u (0x%04x), len=%u, total_size=%zu", envelope.type, envelope.type,
           envelope.len, packet_len);
 
  log_dev_every(4500 * US_PER_MS_INT, "ACIP received packet: type=%u, len=%u, total_size=%zu", envelope.type,
                envelope.len, packet_len);
 
  // Validate packet length
  log_debug("[ACIP_RECV] LENGTH_VALIDATION: payload_size=%u vs actual=%zu", envelope.len,
            packet_len - sizeof(packet_header_t));
  if (envelope.len != packet_len - sizeof(packet_header_t)) {
    log_error("[ACIP_RECV] ❌ LENGTH_MISMATCH: header=%u, actual=%zu", envelope.len,
              packet_len - sizeof(packet_header_t));
    buffer_pool_free(NULL, allocated_buffer, packet_len);
    return SET_ERRNO(ERROR_NETWORK, "Packet length mismatch: header says %u, actual %zu", envelope.len,
                     packet_len - sizeof(packet_header_t));
  }
 
  // Handle PACKET_TYPE_ENCRYPTED from server (decrypt and extract inner packet)
  if (envelope.type == PACKET_TYPE_ENCRYPTED) {
    log_debug("[ACIP_RECV] 🔐 ENCRYPTED_PACKET: decrypting PACKET_TYPE_ENCRYPTED (len=%u)", envelope.len);
    asciichat_error_t decrypt_result = packet_decrypt_envelope(&envelope, transport->crypto_ctx);
    if (decrypt_result != ASCIICHAT_OK) {
      log_error("[ACIP_RECV] ❌ DECRYPT_FAILED: %d", decrypt_result);
      buffer_pool_free(NULL, envelope.allocated_buffer, envelope.allocated_size);
      return decrypt_result;
    }
  }
 
  // Dispatch packet to appropriate ACIP handler
  log_debug("[ACIP_RECV] 🎯 DISPATCH_START: type=%u (0x%04x), data_len=%u, callbacks=%p", envelope.type, envelope.type,
           envelope.len, (void *)callbacks);
  asciichat_error_t dispatch_result =
      acip_handle_client_packet(transport, envelope.type, envelope.data, envelope.len, callbacks);
 
  if (dispatch_result != ASCIICHAT_OK) {
    log_error("[ACIP_RECV] ❌ DISPATCH_FAILED: type=%u, error=%d", envelope.type, dispatch_result);
  } else {
    log_debug("[ACIP_RECV] ✅ DISPATCH_OK: type=%u (0x%04x) handled by callbacks", envelope.type, envelope.type);
  }
 
  // Always free the allocated buffer (even if handler failed)
  log_debug("[ACIP_RECV] 🗑️  CLEANUP: freeing buffer %p (size=%zu)", envelope.allocated_buffer,
            envelope.allocated_size);
  if (envelope.allocated_buffer) {
    buffer_pool_free(NULL, envelope.allocated_buffer, envelope.allocated_size);
  }
 
  log_debug("[ACIP_RECV] ✅ RECV_COMPLETE: type=%u, result=%d", envelope.type,
            dispatch_result != ASCIICHAT_OK ? -1 : 0);
 
  // Return handler result
  return dispatch_result;
}

References acip_handle_client_packet(), packet_envelope_t::allocated_buffer, packet_envelope_t::allocated_size, ASCIICHAT_OK, buffer_pool_free(), acip_transport::crypto_ctx, packet_envelope_t::data, ERROR_INVALID_PARAM, ERROR_NETWORK, ERROR_NETWORK_TIMEOUT, ERROR_NOT_SUPPORTED, acip_transport_methods_t::get_socket, INVALID_SOCKET_VALUE, acip_transport_methods_t::is_connected, packet_envelope_t::len, packet_header_t::length, log_debug, log_dev_every, log_error, acip_transport::methods, NET_TO_HOST_U16, NET_TO_HOST_U32, packet_decrypt_envelope(), PACKET_TYPE_ENCRYPTED, SET_ERRNO, packet_header_t::type, packet_envelope_t::type, US_PER_MS_INT, and packet_envelope_t::was_encrypted.

acip_send_capabilities()

asciichat_error_t acip_send_capabilities	(	acip_transport_t *	transport,
		const void *	cap_data,
		size_t	cap_len
	)

Send terminal capabilities to server (client → server)

Reports client's terminal capabilities (color support, dimensions, etc.)

Parameters

transport	Transport instance
cap_data	Capability data buffer
cap_len	Capability data length

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 306 of file lib/network/acip/client.c.

                                                                                                            {
  if (!transport || !cap_data) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or cap_data");
  }
 
  return packet_send_via_transport(transport, PACKET_TYPE_CLIENT_CAPABILITIES, cap_data, cap_len, 0);
}

References ERROR_INVALID_PARAM, packet_send_via_transport(), PACKET_TYPE_CLIENT_CAPABILITIES, and SET_ERRNO.

acip_send_client_join()

asciichat_error_t acip_send_client_join	(	acip_transport_t *	transport,
		uint8_t	capabilities
	)

Announce client join to server (client → server)

Notifies server that client is ready to participate in session.

Parameters

transport	Transport instance
capabilities	Client capability bitmask (video, audio, etc.)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 266 of file lib/network/acip/client.c.

                                                                                           {
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport");
  }
 
  client_info_packet_t join = {0};
  SAFE_STRNCPY(join.display_name, "ascii-chat", sizeof(join.display_name));
  join.capabilities = HOST_TO_NET_U32(capabilities);
  return packet_send_via_transport(transport, PACKET_TYPE_CLIENT_JOIN, &join, sizeof(join), 0);
}

References client_info_packet_t::capabilities, client_info_packet_t::display_name, ERROR_INVALID_PARAM, HOST_TO_NET_U32, packet_send_via_transport(), PACKET_TYPE_CLIENT_JOIN, SAFE_STRNCPY, and SET_ERRNO.

acip_send_client_leave()

asciichat_error_t acip_send_client_leave

(

acip_transport_t *

transport

)

Notify server of client leaving (client → server)

Clean disconnect notification to server.

Parameters

transport

Transport instance

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 277 of file lib/network/acip/client.c.

                                                                      {
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport");
  }
 
  // Leave has no payload
  return packet_send_via_transport(transport, PACKET_TYPE_CLIENT_LEAVE, NULL, 0, 0);
}

References ERROR_INVALID_PARAM, packet_send_via_transport(), PACKET_TYPE_CLIENT_LEAVE, and SET_ERRNO.

acip_send_image_frame()

asciichat_error_t acip_send_image_frame	(	acip_transport_t *	transport,
		const void *	pixel_data,
		uint32_t	width,
		uint32_t	height,
		uint32_t	pixel_format
	)

Send image frame to server (client → server)

Sends webcam video frame as RGB24 pixel data.

Parameters

transport	Transport instance
pixel_data	RGB24 pixel data (width * height * 3 bytes)
width	Frame width in pixels
height	Frame height in pixels
pixel_format	Pixel format (e.g., RGB24)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 146 of file lib/network/acip/client.c.

                                                                                {
  log_dev("★ ACIP_SEND_IMAGE_FRAME: Called with %ux%u, transport=%p, pixel_data=%p", width, height, (void *)transport,
          pixel_data);
 
  if (!transport || !pixel_data) {
    log_dev("★ ACIP_SEND_IMAGE_FRAME: Invalid params");
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or pixel_data");
  }
 
  // Calculate pixel data size (3 bytes per pixel for RGB24)
  size_t pixel_size = (size_t)width * height * 3;
  log_dev("★ ACIP_SEND_IMAGE_FRAME: pixel_size=%zu", pixel_size);
 
  // Create image frame packet header
  image_frame_packet_t header;
  header.width = HOST_TO_NET_U32(width);
  header.height = HOST_TO_NET_U32(height);
  header.pixel_format = HOST_TO_NET_U32(pixel_format);
  header.compressed_size = 0;
  header.checksum = 0;
  header.timestamp = 0;
 
  // Calculate total size
  size_t total_size;
  if (checked_size_add(sizeof(header), pixel_size, &total_size) != ASCIICHAT_OK) {
    log_dev("★ ACIP_SEND_IMAGE_FRAME: Overflow in size calculation");
    return SET_ERRNO(ERROR_INVALID_PARAM, "Packet size overflow");
  }
 
  log_dev("★ ACIP_SEND_IMAGE_FRAME: total_size=%zu, allocating buffer", total_size);
 
  // Allocate buffer
  uint8_t *buffer = buffer_pool_alloc(NULL, total_size);
  if (!buffer) {
    log_dev("★ ACIP_SEND_IMAGE_FRAME: Failed to allocate %zu bytes", total_size);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer: %zu bytes", total_size);
  }
 
  // Build packet
  memcpy(buffer, &header, sizeof(header));
  memcpy(buffer + sizeof(header), pixel_data, pixel_size);
 
  log_dev("★ ACIP_SEND_IMAGE_FRAME: About to send packet");
  // Send via transport
  asciichat_error_t result = packet_send_via_transport(transport, PACKET_TYPE_IMAGE_FRAME, buffer, total_size, 0);
 
  log_dev("★ ACIP_SEND_IMAGE_FRAME: packet_send_via_transport returned %d", result);
 
  buffer_pool_free(NULL, buffer, total_size);
  return result;
}

References ASCIICHAT_OK, buffer_pool_alloc(), buffer_pool_free(), image_frame_packet_t::checksum, image_frame_packet_t::compressed_size, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NOT_SUPPORTED, image_frame_packet_t::height, HOST_TO_NET_U32, log_dev, packet_send_via_transport(), PACKET_TYPE_IMAGE_FRAME, image_frame_packet_t::pixel_format, SET_ERRNO, image_frame_packet_t::timestamp, and image_frame_packet_t::width.

Referenced by threaded_send_image_frame().

acip_send_image_frame_h265()

asciichat_error_t acip_send_image_frame_h265	(	acip_transport_t *	transport,
		h265_encoder_t *	encoder,
		const void *	pixel_data,
		uint32_t	width,
		uint32_t	height
	)

Send H.265-encoded video frame to server (client → server)

Encodes RGB frame to H.265 and transmits as PACKET_TYPE_IMAGE_FRAME_H265. Much more efficient than raw pixel transmission for bandwidth-limited connections.

PACKET FORMAT: [flags: u8][width: u16][height: u16][h265_data...]

• flags: H.265 encoding flags (keyframe, size_change)
• width: Frame width in pixels
• height: Frame height in pixels
• h265_data: x265-encoded frame payload

Parameters

transport	Transport instance
encoder	H.265 encoder (initialized with initial frame dimensions)
pixel_data	RGB pixel data from camera/source
width	Frame width in pixels
height	Frame height in pixels

Returns

ASCIICHAT_OK on success, error code on failure

Note

Encoder is responsible for RGB → YUV420 conversion internally

Encoder handles frame dimension changes transparently (reconfigures on size change)

Send H.265-encoded video frame to server (client → server)

Encodes frame using H.265 codec and sends as PACKET_TYPE_IMAGE_FRAME_H265. Packet format: [flags:u8][width:u16][height:u16][h265_encoded_data...]

Parameters

transport	ACIP transport
encoder	H.265 encoder instance
pixel_data	RGB pixel data from capture
width	Frame width in pixels
height	Frame height in pixels

Returns

Error code

Definition at line 212 of file lib/network/acip/client.c.

                                                                                                      {
  if (!transport || !encoder || !pixel_data) {
    log_debug("★ ACIP_SEND_IMAGE_FRAME_H265: Invalid params");
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport, encoder, or pixel_data");
  }
 
  // Allocate output buffer for H.265 encoding
  // H.265 can produce output larger than input due to codec overhead
  // Use 2x multiplier to account for worst-case frame content
  size_t output_buffer_size = 5 + (width * height * 2);
  log_dev("[ACIP_SEND_H265_1] About to allocate output buffer (%zu bytes)", output_buffer_size);
  uint8_t *output_buffer = buffer_pool_alloc(NULL, output_buffer_size);
  log_dev("[ACIP_SEND_H265_2] ✅ Allocated output buffer");
  if (!output_buffer) {
    log_debug("★ ACIP_SEND_IMAGE_FRAME_H265: Failed to allocate output buffer");
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate H.265 output buffer: %zu bytes", output_buffer_size);
  }
 
  // Encode frame
  size_t encoded_size = output_buffer_size - 5;
  log_dev("[ACIP_SEND_H265_3] Calling h265_encode");
  asciichat_error_t encode_result = h265_encode(encoder, (uint16_t)width, (uint16_t)height, (const uint8_t *)pixel_data,
                                                output_buffer + 5, &encoded_size);
  log_dev("[ACIP_SEND_H265_4] h265_encode returned: %d, encoded_size=%zu", encode_result, encoded_size);
 
  if (encode_result != ASCIICHAT_OK) {
    log_error("H.265 encoding failed: %s", asciichat_error_string(encode_result));
    buffer_pool_free(NULL, output_buffer, output_buffer_size);
    return encode_result;
  }
 
  // Prepare H.265 packet: [flags:u8][width:u16][height:u16][h265_data...]
  output_buffer[0] = 0; // flags: no flags set by default
  output_buffer[1] = (width >> 8) & 0xFF;
  output_buffer[2] = width & 0xFF;
  output_buffer[3] = (height >> 8) & 0xFF;
  output_buffer[4] = height & 0xFF;
 
  size_t total_size = 5 + encoded_size;
 
  log_debug("★ ACIP_SEND_IMAGE_FRAME_H265: Encoded %ux%u → %zu bytes", width, height, total_size);
 
  // Send via transport
  log_dev("[ACIP_SEND_H265_5] Calling packet_send_via_transport with %zu bytes", total_size);
  asciichat_error_t result =
      packet_send_via_transport(transport, PACKET_TYPE_IMAGE_FRAME_H265, output_buffer, total_size, 0);
  log_dev("[ACIP_SEND_H265_6] packet_send_via_transport returned: %d", result);
 
  buffer_pool_free(NULL, output_buffer, output_buffer_size);
  log_dev("[ACIP_SEND_H265_7] ✅ Freed output buffer, returning from acip_send_image_frame_h265");
  return result;
}

References ASCIICHAT_OK, buffer_pool_alloc(), buffer_pool_free(), ERROR_INVALID_PARAM, ERROR_MEMORY, h265_encode(), log_debug, log_dev, log_error, packet_send_via_transport(), PACKET_TYPE_IMAGE_FRAME_H265, and SET_ERRNO.

acip_send_protocol_version()

asciichat_error_t acip_send_protocol_version	(	acip_transport_t *	transport,
		const protocol_version_packet_t *	version
	)

Send protocol version to server (client → server)

Negotiates protocol version with server.

Parameters

transport	Transport instance
version	Protocol version structure

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 314 of file lib/network/acip/client.c.

                                                                                                                    {
  if (!transport || !version) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or version");
  }
 
  return packet_send_via_transport(transport, PACKET_TYPE_PROTOCOL_VERSION, version, sizeof(*version), 0);
}

References ERROR_INVALID_PARAM, packet_send_via_transport(), PACKET_TYPE_PROTOCOL_VERSION, and SET_ERRNO.

acip_send_stream_start()

asciichat_error_t acip_send_stream_start	(	acip_transport_t *	transport,
		uint8_t	stream_types
	)

Request to start media streaming (client → server)

Notifies server that client wants to start sending video/audio.

Parameters

transport	Transport instance
stream_types	Stream type bitmask (video, audio, etc.)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 286 of file lib/network/acip/client.c.

                                                                                            {
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport");
  }
 
  // Server expects uint32_t (4 bytes), not uint8_t
  uint32_t stream_types_net = HOST_TO_NET_U32((uint32_t)stream_types);
  return packet_send_via_transport(transport, PACKET_TYPE_STREAM_START, &stream_types_net, sizeof(stream_types_net), 0);
}

References ERROR_INVALID_PARAM, HOST_TO_NET_U32, packet_send_via_transport(), PACKET_TYPE_STREAM_START, and SET_ERRNO.

acip_send_stream_stop()

asciichat_error_t acip_send_stream_stop	(	acip_transport_t *	transport,
		uint8_t	stream_types
	)

Request to stop media streaming (client → server)

Notifies server that client wants to stop sending video/audio.

Parameters

transport	Transport instance
stream_types	Stream type bitmask (video, audio, etc.)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 296 of file lib/network/acip/client.c.

                                                                                           {
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport");
  }
 
  // Server expects uint32_t (4 bytes), not uint8_t
  uint32_t stream_types_net = HOST_TO_NET_U32((uint32_t)stream_types);
  return packet_send_via_transport(transport, PACKET_TYPE_STREAM_STOP, &stream_types_net, sizeof(stream_types_net), 0);
}

References ERROR_INVALID_PARAM, HOST_TO_NET_U32, packet_send_via_transport(), PACKET_TYPE_STREAM_STOP, and SET_ERRNO.