client.h File Reference

ACIP client-side protocol library. 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_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 library.

ACIP client-side protocol API.

Client-side ACIP (ASCII-Chat IP Protocol) implementation for:

• Session discovery and management (create, lookup, join, leave)
• WebRTC signaling relay (SDP, ICE candidates)
• String reservation (future feature)

ACIP Protocol Overview:

• Binary TCP protocol (not HTTP/JSON)
• Packet-based with CRC32 validation
• Ed25519 identity signatures
• Optional password protection

Primary Use Case: Connecting to ACDS (ASCII-Chat Discovery Service) servers for session discovery and WebRTC peer coordination.

Integration: This library is part of libasciichat and can be used by any application needing ACIP/ACDS integration.

See also

network/acip/acds.h for ACDS message structures

network/acip/protocol.h for ACIP Packet Types types

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

                                                                                             {
  if (!transport || !callbacks) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or callbacks");
  }
 
  // Get socket from transport for low-level packet reception
  socket_t sock = transport->methods->get_socket(transport);
  if (sock == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_NETWORK, "Transport has no valid socket");
  }
 
  // Check if transport is connected
  if (!transport->methods->is_connected(transport)) {
    return SET_ERRNO(ERROR_NETWORK, "Transport not connected");
  }
 
  // Receive packet with automatic decryption
  packet_envelope_t envelope;
  bool enforce_encryption = (transport->crypto_ctx != NULL);
  packet_recv_result_t result = receive_packet_secure(sock, transport->crypto_ctx, enforce_encryption, &envelope);
 
  // Handle receive errors
  if (result != PACKET_RECV_SUCCESS) {
    if (result == PACKET_RECV_EOF) {
      return SET_ERRNO(ERROR_NETWORK, "Connection closed (EOF)");
    } else if (result == PACKET_RECV_SECURITY_VIOLATION) {
      return SET_ERRNO(ERROR_CRYPTO, "Security violation: unencrypted packet when encryption required");
    } else {
      return SET_ERRNO(ERROR_NETWORK, "Failed to receive packet");
    }
  }
 
  // Dispatch packet to appropriate ACIP handler
  asciichat_error_t dispatch_result =
      acip_handle_client_packet(transport, envelope.type, envelope.data, envelope.len, callbacks);
 
  // Always free the allocated buffer (even if handler failed)
  if (envelope.allocated_buffer) {
    buffer_pool_free(NULL, envelope.allocated_buffer, envelope.allocated_size);
  }
 
  // Return handler result
  return dispatch_result;
}

References acip_handle_client_packet(), packet_envelope_t::allocated_buffer, packet_envelope_t::allocated_size, buffer_pool_free(), acip_transport::crypto_ctx, packet_envelope_t::data, ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_NETWORK, acip_transport_methods_t::get_socket, INVALID_SOCKET_VALUE, acip_transport_methods_t::is_connected, packet_envelope_t::len, acip_transport::methods, PACKET_RECV_EOF, PACKET_RECV_SECURITY_VIOLATION, PACKET_RECV_SUCCESS, receive_packet_secure(), SET_ERRNO, and packet_envelope_t::type.

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 157 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);
}

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

                                                                                           {
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport");
  }
 
  // Simple capability byte payload
  return packet_send_via_transport(transport, PACKET_TYPE_CLIENT_JOIN, &capabilities, sizeof(capabilities));
}

References ERROR_INVALID_PARAM, packet_send_via_transport(), PACKET_TYPE_CLIENT_JOIN, 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 128 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);
}

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

                                                                                {
  if (!transport || !pixel_data) {
    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;
 
  // 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) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Packet size overflow");
  }
 
  // Allocate buffer
  uint8_t *buffer = buffer_pool_alloc(NULL, total_size);
  if (!buffer) {
    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);
 
  // Send via transport
  asciichat_error_t result = packet_send_via_transport(transport, PACKET_TYPE_IMAGE_FRAME, buffer, total_size);
 
  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, image_frame_packet_t::height, HOST_TO_NET_U32, 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.

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 165 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));
}

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 137 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));
}

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 147 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));
}

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