client.h File Reference

Go to the source code of this file.

Data Structures
struct	tcp_client_audio_packet_t
	Audio packet for async network transmission. More...
struct	tcp_client
	TCP client connection and state management. More...

Macros
#define	TCP_CLIENT_AUDIO_QUEUE_SIZE   256

Typedefs
typedef struct tcp_client	tcp_client_t
	TCP client connection and state management.

Functions
tcp_client_t *	tcp_client_create (void)
	Create and initialize a TCP client instance.
void	tcp_client_destroy (tcp_client_t **client_ptr)
	Destroy TCP client and free all resources.
bool	tcp_client_is_active (const tcp_client_t *client)
	Check if connection is currently active.
bool	tcp_client_is_lost (const tcp_client_t *client)
	Check if connection was lost.
socket_t	tcp_client_get_socket (const tcp_client_t *client)
	Get current socket descriptor.
uint32_t	tcp_client_get_id (const tcp_client_t *client)
	Get client ID assigned by server.
void	tcp_client_signal_lost (tcp_client_t *client)
	Signal that connection was lost (triggers reconnection)
void	tcp_client_close (tcp_client_t *client)
	Close connection gracefully.
void	tcp_client_shutdown (tcp_client_t *client)
	Shutdown connection forcefully (for signal handlers)
void	tcp_client_cleanup (tcp_client_t *client)
	Cleanup connection resources.
int	tcp_client_connect (tcp_client_t *client, const char *address, int port, int reconnect_attempt, bool first_connection, bool has_ever_connected)
	Establish TCP connection to server.
int	tcp_client_send_packet (tcp_client_t *client, packet_type_t type, const void *data, size_t len)
	Send packet with thread-safe mutex protection.
int	tcp_client_send_ping (tcp_client_t *client)
	Send ping packet.
int	tcp_client_send_pong (tcp_client_t *client)
	Send pong packet.
int	tcp_client_send_audio_opus (tcp_client_t *client, const uint8_t *opus_data, size_t opus_size, int sample_rate, int frame_duration)
	Send Opus-encoded audio frame.
int	tcp_client_send_audio_opus_batch (tcp_client_t *client, const uint8_t *opus_data, size_t opus_size, const uint16_t *frame_sizes, int frame_count)
	Send Opus audio batch packet.
int	tcp_client_send_terminal_capabilities (tcp_client_t *client, unsigned short width, unsigned short height)
	Send terminal capabilities packet.
int	tcp_client_send_join (tcp_client_t *client, const char *display_name, uint32_t capabilities)
	Send client join packet.
int	tcp_client_send_stream_start (tcp_client_t *client, uint32_t stream_type)
	Send stream start packet.
int	tcp_client_send_audio_batch (tcp_client_t *client, const float *samples, int num_samples, int batch_count)
	Send audio batch packet.

Macro Definition Documentation

TCP_CLIENT_AUDIO_QUEUE_SIZE

#define TCP_CLIENT_AUDIO_QUEUE_SIZE   256

Definition at line 64 of file lib/network/tcp/client.h.

Typedef Documentation

tcp_client_t

typedef struct tcp_client tcp_client_t

TCP client connection and state management.

Encapsulates all state for a single TCP client connection, including:

• Network connection state (socket, server info, connection flags)
• Thread management (handles, creation flags, exit flags)
• Audio processing state (queues, buffers, context)
• Protocol state (packet tracking, server state)
• Display state (terminal capabilities, TTY info)
• Crypto state (handshake context, encryption flags)

Ownership Model

• Created by tcp_client_create() in main thread
• Owned by application, shared read-only or synchronized across threads
• Destroyed by tcp_client_destroy() after all worker threads joined

Thread Safety

• Atomic fields: Safe for concurrent read/write without locks
• Mutex-protected fields: Acquire mutex before access
• Immutable after init: Safe for concurrent reads

See also

tcp_server_t For server-side equivalent structure

Function Documentation

tcp_client_cleanup()

void tcp_client_cleanup

(

tcp_client_t *

client

)

Cleanup connection resources.

Parameters

client

TCP client instance

Definition at line 317 of file lib/network/tcp/client.c.

                                              {
  if (!client)
    return;
 
  // Close connection
  tcp_client_close(client);
 
  // Reset state flags
  atomic_store(&client->connection_lost, false);
  atomic_store(&client->should_reconnect, false);
  memset(client->server_ip, 0, sizeof(client->server_ip));
}

References tcp_client::connection_lost, tcp_client::server_ip, tcp_client::should_reconnect, and tcp_client_close().

tcp_client_close()

void tcp_client_close

(

tcp_client_t *

client

)

Close connection gracefully.

Parameters

client

TCP client instance

Definition at line 280 of file lib/network/tcp/client.c.

                                            {
  if (!client)
    return;
 
  log_debug("Closing client connection");
 
  // Mark connection as inactive
  atomic_store(&client->connection_active, false);
 
  // Close socket
  if (socket_is_valid(client->sockfd)) {
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
  }
 
  // Reset client ID
  client->my_client_id = 0;
}

References tcp_client::connection_active, INVALID_SOCKET_VALUE, log_debug, tcp_client::my_client_id, socket_is_valid(), and tcp_client::sockfd.

Referenced by tcp_client_cleanup().

tcp_client_connect()

int tcp_client_connect	(	tcp_client_t *	client,
		const char *	address,
		int	port,
		int	reconnect_attempt,
		bool	first_connection,
		bool	has_ever_connected
	)

Establish TCP connection to server.

Performs full connection lifecycle including DNS resolution, socket creation, connection with timeout, and socket configuration. Does NOT perform crypto handshake or send initial packets - those are application responsibilities.

Parameters

client	TCP client instance
address	Server hostname or IP address
port	Server port number
reconnect_attempt	Current reconnection attempt (0 for first, 1+ for retries)
first_connection	True if this is the very first connection since program start
has_ever_connected	True if client has successfully connected at least once

Returns

0 on success, negative on error

Performs full connection lifecycle:

• DNS resolution with IPv4/IPv6 dual-stack support
• Socket creation and connection with timeout
• Crypto handshake (if enabled)
• Initial capability exchange
• Client ID assignment from local port

Parameters

client	TCP client instance
address	Server hostname or IP address
port	Server port number
reconnect_attempt	Current reconnection attempt (0 for first, 1+ for retries)
first_connection	True if this is the very first connection since program start
has_ever_connected	True if client has successfully connected at least once

Returns

0 on success, negative on error

Definition at line 411 of file lib/network/tcp/client.c.

                                                                       {
  (void)first_connection;   // Currently unused
  (void)has_ever_connected; // Currently unused
 
  if (!client || !address || port <= 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid client, address, or port");
  }
 
  // Close any existing connection
  if (socket_is_valid(client->sockfd)) {
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
  }
 
  // Apply reconnection delay if this is a retry
  if (reconnect_attempt > 0) {
    unsigned int delay_us = get_reconnect_delay(reconnect_attempt);
    platform_sleep_usec(delay_us);
  }
 
  // Resolve server address using getaddrinfo() for IPv4/IPv6 support
  // Special handling for localhost: ensure we try both IPv6 (::1) and IPv4 (127.0.0.1)
  bool is_localhost =
      (strcmp(address, "localhost") == 0 || strcmp(address, "127.0.0.1") == 0 || strcmp(address, "::1") == 0);
 
  struct addrinfo hints, *res = NULL, *addr_iter;
  memset(&hints, 0, sizeof(hints));
  hints.ai_family = AF_UNSPEC; // Allow IPv4 or IPv6
  hints.ai_socktype = SOCK_STREAM;
  if (is_localhost) {
    hints.ai_flags = AI_NUMERICSERV; // Optimize for localhost
  }
 
  char port_str[16];
  SAFE_SNPRINTF(port_str, sizeof(port_str), "%d", port);
 
  // For localhost, try IPv6 loopback (::1) first, then fall back to IPv4
  if (is_localhost) {
    log_debug("Localhost detected - trying IPv6 loopback [::1]:%s first...", port_str);
    hints.ai_family = AF_INET6;
    hints.ai_flags = AI_NUMERICHOST | AI_NUMERICSERV;
 
    int ipv6_result = getaddrinfo("::1", port_str, &hints, &res);
    if (ipv6_result == 0 && res != NULL) {
      // Try IPv6 loopback connection
      client->sockfd = socket_create(res->ai_family, res->ai_socktype, res->ai_protocol);
      if (client->sockfd != INVALID_SOCKET_VALUE) {
        log_info("Trying IPv6 loopback connection to [::1]:%s...", port_str);
        if (connect_with_timeout(client->sockfd, res->ai_addr, res->ai_addrlen, CONNECT_TIMEOUT)) {
          log_debug("Connection successful using IPv6 loopback");
          SAFE_STRNCPY(client->server_ip, "::1", sizeof(client->server_ip));
          freeaddrinfo(res);
          res = NULL; // Prevent double-free at connection_success label
          goto connection_success;
        }
        close_socket_safe(client->sockfd);
        client->sockfd = INVALID_SOCKET_VALUE;
      }
      freeaddrinfo(res);
      res = NULL;
    }
 
    // IPv6 failed, try IPv4 loopback (127.0.0.1)
    log_debug("IPv6 failed, trying IPv4 loopback 127.0.0.1:%s...", port_str);
    hints.ai_family = AF_INET;
 
    int ipv4_result = getaddrinfo("127.0.0.1", port_str, &hints, &res);
    if (ipv4_result == 0 && res != NULL) {
      client->sockfd = socket_create(res->ai_family, res->ai_socktype, res->ai_protocol);
      if (client->sockfd != INVALID_SOCKET_VALUE) {
        log_info("Trying IPv4 loopback connection to 127.0.0.1:%s...", port_str);
        if (connect_with_timeout(client->sockfd, res->ai_addr, res->ai_addrlen, CONNECT_TIMEOUT)) {
          log_debug("Connection successful using IPv4 loopback");
          SAFE_STRNCPY(client->server_ip, "127.0.0.1", sizeof(client->server_ip));
          freeaddrinfo(res);
          res = NULL;
          goto connection_success;
        }
        close_socket_safe(client->sockfd);
        client->sockfd = INVALID_SOCKET_VALUE;
      }
      freeaddrinfo(res);
      res = NULL;
    }
 
    // Both IPv6 and IPv4 loopback failed for localhost
    log_warn("Could not connect to localhost using either IPv6 or IPv4 loopback");
    return -1;
  }
 
  // For non-localhost addresses, use standard resolution
  log_debug("Resolving server address '%s' port %s...", address, port_str);
  hints.ai_family = AF_UNSPEC;
  hints.ai_flags = 0;
  int getaddr_result = getaddrinfo(address, port_str, &hints, &res);
  if (getaddr_result != 0) {
    log_error("Failed to resolve server address '%s': %s", address, gai_strerror(getaddr_result));
    return -1;
  }
 
  // Try each address returned by getaddrinfo() - prefer IPv6, fall back to IPv4
  for (int address_family = AF_INET6; address_family >= AF_INET; address_family -= (AF_INET6 - AF_INET)) {
    for (addr_iter = res; addr_iter != NULL; addr_iter = addr_iter->ai_next) {
      if (addr_iter->ai_family != address_family) {
        continue;
      }
 
      client->sockfd = socket_create(addr_iter->ai_family, addr_iter->ai_socktype, addr_iter->ai_protocol);
      if (client->sockfd == INVALID_SOCKET_VALUE) {
        continue;
      }
 
      if (addr_iter->ai_family == AF_INET) {
        log_debug("Trying IPv4 connection...");
      } else if (addr_iter->ai_family == AF_INET6) {
        log_debug("Trying IPv6 connection...");
      }
 
      if (connect_with_timeout(client->sockfd, addr_iter->ai_addr, addr_iter->ai_addrlen, CONNECT_TIMEOUT)) {
        log_debug("Connection successful using %s", addr_iter->ai_family == AF_INET    ? "IPv4"
                                                    : addr_iter->ai_family == AF_INET6 ? "IPv6"
                                                                                       : "unknown protocol");
 
        // Extract server IP address for known_hosts
        if (format_ip_address(addr_iter->ai_family, addr_iter->ai_addr, client->server_ip, sizeof(client->server_ip)) ==
            ASCIICHAT_OK) {
          log_debug("Resolved server IP: %s", client->server_ip);
        } else {
          log_warn("Failed to format server IP address");
        }
 
        goto connection_success;
      }
 
      close_socket_safe(client->sockfd);
      client->sockfd = INVALID_SOCKET_VALUE;
    }
  }
 
connection_success:
 
  if (res) {
    freeaddrinfo(res);
  }
 
  // If we exhausted all addresses without success, fail
  if (client->sockfd == INVALID_SOCKET_VALUE) {
    log_warn("Could not connect to server %s:%d (tried all addresses)", address, port);
    return -1;
  }
 
  // Extract local port for client ID
  struct sockaddr_storage local_addr = {0};
  socklen_t addr_len = sizeof(local_addr);
  if (getsockname(client->sockfd, (struct sockaddr *)&local_addr, &addr_len) == -1) {
    log_error("Failed to get local socket address: %s", network_error_string());
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
    return -1;
  }
 
  // Extract port from either IPv4 or IPv6 address
  int local_port = 0;
  if (((struct sockaddr *)&local_addr)->sa_family == AF_INET) {
    local_port = NET_TO_HOST_U16(((struct sockaddr_in *)&local_addr)->sin_port);
  } else if (((struct sockaddr *)&local_addr)->sa_family == AF_INET6) {
    local_port = NET_TO_HOST_U16(((struct sockaddr_in6 *)&local_addr)->sin6_port);
  }
  client->my_client_id = (uint32_t)local_port;
 
  // Mark connection as active
  atomic_store(&client->connection_active, true);
  atomic_store(&client->connection_lost, false);
  atomic_store(&client->should_reconnect, false);
 
  // Initialize crypto (application must set crypto_initialized flag)
  // This is done outside this function by calling client_crypto_init()
 
  // Configure socket options
  if (socket_set_keepalive(client->sockfd, true) < 0) {
    log_warn("Failed to set socket keepalive: %s", network_error_string());
  }
 
  asciichat_error_t sock_config_result = socket_configure_buffers(client->sockfd);
  if (sock_config_result != ASCIICHAT_OK) {
    log_warn("Failed to configure socket: %s", network_error_string());
  }
 
  log_debug("Connection established successfully to %s:%d (client_id=%u)", address, port, client->my_client_id);
  return 0;
}

References ASCIICHAT_OK, CONNECT_TIMEOUT, connect_with_timeout(), tcp_client::connection_active, tcp_client::connection_lost, ERROR_INVALID_PARAM, format_ip_address(), INVALID_SOCKET_VALUE, log_debug, log_error, log_info, log_warn, tcp_client::my_client_id, NET_TO_HOST_U16, network_error_string(), platform_sleep_usec(), SAFE_SNPRINTF, SAFE_STRNCPY, tcp_client::server_ip, SET_ERRNO, tcp_client::should_reconnect, socket_configure_buffers(), socket_create(), socket_is_valid(), socket_set_keepalive(), and tcp_client::sockfd.

tcp_client_create()

tcp_client_t * tcp_client_create

(

void

)

Create and initialize a TCP client instance.

Allocates a new tcp_client_t structure and initializes all fields to safe defaults. This function must be called before starting any worker threads.

Initialization Steps

1. Allocate tcp_client_t structure
2. Zero-initialize all fields
3. Set atomic flags to initial states
4. Initialize mutexes and condition variables
5. Set socket to INVALID_SOCKET_VALUE

Error Handling

Returns NULL if allocation fails or mutex initialization fails. Check errno or use HAS_ERRNO() for detailed error information.

Returns

Pointer to initialized client, or NULL on failure

Note

Caller must call tcp_client_destroy() when done

See also

tcp_client_destroy() For proper cleanup

Create and initialize a TCP client instance.

Allocates tcp_client_t and initializes all fields to safe defaults.

Definition at line 95 of file lib/network/tcp/client.c.

                                      {
  tcp_client_t *client = SAFE_MALLOC(sizeof(tcp_client_t), tcp_client_t *);
  if (!client) {
    log_error("Failed to allocate tcp_client_t");
    return NULL;
  }
 
  // Zero-initialize all fields
  memset(client, 0, sizeof(*client));
 
  /* Connection State */
  client->sockfd = INVALID_SOCKET_VALUE;
  atomic_store(&client->connection_active, false);
  atomic_store(&client->connection_lost, false);
  atomic_store(&client->should_reconnect, false);
  client->my_client_id = 0;
  memset(client->server_ip, 0, sizeof(client->server_ip));
  client->encryption_enabled = false;
 
  // Initialize send mutex
  if (mutex_init(&client->send_mutex) != 0) {
    log_error("Failed to initialize send mutex");
    SAFE_FREE(client);
    return NULL;
  }
 
  /* Audio State */
  memset(&client->audio_ctx, 0, sizeof(client->audio_ctx));
  memset(client->audio_send_queue, 0, sizeof(client->audio_send_queue));
  client->audio_send_queue_head = 0;
  client->audio_send_queue_tail = 0;
  client->audio_send_queue_initialized = false;
  atomic_store(&client->audio_sender_should_exit, false);
 
  // Initialize audio queue mutex and condition variable
  if (mutex_init(&client->audio_send_queue_mutex) != 0) {
    log_error("Failed to initialize audio queue mutex");
    mutex_destroy(&client->send_mutex);
    SAFE_FREE(client);
    return NULL;
  }
 
  if (cond_init(&client->audio_send_queue_cond) != 0) {
    log_error("Failed to initialize audio queue cond");
    mutex_destroy(&client->audio_send_queue_mutex);
    mutex_destroy(&client->send_mutex);
    SAFE_FREE(client);
    return NULL;
  }
 
  client->audio_capture_thread_created = false;
  client->audio_sender_thread_created = false;
  atomic_store(&client->audio_capture_thread_exited, false);
 
  /* Protocol State */
  client->data_thread_created = false;
  atomic_store(&client->data_thread_exited, false);
  client->last_active_count = 0;
  client->server_state_initialized = false;
  client->should_clear_before_next_frame = false;
 
  /* Capture State */
  client->capture_thread_created = false;
  atomic_store(&client->capture_thread_exited, false);
 
  /* Keepalive State */
  client->ping_thread_created = false;
  atomic_store(&client->ping_thread_exited, false);
 
  /* Display State */
  client->has_tty = false;
  atomic_store(&client->is_first_frame_of_connection, true);
  memset(&client->tty_info, 0, sizeof(client->tty_info));
 
  /* Crypto State */
  memset(&client->crypto_ctx, 0, sizeof(client->crypto_ctx));
  client->crypto_initialized = false;
 
  log_debug("TCP client created successfully");
  return client;
}

References tcp_client::audio_capture_thread_created, tcp_client::audio_capture_thread_exited, tcp_client::audio_ctx, tcp_client::audio_send_queue, tcp_client::audio_send_queue_cond, tcp_client::audio_send_queue_head, tcp_client::audio_send_queue_initialized, tcp_client::audio_send_queue_mutex, tcp_client::audio_send_queue_tail, tcp_client::audio_sender_should_exit, tcp_client::audio_sender_thread_created, tcp_client::capture_thread_created, tcp_client::capture_thread_exited, cond_init(), tcp_client::connection_active, tcp_client::connection_lost, tcp_client::crypto_ctx, tcp_client::crypto_initialized, tcp_client::data_thread_created, tcp_client::data_thread_exited, tcp_client::encryption_enabled, tcp_client::has_tty, INVALID_SOCKET_VALUE, tcp_client::is_first_frame_of_connection, tcp_client::last_active_count, log_debug, log_error, mutex_destroy(), mutex_init(), tcp_client::my_client_id, tcp_client::ping_thread_created, tcp_client::ping_thread_exited, SAFE_FREE, SAFE_MALLOC, tcp_client::send_mutex, tcp_client::server_ip, tcp_client::server_state_initialized, tcp_client::should_clear_before_next_frame, tcp_client::should_reconnect, tcp_client::sockfd, and tcp_client::tty_info.

tcp_client_destroy()

void tcp_client_destroy

(

tcp_client_t **

client_ptr

)

Destroy TCP client and free all resources.

Destroys all synchronization primitives and frees the client structure. This function must be called AFTER all worker threads have been joined.

Cleanup Steps

1. Verify all threads have exited (debug builds only)
2. Destroy all mutexes and condition variables
3. Free tcp_client_t structure
4. Set pointer to NULL (via parameter)

Thread Safety

This function is NOT thread-safe. All worker threads must be joined before calling this function.

Parameters

client_ptr

Pointer to client pointer (set to NULL after free)

Warning

All threads must be stopped and joined before calling

Note

No-op if client_ptr is NULL or *client_ptr is NULL

Destroy TCP client and free all resources.

Must be called AFTER all threads have been joined.

Definition at line 182 of file lib/network/tcp/client.c.

                                                   {
  if (!client_ptr || !*client_ptr) {
    return;
  }
 
  tcp_client_t *client = *client_ptr;
 
#ifndef NDEBUG
  // Debug: verify all threads have exited
  if (client->audio_capture_thread_created && !atomic_load(&client->audio_capture_thread_exited)) {
    log_warn("Destroying client while audio capture thread may still be running");
  }
  if (client->data_thread_created && !atomic_load(&client->data_thread_exited)) {
    log_warn("Destroying client while data thread may still be running");
  }
  if (client->capture_thread_created && !atomic_load(&client->capture_thread_exited)) {
    log_warn("Destroying client while capture thread may still be running");
  }
  if (client->ping_thread_created && !atomic_load(&client->ping_thread_exited)) {
    log_warn("Destroying client while ping thread may still be running");
  }
#endif
 
  // Close socket if still open
  if (socket_is_valid(client->sockfd)) {
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
  }
 
  // Destroy synchronization primitives
  mutex_destroy(&client->send_mutex);
  mutex_destroy(&client->audio_send_queue_mutex);
  cond_destroy(&client->audio_send_queue_cond);
 
  // Free client structure
  SAFE_FREE(client);
  *client_ptr = NULL;
 
  log_debug("TCP client destroyed");
}

References tcp_client::audio_capture_thread_created, tcp_client::audio_capture_thread_exited, tcp_client::audio_send_queue_cond, tcp_client::audio_send_queue_mutex, tcp_client::capture_thread_created, tcp_client::capture_thread_exited, cond_destroy(), tcp_client::data_thread_created, tcp_client::data_thread_exited, INVALID_SOCKET_VALUE, log_debug, log_warn, mutex_destroy(), tcp_client::ping_thread_created, tcp_client::ping_thread_exited, SAFE_FREE, tcp_client::send_mutex, socket_is_valid(), and tcp_client::sockfd.

Referenced by connection_context_cleanup().

tcp_client_get_id()

uint32_t tcp_client_get_id

(

const tcp_client_t *

client

)

Get client ID assigned by server.

Parameters

client

TCP client instance

Returns

Client ID (from local port) or 0 if not connected

Definition at line 255 of file lib/network/tcp/client.c.

                                                       {
  return client ? client->my_client_id : 0;
}

References tcp_client::my_client_id.

tcp_client_get_socket()

socket_t tcp_client_get_socket

(

const tcp_client_t *

client

)

Get current socket descriptor.

Parameters

client

TCP client instance

Returns

Socket descriptor or INVALID_SOCKET_VALUE if not connected

Definition at line 248 of file lib/network/tcp/client.c.

                                                           {
  return client ? client->sockfd : INVALID_SOCKET_VALUE;
}

References INVALID_SOCKET_VALUE, and tcp_client::sockfd.

tcp_client_is_active()

bool tcp_client_is_active

(

const tcp_client_t *

client

)

Check if connection is currently active.

Parameters

client

TCP client instance

Returns

true if connection is active, false otherwise

Definition at line 230 of file lib/network/tcp/client.c.

                                                      {
  if (!client)
    return false;
  return atomic_load(&client->connection_active);
}

References tcp_client::connection_active.

tcp_client_is_lost()

bool tcp_client_is_lost

(

const tcp_client_t *

client

)

Check if connection was lost.

Parameters

client

TCP client instance

Returns

true if connection loss was detected, false otherwise

Definition at line 239 of file lib/network/tcp/client.c.

                                                    {
  if (!client)
    return false;
  return atomic_load(&client->connection_lost);
}

References tcp_client::connection_lost.

tcp_client_send_audio_batch()

int tcp_client_send_audio_batch	(	tcp_client_t *	client,
		const float *	samples,
		int	num_samples,
		int	batch_count
	)

Send audio batch packet.

Parameters

client	TCP client instance
samples	Audio sample buffer
num_samples	Number of samples in buffer
batch_count	Number of chunks in batch

Returns

0 on success, negative on error

Definition at line 878 of file lib/network/tcp/client.c.

                                                                                                              {
  if (!client || !samples) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client or samples");
  }
 
  if (!atomic_load(&client->connection_active)) {
    return SET_ERRNO(ERROR_NETWORK, "Connection not active");
  }
 
  mutex_lock(&client->send_mutex);
 
  if (!atomic_load(&client->connection_active) || client->sockfd == INVALID_SOCKET_VALUE) {
    mutex_unlock(&client->send_mutex);
    return -1;
  }
 
  crypto_context_t *crypto_ctx = NULL;
  if (client->crypto_initialized && crypto_handshake_is_ready(&client->crypto_ctx)) {
    crypto_ctx = crypto_handshake_get_context(&client->crypto_ctx);
  }
 
  int result = send_audio_batch_packet(client->sockfd, samples, num_samples, batch_count, crypto_ctx);
 
  mutex_unlock(&client->send_mutex);
 
  if (result < 0) {
    tcp_client_signal_lost(client);
  }
 
  return result;
}

References tcp_client::connection_active, tcp_client::crypto_ctx, crypto_handshake_get_context(), crypto_handshake_is_ready(), tcp_client::crypto_initialized, ERROR_INVALID_PARAM, ERROR_NETWORK, INVALID_SOCKET_VALUE, mutex_lock, mutex_unlock, send_audio_batch_packet(), tcp_client::send_mutex, SET_ERRNO, tcp_client::sockfd, and tcp_client_signal_lost().

tcp_client_send_audio_opus()

int tcp_client_send_audio_opus	(	tcp_client_t *	client,
		const uint8_t *	opus_data,
		size_t	opus_size,
		int	sample_rate,
		int	frame_duration
	)

Send Opus-encoded audio frame.

Parameters

client	TCP client instance
opus_data	Opus-encoded audio data
opus_size	Size of encoded frame
sample_rate	Sample rate in Hz
frame_duration	Frame duration in milliseconds

Returns

0 on success, negative on error

Definition at line 618 of file lib/network/tcp/client.c.

                                                   {
  if (!client || !opus_data) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client or opus_data");
  }
 
  if (!atomic_load(&client->connection_active)) {
    return SET_ERRNO(ERROR_NETWORK, "Connection not active");
  }
 
  mutex_lock(&client->send_mutex);
 
  // Recheck connection status inside mutex to prevent TOCTOU race
  if (!atomic_load(&client->connection_active) || client->sockfd == INVALID_SOCKET_VALUE) {
    mutex_unlock(&client->send_mutex);
    return SET_ERRNO(ERROR_NETWORK, "Connection not active");
  }
 
  // Get crypto context if encryption is enabled
  crypto_context_t *crypto_ctx = NULL;
  if (client->crypto_initialized && crypto_handshake_is_ready(&client->crypto_ctx)) {
    crypto_ctx = crypto_handshake_get_context(&client->crypto_ctx);
  }
 
  // Build Opus packet with header
  size_t header_size = 16; // sample_rate (4), frame_duration (4), reserved (8)
  size_t total_size = header_size + opus_size;
  void *packet_data = buffer_pool_alloc(NULL, total_size);
  if (!packet_data) {
    mutex_unlock(&client->send_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for Opus packet: %zu bytes", total_size);
  }
 
  // Write header in network byte order
  uint8_t *buf = (uint8_t *)packet_data;
  uint32_t sr = HOST_TO_NET_U32((uint32_t)sample_rate);
  uint32_t fd = HOST_TO_NET_U32((uint32_t)frame_duration);
  memcpy(buf, &sr, 4);
  memcpy(buf + 4, &fd, 4);
  memset(buf + 8, 0, 8); // Reserved
 
  // Copy Opus data
  memcpy(buf + header_size, opus_data, opus_size);
 
  // Send packet with encryption if available
  asciichat_error_t result;
  if (crypto_ctx) {
    result = send_packet_secure(client->sockfd, PACKET_TYPE_AUDIO_OPUS, packet_data, total_size, crypto_ctx);
  } else {
    result = packet_send(client->sockfd, PACKET_TYPE_AUDIO_OPUS, packet_data, total_size);
  }
 
  buffer_pool_free(NULL, packet_data, total_size);
  mutex_unlock(&client->send_mutex);
 
  if (result != ASCIICHAT_OK) {
    tcp_client_signal_lost(client);
  }
 
  return result;
}

References ASCIICHAT_OK, buffer_pool_alloc(), buffer_pool_free(), tcp_client::connection_active, tcp_client::crypto_ctx, crypto_handshake_get_context(), crypto_handshake_is_ready(), tcp_client::crypto_initialized, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, mutex_lock, mutex_unlock, packet_send(), PACKET_TYPE_AUDIO_OPUS, tcp_client::send_mutex, send_packet_secure(), SET_ERRNO, tcp_client::sockfd, and tcp_client_signal_lost().

tcp_client_send_audio_opus_batch()

int tcp_client_send_audio_opus_batch	(	tcp_client_t *	client,
		const uint8_t *	opus_data,
		size_t	opus_size,
		const uint16_t *	frame_sizes,
		int	frame_count
	)

Send Opus audio batch packet.

Parameters

client	TCP client instance
opus_data	Opus-encoded audio data (multiple frames)
opus_size	Total size of Opus data
frame_sizes	Array of individual frame sizes
frame_count	Number of frames in batch

Returns

0 on success, negative on error

Definition at line 690 of file lib/network/tcp/client.c.

                                                                                   {
  if (!client || !opus_data || !frame_sizes) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client, opus_data, or frame_sizes");
  }
 
  if (!atomic_load(&client->connection_active)) {
    return SET_ERRNO(ERROR_NETWORK, "Connection not active");
  }
 
  mutex_lock(&client->send_mutex);
 
  if (!atomic_load(&client->connection_active) || client->sockfd == INVALID_SOCKET_VALUE) {
    mutex_unlock(&client->send_mutex);
    return -1;
  }
 
  crypto_context_t *crypto_ctx = NULL;
  if (client->crypto_initialized && crypto_handshake_is_ready(&client->crypto_ctx)) {
    crypto_ctx = crypto_handshake_get_context(&client->crypto_ctx);
  }
 
  // Opus uses 20ms frames at 48kHz
  int result =
      av_send_audio_opus_batch(client->sockfd, opus_data, opus_size, frame_sizes, 48000, 20, frame_count, crypto_ctx);
 
  mutex_unlock(&client->send_mutex);
 
  if (result < 0) {
    tcp_client_signal_lost(client);
  }
 
  return result;
}

References av_send_audio_opus_batch(), tcp_client::connection_active, tcp_client::crypto_ctx, crypto_handshake_get_context(), crypto_handshake_is_ready(), tcp_client::crypto_initialized, ERROR_INVALID_PARAM, ERROR_NETWORK, INVALID_SOCKET_VALUE, mutex_lock, mutex_unlock, tcp_client::send_mutex, SET_ERRNO, tcp_client::sockfd, and tcp_client_signal_lost().

tcp_client_send_join()

int tcp_client_send_join	(	tcp_client_t *	client,
		const char *	display_name,
		uint32_t	capabilities
	)

Send client join packet.

Parameters

client	TCP client instance
display_name	Client display name
capabilities	Client capability flags

Returns

0 on success, negative on error

Definition at line 814 of file lib/network/tcp/client.c.

                                                                                                {
  if (!client) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client");
  }
 
  if (!atomic_load(&client->connection_active) || client->sockfd == INVALID_SOCKET_VALUE) {
    return -1;
  }
 
  // Build CLIENT_JOIN packet
  client_info_packet_t join_packet;
  SAFE_MEMSET(&join_packet, sizeof(join_packet), 0, sizeof(join_packet));
  join_packet.client_id = HOST_TO_NET_U32(0); // Will be assigned by server
  SAFE_SNPRINTF(join_packet.display_name, MAX_DISPLAY_NAME_LEN, "%s", display_name ? display_name : "Unknown");
  join_packet.capabilities = HOST_TO_NET_U32(capabilities);
 
  int send_result = tcp_client_send_packet(client, PACKET_TYPE_CLIENT_JOIN, &join_packet, sizeof(join_packet));
  if (send_result == 0) {
    mutex_lock(&client->send_mutex);
    bool active = atomic_load(&client->connection_active);
    socket_t socket_snapshot = client->sockfd;
    crypto_context_t *crypto_ctx = NULL;
    if (client->crypto_initialized && crypto_handshake_is_ready(&client->crypto_ctx)) {
      crypto_ctx = crypto_handshake_get_context(&client->crypto_ctx);
    }
    if (active && socket_snapshot != INVALID_SOCKET_VALUE) {
      (void)log_network_message(
          socket_snapshot, (const struct crypto_context_t *)crypto_ctx, LOG_INFO, REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER,
          "CLIENT_JOIN sent (display=\"%s\", capabilities=0x%x)", join_packet.display_name, capabilities);
    }
    mutex_unlock(&client->send_mutex);
  }
  return send_result;
}

References client_info_packet_t::capabilities, client_info_packet_t::client_id, tcp_client::connection_active, tcp_client::crypto_ctx, crypto_handshake_get_context(), crypto_handshake_is_ready(), tcp_client::crypto_initialized, client_info_packet_t::display_name, ERROR_INVALID_PARAM, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, LOG_INFO, log_network_message(), MAX_DISPLAY_NAME_LEN, mutex_lock, mutex_unlock, PACKET_TYPE_CLIENT_JOIN, REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER, SAFE_MEMSET, SAFE_SNPRINTF, tcp_client::send_mutex, SET_ERRNO, tcp_client::sockfd, and tcp_client_send_packet().

tcp_client_send_packet()

int tcp_client_send_packet	(	tcp_client_t *	client,
		packet_type_t	type,
		const void *	data,
		size_t	len
	)

Send packet with thread-safe mutex protection.

All packet transmission goes through this function to ensure packets aren't interleaved on the wire. Automatically handles encryption if crypto context is ready.

Parameters

client	TCP client instance
type	Packet type identifier
data	Packet payload
len	Payload length

Returns

0 on success, negative on error

All packet transmission goes through this function to ensure packets aren't interleaved on the wire.

Definition at line 340 of file lib/network/tcp/client.c.

                                                                                                   {
  if (!client) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client");
  }
 
  if (!atomic_load(&client->connection_active)) {
    return SET_ERRNO(ERROR_NETWORK, "Connection not active");
  }
 
  // Acquire send mutex for thread-safe transmission
  mutex_lock(&client->send_mutex);
 
  // Determine if encryption should be used
  crypto_context_t *crypto_ctx = NULL;
  if (client->crypto_initialized && crypto_handshake_is_ready(&client->crypto_ctx)) {
    crypto_ctx = crypto_handshake_get_context(&client->crypto_ctx);
  }
 
  // Send packet (encrypted if crypto context available)
  asciichat_error_t result = send_packet_secure(client->sockfd, type, data, len, crypto_ctx);
 
  mutex_unlock(&client->send_mutex);
 
  if (result != ASCIICHAT_OK) {
    log_debug("Failed to send packet type %d: %s", type, asciichat_error_string(result));
    return -1;
  }
 
  return 0;
}

References ASCIICHAT_OK, tcp_client::connection_active, tcp_client::crypto_ctx, crypto_handshake_get_context(), crypto_handshake_is_ready(), tcp_client::crypto_initialized, ERROR_INVALID_PARAM, ERROR_NETWORK, log_debug, mutex_lock, mutex_unlock, tcp_client::send_mutex, send_packet_secure(), SET_ERRNO, and tcp_client::sockfd.

Referenced by tcp_client_send_join(), tcp_client_send_ping(), tcp_client_send_pong(), tcp_client_send_stream_start(), and tcp_client_send_terminal_capabilities().

tcp_client_send_ping()

int tcp_client_send_ping

(

tcp_client_t *

client

)

Send ping packet.

Parameters

client

TCP client instance

Returns

0 on success, negative on error

Definition at line 374 of file lib/network/tcp/client.c.

                                               {
  if (!client)
    return -1;
  return tcp_client_send_packet(client, PACKET_TYPE_PING, NULL, 0);
}

References PACKET_TYPE_PING, and tcp_client_send_packet().

tcp_client_send_pong()

int tcp_client_send_pong

(

tcp_client_t *

client

)

Send pong packet.

Parameters

client

TCP client instance

Returns

0 on success, negative on error

Definition at line 383 of file lib/network/tcp/client.c.

                                               {
  if (!client)
    return -1;
  return tcp_client_send_packet(client, PACKET_TYPE_PONG, NULL, 0);
}

References PACKET_TYPE_PONG, and tcp_client_send_packet().

tcp_client_send_stream_start()

int tcp_client_send_stream_start	(	tcp_client_t *	client,
		uint32_t	stream_type
	)

Send stream start packet.

Parameters

client	TCP client instance
stream_type	Type of stream (audio/video)

Returns

0 on success, negative on error

Definition at line 856 of file lib/network/tcp/client.c.

                                                                             {
  if (!client) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client");
  }
 
  if (!atomic_load(&client->connection_active) || client->sockfd == INVALID_SOCKET_VALUE) {
    return -1;
  }
 
  uint32_t type_data = HOST_TO_NET_U32(stream_type);
  return tcp_client_send_packet(client, PACKET_TYPE_STREAM_START, &type_data, sizeof(type_data));
}

References tcp_client::connection_active, ERROR_INVALID_PARAM, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, PACKET_TYPE_STREAM_START, SET_ERRNO, tcp_client::sockfd, and tcp_client_send_packet().

tcp_client_send_terminal_capabilities()

int tcp_client_send_terminal_capabilities	(	tcp_client_t *	client,
		unsigned short	width,
		unsigned short	height
	)

Send terminal capabilities packet.

Parameters

client	TCP client instance
width	Terminal width in characters
height	Terminal height in characters

Returns

0 on success, negative on error

Definition at line 733 of file lib/network/tcp/client.c.

                                                                                                             {
  if (!client) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client");
  }
 
  if (!atomic_load(&client->connection_active) || client->sockfd == INVALID_SOCKET_VALUE) {
    return -1;
  }
 
  // Detect terminal capabilities automatically
  terminal_capabilities_t caps = detect_terminal_capabilities();
 
  // Apply user's color mode override
  caps = apply_color_mode_override(caps);
 
  // Check if detection was reliable, use fallback only for auto-detection
  if (!caps.detection_reliable && (int)GET_OPTION(color_mode) == COLOR_MODE_AUTO) {
    log_warn("Terminal capability detection not reliable, using fallback");
    SAFE_MEMSET(&caps, sizeof(caps), 0, sizeof(caps));
    caps.color_level = TERM_COLOR_NONE;
    caps.color_count = 2;
    caps.capabilities = 0;
    SAFE_STRNCPY(caps.term_type, "unknown", sizeof(caps.term_type));
    SAFE_STRNCPY(caps.colorterm, "", sizeof(caps.colorterm));
    caps.detection_reliable = 0;
  }
 
  // Convert to network packet format
  terminal_capabilities_packet_t net_packet;
  net_packet.capabilities = HOST_TO_NET_U32(caps.capabilities);
  net_packet.color_level = HOST_TO_NET_U32(caps.color_level);
  net_packet.color_count = HOST_TO_NET_U32(caps.color_count);
  net_packet.render_mode = HOST_TO_NET_U32(caps.render_mode);
  net_packet.width = HOST_TO_NET_U16(width);
  net_packet.height = HOST_TO_NET_U16(height);
  net_packet.palette_type = HOST_TO_NET_U32(GET_OPTION(palette_type));
  net_packet.utf8_support = HOST_TO_NET_U32(caps.utf8_support ? 1 : 0);
 
  const options_t *opts = options_get();
  if (GET_OPTION(palette_type) == PALETTE_CUSTOM && GET_OPTION(palette_custom_set)) {
    const char *palette_custom = opts && opts->palette_custom_set ? opts->palette_custom : "";
    SAFE_STRNCPY(net_packet.palette_custom, palette_custom, sizeof(net_packet.palette_custom));
    net_packet.palette_custom[sizeof(net_packet.palette_custom) - 1] = '\0';
  } else {
    SAFE_MEMSET(net_packet.palette_custom, sizeof(net_packet.palette_custom), 0, sizeof(net_packet.palette_custom));
  }
 
  // Set desired FPS (from global g_max_fps if available, otherwise from caps)
  extern int g_max_fps; // Will be passed via options in future refactoring
  if (g_max_fps > 0) {
    net_packet.desired_fps = (uint8_t)(g_max_fps > 144 ? 144 : g_max_fps);
  } else {
    net_packet.desired_fps = caps.desired_fps;
  }
 
  if (net_packet.desired_fps == 0) {
    net_packet.desired_fps = DEFAULT_MAX_FPS;
  }
 
  SAFE_STRNCPY(net_packet.term_type, caps.term_type, sizeof(net_packet.term_type));
  net_packet.term_type[sizeof(net_packet.term_type) - 1] = '\0';
 
  SAFE_STRNCPY(net_packet.colorterm, caps.colorterm, sizeof(net_packet.colorterm));
  net_packet.colorterm[sizeof(net_packet.colorterm) - 1] = '\0';
 
  net_packet.detection_reliable = caps.detection_reliable;
  net_packet.utf8_support = GET_OPTION(force_utf8) ? 1 : 0;
 
  SAFE_MEMSET(net_packet.reserved, sizeof(net_packet.reserved), 0, sizeof(net_packet.reserved));
 
  return tcp_client_send_packet(client, PACKET_TYPE_CLIENT_CAPABILITIES, &net_packet, sizeof(net_packet));
}

References apply_color_mode_override(), terminal_capabilities_packet_t::capabilities, terminal_capabilities_t::capabilities, terminal_capabilities_packet_t::color_count, terminal_capabilities_t::color_count, terminal_capabilities_packet_t::color_level, terminal_capabilities_t::color_level, COLOR_MODE_AUTO, terminal_capabilities_packet_t::colorterm, terminal_capabilities_t::colorterm, tcp_client::connection_active, DEFAULT_MAX_FPS, terminal_capabilities_packet_t::desired_fps, terminal_capabilities_t::desired_fps, detect_terminal_capabilities(), terminal_capabilities_packet_t::detection_reliable, terminal_capabilities_t::detection_reliable, ERROR_INVALID_PARAM, g_max_fps, GET_OPTION, terminal_capabilities_packet_t::height, HOST_TO_NET_U16, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, log_warn, options_get(), PACKET_TYPE_CLIENT_CAPABILITIES, terminal_capabilities_packet_t::palette_custom, PALETTE_CUSTOM, terminal_capabilities_packet_t::palette_type, terminal_capabilities_packet_t::render_mode, terminal_capabilities_t::render_mode, terminal_capabilities_packet_t::reserved, SAFE_MEMSET, SAFE_STRNCPY, SET_ERRNO, tcp_client::sockfd, tcp_client_send_packet(), TERM_COLOR_NONE, terminal_capabilities_packet_t::term_type, terminal_capabilities_t::term_type, terminal_capabilities_packet_t::utf8_support, terminal_capabilities_t::utf8_support, and terminal_capabilities_packet_t::width.

tcp_client_shutdown()

void tcp_client_shutdown

(

tcp_client_t *

client

)

Shutdown connection forcefully (for signal handlers)

Parameters

client

TCP client instance

Definition at line 302 of file lib/network/tcp/client.c.

                                               {
  if (!client)
    return;
 
  atomic_store(&client->connection_active, false);
 
  // Shutdown socket for reading/writing to interrupt blocking calls
  if (socket_is_valid(client->sockfd)) {
    socket_shutdown(client->sockfd, SHUT_RDWR);
  }
}

References tcp_client::connection_active, socket_is_valid(), socket_shutdown(), and tcp_client::sockfd.

tcp_client_signal_lost()

void tcp_client_signal_lost

(

tcp_client_t *

client

)

Signal that connection was lost (triggers reconnection)

Parameters

client

TCP client instance

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

                                                  {
  if (!client)
    return;
 
  if (!atomic_load(&client->connection_lost)) {
    atomic_store(&client->connection_lost, true);
    atomic_store(&client->connection_active, false);
    log_info("Connection lost signaled");
  }
}

References tcp_client::connection_active, tcp_client::connection_lost, and log_info.

Referenced by tcp_client_send_audio_batch(), tcp_client_send_audio_opus(), and tcp_client_send_audio_opus_batch().