Client Handler

📡 Client-side packet processing and data reception thread More...

Files
file	protocol.c
	📡 Client protocol handler: packet reception, parsing, and dispatch with data thread coordination
file	protocol.h
	ascii-chat Client Protocol Handler Interface

Data Structures
struct	remote_client_info_t
	Remote client information structure for multi-user client tracking. More...

Functions
int	protocol_start_connection ()
	Start protocol connection handling.
void	protocol_stop_connection ()
	Stop protocol connection handling.
bool	protocol_connection_lost ()
	Check if connection has been lost.
const acip_client_callbacks_t *	protocol_get_acip_callbacks ()
	Get ACIP client callbacks for packet dispatch.

Detailed Description

📡 Client-side packet processing and data reception thread

Client Protocol README

Overview

The protocol handler manages the data reception thread, processes incoming packets from the server, and dispatches them to appropriate handlers based on packet type.

Implementation: src/client/protocol.c, src/client/protocol.h

Data Reception Thread

static void *data_reception_thread(void *arg)
{
  (void)arg;
 
  socket_t sockfd = server_connection_get_socket();
  const crypto_context_t *crypto_ctx = crypto_client_get_context();
 
  while (!should_exit() && server_connection_is_active()) {
    packet_header_t header;
    void *payload = NULL;
    size_t payload_len = 0;
 
    // Receive and decrypt packet
    int result = receive_packet(sockfd, crypto_ctx, &header, &payload, &payload_len);
 
    if (result < 0) {
      log_debug("receive_packet failed - connection lost");
      server_connection_lost();
      break;
    }
 
    // Dispatch based on packet type
    handle_packet(&header, payload, payload_len);
 
    if (payload) {
      free(payload);
      payload = NULL;
    }
  }
 
  atomic_store(&g_data_thread_exited, true);
  return NULL;
}

Packet Handlers

ASCII Frame Handler

static void handle_ascii_frame(const void *payload, size_t payload_len)
{
  // Render ASCII frame to terminal
  display_render_frame((const char *)payload, opt_snapshot);
 
  // Snapshot mode: exit after displaying frame
  if (opt_snapshot) {
    signal_exit();
  }
}

Audio Batch Handler

static void handle_audio_batch(const void *payload, size_t payload_len)
{
  const float *samples = (const float *)payload;
  int num_samples = payload_len / sizeof(float);
 
  // Process received audio samples
  audio_process_received_samples(samples, num_samples);
}

Pong Handler

static void handle_pong(void)
{
  // Update last pong time for keepalive timeout tracking
  keepalive_record_pong();
}

Clear Console Handler

static void handle_clear_console(void)
{
  // Server requests terminal clear
  display_full_reset();
}

Server State Handler

static void handle_server_state(const void *payload, size_t payload_len)
{
  // Log server state information
  log_debug("Received server state update");
}

Connection Loss Detection

Loss triggers in protocol thread:

• receive_packet() returns error
• Socket read error (connection closed by server)
• Decryption failure (corrupted stream)
• Invalid packet magic number

if (receive_packet(...) < 0) {
  server_connection_lost();  // Signal connection loss
  break;                     // Exit thread
}

See also

src/client/protocol.c

src/client/protocol.h

Client Overview

Function Documentation

protocol_connection_lost()

bool protocol_connection_lost

(

)

#include <protocol.c>

Check if connection has been lost.

Check if connection has been lost

Returns

true if protocol detected connection loss, false otherwise

true if connection lost, false otherwise

Definition at line 1118 of file client/protocol.c.

                                {
  return atomic_load(&g_data_thread_exited) || server_connection_is_lost();
}

References server_connection_is_lost().

protocol_get_acip_callbacks()

const acip_client_callbacks_t * protocol_get_acip_callbacks

(

)

#include <protocol.h>

Get ACIP client callbacks for packet dispatch.

Returns

Pointer to client callbacks structure

Used by WebRTC sessions to receive and dispatch ACDS signaling packets.

Returns pointer to the global callback structure for use by WebRTC sessions that need to receive ACDS signaling packets.

Returns

Pointer to client callbacks (never NULL)

Definition at line 880 of file client/protocol.c.

                                                             {
  return &g_acip_client_callbacks;
}

protocol_start_connection()

int protocol_start_connection

(

)

#include <protocol.c>

Start protocol connection handling.

Start protocol connection handling

Initializes protocol state and starts the data reception thread. Must be called after successful server connection establishment.

Returns

0 on success, negative on error

0 on success, negative on error

Definition at line 985 of file client/protocol.c.

                                {
  // Reset protocol state for new connection
  g_server_state_initialized = false;
  g_last_active_count = 0;
  g_should_clear_before_next_frame = false;
 
  // Reset display state for new connection
  display_reset_for_new_connection();
 
  // Send CLIENT_CAPABILITIES packet FIRST before starting any threads
  // Server expects this as the first packet after crypto handshake
  log_debug("Sending client capabilities to server...");
  asciichat_error_t cap_result = threaded_send_terminal_size_with_auto_detect(GET_OPTION(width), GET_OPTION(height));
  if (cap_result != ASCIICHAT_OK) {
    log_error("Failed to send client capabilities to server");
    return -1;
  }
  log_debug("Client capabilities sent successfully");
 
  // Send STREAM_START packet with combined stream types BEFORE starting worker threads
  // This tells the server what streams to expect before any data arrives
  uint32_t stream_types = STREAM_TYPE_VIDEO; // Always have video
  if (GET_OPTION(audio_enabled)) {
    stream_types |= STREAM_TYPE_AUDIO; // Add audio if enabled
  }
  log_debug("Sending STREAM_START packet (types=0x%x: %s%s)...", stream_types, "video",
            (stream_types & STREAM_TYPE_AUDIO) ? "+audio" : "");
  asciichat_error_t stream_result = threaded_send_stream_start_packet(stream_types);
  if (stream_result != ASCIICHAT_OK) {
    log_error("Failed to send STREAM_START packet");
    return -1;
  }
  log_debug("STREAM_START packet sent successfully");
 
  // Start data reception thread
  atomic_store(&g_data_thread_exited, false);
  if (thread_pool_spawn(g_client_worker_pool, data_reception_thread_func, NULL, 1, "data_reception") != ASCIICHAT_OK) {
    log_error("Failed to spawn data reception thread in worker pool");
    LOG_ERRNO_IF_SET("Data reception thread creation failed");
    return -1;
  }
 
  // Start webcam capture thread
  log_debug("Starting webcam capture thread...");
  if (capture_start_thread() != 0) {
    log_error("Failed to start webcam capture thread");
    return -1;
  }
  log_debug("Webcam capture thread started successfully");
 
  // Start audio capture thread if audio is enabled
  log_debug("Starting audio capture thread...");
  if (audio_start_thread() != 0) {
    log_error("Failed to start audio capture thread");
    return -1;
  }
  log_debug("Audio capture thread started successfully (or skipped if audio disabled)");
 
  // Start keepalive/ping thread to prevent server timeout
  log_debug("Starting keepalive/ping thread...");
  if (keepalive_start_thread() != 0) {
    log_error("Failed to start keepalive/ping thread");
    return -1;
  }
  log_debug("Keepalive/ping thread started successfully");
 
  g_data_thread_created = true;
  return 0;
}

References audio_start_thread(), capture_start_thread(), display_reset_for_new_connection(), g_client_worker_pool, keepalive_start_thread(), thread_pool_spawn(), threaded_send_stream_start_packet(), and threaded_send_terminal_size_with_auto_detect().

protocol_stop_connection()

void protocol_stop_connection

(

)

#include <protocol.c>

Stop protocol connection handling.

Stop protocol connection handling

Gracefully shuts down the data reception thread and cleans up protocol state. Safe to call multiple times.

Definition at line 1063 of file client/protocol.c.

                                {
  if (!g_data_thread_created) {
    return;
  }
 
  // Don't call signal_exit() here - that's for global shutdown only!
  // We just want to stop threads for this connection, not exit the entire client
 
  // Shutdown the socket to interrupt any blocking recv() in data thread
  server_connection_shutdown();
 
  // Stop keepalive/ping thread - it checks connection status and will exit
  keepalive_stop_thread();
 
  // Stop webcam capture thread
  capture_stop_thread();
 
  // Stop audio threads if running
  audio_stop_thread();
 
  // Wait for data reception thread to exit gracefully
  int wait_count = 0;
  while (wait_count < 20 && !atomic_load(&g_data_thread_exited)) {
    platform_sleep_us(100 * US_PER_MS_INT); // 100ms
    wait_count++;
  }
 
  if (!atomic_load(&g_data_thread_exited)) {
    log_warn("Data thread not responding after 2 seconds - will be joined by thread pool");
  }
 
  // Join all threads in the client worker pool (in stop_id order)
  // This handles the data reception thread and (eventually) all other worker threads
  if (g_client_worker_pool) {
    asciichat_error_t result = thread_pool_stop_all(g_client_worker_pool);
    if (result != ASCIICHAT_OK) {
      log_error("Failed to stop client worker threads");
      LOG_ERRNO_IF_SET("Thread pool stop failed");
    }
  }
 
  g_data_thread_created = false;
 
#ifdef DEBUG_THREADS
  log_debug("Data reception thread stopped and joined by thread pool");
#endif
}

References audio_stop_thread(), capture_stop_thread(), g_client_worker_pool, keepalive_stop_thread(), platform_sleep_us(), server_connection_shutdown(), and thread_pool_stop_all().