protocol.c File Reference

📡 Client protocol handler: packet reception, parsing, and dispatch with data thread coordination More...

Go to the source code of this file.

Functions
bool	crypto_client_is_ready (void)
	Check if crypto handshake is ready.
const crypto_context_t *	crypto_client_get_context (void)
	Get crypto context for encryption/decryption.
int	crypto_client_decrypt_packet (const uint8_t *ciphertext, size_t ciphertext_len, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_len)
	Decrypt a received packet.
	__attribute__ ((unused))
	Data reception thread handle.
const acip_client_callbacks_t *	protocol_get_acip_callbacks ()
	Get ACIP client callbacks for packet dispatch.
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.

Variables
	remote_client_info_t

Detailed Description

📡 Client protocol handler: packet reception, parsing, and dispatch with data thread coordination

The client protocol handler follows a producer-consumer pattern:

• Producer: Data reception thread reads packets from socket
• Consumer: Protocol handlers process packets based on type
• Coordination: Thread-safe flags manage connection state
• Error Recovery: Connection loss detection and recovery signaling

Packet Processing Pipeline

1. Reception: Raw packet data read from TCP socket
2. Validation: Header validation and CRC verification
3. Deserialization: Network byte order conversion
4. Dispatch: Route to type-specific handler functions
5. Processing: Handler executes packet-specific logic
6. Cleanup: Buffer management and resource deallocation

Thread Management

The protocol module manages a dedicated data reception thread:

• Lifecycle: Thread creation, monitoring, and graceful termination
• Exit Coordination: Atomic flags coordinate thread shutdown
• Connection Monitoring: Detect socket closure and network errors
• Resource Management: Clean buffer pool usage and leak prevention

Packet Type Handlers

Each packet type has a dedicated handler function:

• ASCII_FRAME: Display ASCII art frames with decompression
• AUDIO: Process and queue audio samples for playback
• PING/PONG: Keepalive protocol implementation
• CLEAR_CONSOLE: Terminal control commands from server
• SERVER_STATE: Multi-client state synchronization
• Unknown Types: Graceful handling of protocol extensions

Compression Support

Frame packets support optional zstd compression:

• Detection: Frame flags indicate compression status
• Decompression: zstd inflation with size validation
• Fallback: Graceful handling when compression disabled
• Integrity: CRC32 verification of decompressed data

Integration Points

• main.c: Thread lifecycle management and coordination
• server.c: Socket operations and connection state
• display.c: Frame rendering and terminal control
• audio.c: Audio sample processing and playback
• keepalive.c: Ping/pong response coordination

Error Handling

Protocol errors are classified and handled appropriately:

• Network Errors: Socket failures trigger connection loss
• Protocol Errors: Malformed packets logged but connection continues
• Resource Errors: Memory allocation failures with graceful degradation
• Compression Errors: Invalid compressed data with frame skipping

Buffer Management

Uses shared buffer pool for efficient memory management:

• Allocation: Packets allocated from global buffer pool
• Ownership: Clear ownership transfer between modules
• Deallocation: Automatic cleanup with buffer pool integration
• Leak Prevention: Comprehensive cleanup on all error paths

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

Version

2.0

Definition in file client/protocol.c.

Variable Documentation

remote_client_info_t

remote_client_info_t

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