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

Functions
	__attribute__ ((unused))
	Data reception thread handle.
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

__attribute__()

__attribute__

(

(unused)

)

#include <protocol.c>

Data reception thread handle.

Handle incoming audio batch packet from server.

Thread handle for the background thread that receives and processes packets from the server. Created during connection establishment, joined during shutdown.

Remote client information structure for multi-user client tracking

Tracks information about other clients connected to the server. Used by the client to maintain awareness of other participants in the chat session.

CORE FIELDS:

• client_id: Unique identifier for this remote client
• display_name: User-friendly display name for the client
• is_active: Whether this client is currently active (sending video/audio)
• last_seen: Timestamp when this client was last seen (for timeout detection)

USAGE:

The client maintains an array of remote_client_info_t structures to track all other clients. This information is used for:

• Multi-user display coordination
• Client list display
• Connection state awareness
• Timeout detection

Note

The client_id matches the server's assigned client identifier.

display_name is received from server in CLIENT_JOIN packets.

is_active indicates whether client is sending media (video/audio).

last_seen is updated when receiving packets from this client.

Processes batched audio packets more efficiently than individual packets. Parses the audio batch header, converts quantized samples to float, and processes them through the audio subsystem.

Parameters

data	Packet payload containing audio batch header + quantized samples
len	Total packet length in bytes

Unique client identifier assigned by server

User-friendly display name (null-terminated)

Whether client is currently active (sending video/audio)

Timestamp when client was last seen (for timeout detection)

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

               {
  uint32_t client_id;
  char display_name[MAX_DISPLAY_NAME_LEN];
  bool is_active;
  time_t last_seen;
} remote_client_info_t;

References MAX_DISPLAY_NAME_LEN.

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 1192 of file client/protocol.c.

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

References server_connection_is_lost().

Referenced by client_main().

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 950 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 1061 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_info("Sending client capabilities to server...");
  if (threaded_send_terminal_size_with_auto_detect(GET_OPTION(width), GET_OPTION(height)) < 0) {
    log_error("Failed to send client capabilities to server");
    return -1;
  }
  log_info("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_info("Sending STREAM_START packet (types=0x%x: %s%s)...", stream_types, "video",
           (stream_types & STREAM_TYPE_AUDIO) ? "+audio" : "");
  if (threaded_send_stream_start_packet(stream_types) < 0) {
    log_error("Failed to send STREAM_START packet");
    return -1;
  }
  log_info("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_info("Starting webcam capture thread...");
  if (capture_start_thread() != 0) {
    log_error("Failed to start webcam capture thread");
    return -1;
  }
  log_info("Webcam capture thread started successfully");
 
  // Start audio capture thread if audio is enabled
  log_info("Starting audio capture thread...");
  if (audio_start_thread() != 0) {
    log_error("Failed to start audio capture thread");
    return -1;
  }
  log_info("Audio capture thread started successfully (or skipped if audio disabled)");
 
  // Start keepalive/ping thread to prevent server timeout
  log_info("Starting keepalive/ping thread...");
  if (keepalive_start_thread() != 0) {
    log_error("Failed to start keepalive/ping thread");
    return -1;
  }
  log_info("Keepalive/ping thread started successfully");
 
  g_data_thread_created = true;
  return 0;
}

References ASCIICHAT_OK, audio_start_thread(), capture_start_thread(), display_reset_for_new_connection(), g_client_worker_pool, GET_OPTION, keepalive_start_thread(), LOG_ERRNO_IF_SET, log_error, log_info, STREAM_TYPE_AUDIO, STREAM_TYPE_VIDEO, thread_pool_spawn(), threaded_send_stream_start_packet(), and threaded_send_terminal_size_with_auto_detect().

Referenced by client_main().

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 1137 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_usec(100000); // 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_info("Data reception thread stopped and joined by thread pool");
#endif
}

References ASCIICHAT_OK, audio_stop_thread(), capture_stop_thread(), g_client_worker_pool, keepalive_stop_thread(), LOG_ERRNO_IF_SET, log_error, log_info, log_warn, platform_sleep_usec(), server_connection_shutdown(), and thread_pool_stop_all().

Referenced by client_main().