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_packet (acip_transport_t *transport, packet_envelope_t *envelope)
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_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 45 of file lib/network/acip/client.c.

                                                                                             {
  ASCII_OTEL_SCOPE(ACIP_CLIENT_RECEIVE_AND_DISPATCH);
  if (!callbacks)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing client packet callbacks");
  packet_envelope_t envelope = {0};
  asciichat_error_t result = acip_client_receive_packet(transport, &envelope);
  if (result == ASCIICHAT_OK)
    result = acip_handle_client_packet(transport, envelope.type, envelope.data, envelope.len, callbacks);
  if (envelope.allocated_buffer)
    buffer_release(envelope.allocated_buffer);
  return result;
}

References acip_client_receive_packet(), acip_handle_client_packet(), ASCII_OTEL_SCOPE, ASCIICHAT_OK, buffer_release, ERROR_INVALID_PARAM, and SET_ERRNO.

acip_client_receive_packet()

asciichat_error_t acip_client_receive_packet	(	acip_transport_t *	transport,
		packet_envelope_t *	envelope )

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

                                                                                                  {
  if (!transport || !out) {
    log_error("[ACIP_RECV] ❌ INVALID_PARAMS: transport=%p, output=%p", (void *)transport, (void *)out);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or packet output");
  }
 
  *out = (packet_envelope_t){0};
  if (!acip_transport_is_connected(transport) && !acip_transport_has_pending_data(transport))
    return SET_ERRNO(ERROR_NETWORK, "Transport not connected");
  return packet_receive_via_transport(transport, &out->type, &out->data, &out->len, &out->allocated_buffer);
}

References ERROR_INVALID_PARAM, ERROR_NETWORK, log_error, out, packet_receive_via_transport(), and SET_ERRNO.

Referenced by acip_client_receive_and_dispatch().

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 180 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_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 63 of file lib/network/acip/client.c.

                                                                                {
  ASCII_OTEL_SCOPE(ACIP_SEND_IMAGE_FRAME);
  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;
 
  socket_buffer_t slices[] = {{&header, sizeof(header)}, {pixel_data, pixel_size}};
  return packet_send_via_transportv(transport, PACKET_TYPE_IMAGE_FRAME, slices, 2, 0);
}

References ASCII_OTEL_SCOPE, ERROR_INVALID_PARAM, height, HOST_TO_NET_U32, log_dev, packet_send_via_transportv(), PACKET_TYPE_IMAGE_FRAME, SET_ERRNO, image_frame_packet_t::width, and 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 104 of file lib/network/acip/client.c.

                                                                                                      {
  ASCII_OTEL_SCOPE(ACIP_SEND_IMAGE_FRAME_H265);
  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_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);
  }
  defer(buffer_release(output_buffer));
 
  // Admission expiry can invalidate a previously accepted reference chain.
#ifndef __EMSCRIPTEN__
  if (acip_outbound_needs_keyframe(transport, PACKET_TYPE_IMAGE_FRAME_H265, 0))
    h265_encoder_request_keyframe(encoder);
#endif
  size_t encoded_size = output_buffer_size;
  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, &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_format(NULL, encode_result));
    return encode_result;
  }
 
  // h265_encode includes flags, dimensions, and the encoded picture already.
  size_t total_size = encoded_size;
  if (!total_size) {
    return ASCIICHAT_OK;
  }
 
  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);
 
  return result;
}

References acip_outbound_needs_keyframe(), ASCII_OTEL_SCOPE, asciichat_error_format(), ASCIICHAT_OK, buffer_alloc(), buffer_release, ERROR_INVALID_PARAM, ERROR_MEMORY, h265_encode(), h265_encoder_request_keyframe(), height, log_debug, log_dev, log_error, packet_send_via_transport(), PACKET_TYPE_IMAGE_FRAME_H265, SET_ERRNO, and width.

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 188 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 158 of file lib/network/acip/client.c.

                                                                                            {
  ASCII_OTEL_SCOPE(ACIP_SEND_STREAM_START);
  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 ASCII_OTEL_SCOPE, 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 169 of file lib/network/acip/client.c.

                                                                                           {
  ASCII_OTEL_SCOPE(ACIP_SEND_STREAM_STOP);
  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 ASCII_OTEL_SCOPE, ERROR_INVALID_PARAM, HOST_TO_NET_U32, packet_send_via_transport(), PACKET_TYPE_STREAM_STOP, and SET_ERRNO.