## Overview DAP Client provides comprehensive client-side functionality for connecting to and interacting with DAP-enabled servers and services. This module implements connection management, protocol handling, authentication, and service discovery, enabling applications to seamlessly integrate with the DAP ecosystem. **Based on:** `dap-sdk/net/client/include/dap_client.h`, `dap-sdk/net/client/src/dap_client.c` ## Document Structure - [[#Overview|Overview]] - [[#Module Structures|Module Structures]] - [[#dap_client_t|dap_client_t - Client Instance]] - [[#dap_client_config_t|dap_client_config_t - Configuration]] - [[#dap_client_connection_t|dap_client_connection_t - Connection Management]] - [[#dap_client_request_t|dap_client_request_t - Request Structure]] - [[#dap_client_auth_t|dap_client_auth_t - Authentication]] - [[#Module Functions|Module Functions]] - [[#Client Management|Client Creation and Configuration]] - [[#Connection Operations|Connection Establishment and Control]] - [[#Communication|Request/Response Handling]] - [[#Authentication|Security and Authentication]] - [[#Error Codes|Error Codes]] - [[#Typical Examples|Typical Examples]] ## Module Structures ### dap_client_t Core client instance structure managing connections and configuration. ```c typedef struct dap_client { struct { char *server_addr; // Server address/hostname uint16_t server_port; // Server port number dap_client_config_t *config; // Client configuration dap_list_t *connections; // Active connections uint32_t connection_count; // Number of connections dap_client_state_t state; // Current client state uint64_t requests_sent; // Total requests sent uint64_t responses_received; // Total responses received } pub; struct { dap_htable_t *connection_table; // Fast connection lookup dap_events_socket_t *event_socket; // Event handling socket dap_timer_t *keepalive_timer; // Connection keepalive dap_client_auth_t *auth_context; // Authentication context bool is_connected; // Connection status uint64_t last_activity; // Last activity timestamp pthread_mutex_t client_mutex; // Thread synchronization void *ssl_context; // SSL/TLS context } priv; } dap_client_t; ``` **Public Fields:** - `server_addr` - Target server address or hostname - `server_port` - Server port number for connection - `config` - Client configuration parameters - `connections` - List of active connections - `connection_count` - Current number of active connections - `state` - Current operational state of the client ### dap_client_config_t Configuration parameters for client operation and behavior. ```c typedef struct dap_client_config { struct { uint32_t connection_timeout_ms; // Connection timeout uint32_t request_timeout_ms; // Request timeout uint32_t max_connections; // Maximum concurrent connections uint32_t keepalive_interval_sec; // Keepalive frequency bool auto_reconnect; // Automatic reconnection uint32_t max_reconnect_attempts; // Reconnection retry limit bool enable_compression; // Enable data compression } pub; struct { uint32_t buffer_size; // I/O buffer size dap_enc_key_type_t encryption_type; // Encryption algorithm uint32_t heartbeat_interval_ms; // Heartbeat frequency bool debug_mode; // Debug logging enabled uint32_t circuit_breaker_threshold; // Circuit breaker failure threshold bool enable_metrics; // Performance metrics collection } priv; } dap_client_config_t; ``` ### dap_client_connection_t Connection management structure for individual server connections. ```c typedef struct dap_client_connection { struct { uint64_t connection_id; // Unique connection identifier dap_events_socket_t *socket; // Connection socket dap_connection_state_t state; // Connection state dap_time_t established_time; // Connection establishment time uint64_t bytes_sent; // Bytes sent on connection uint64_t bytes_received; // Bytes received on connection } pub; struct { dap_client_t *parent_client; // Parent client reference dap_buffer_t *send_buffer; // Send buffer queue dap_buffer_t *receive_buffer; // Receive buffer pthread_mutex_t connection_mutex; // Connection synchronization bool is_persistent; // Persistent connection flag uint32_t error_count; // Connection error counter } priv; } dap_client_connection_t; ``` ### dap_client_request_t Request structure for client-server communication. ```c typedef struct dap_client_request { struct { uint64_t request_id; // Unique request identifier dap_client_request_type_t type; // Request type void *data; // Request data payload size_t data_size; // Size of request data uint32_t timeout_ms; // Request timeout dap_client_priority_t priority; // Request priority } pub; struct { dap_client_connection_t *connection; // Connection for this request dap_client_response_callback_t callback; // Response callback void *callback_context; // Callback context data uint32_t retry_count; // Number of retry attempts bool expects_response; // Response expected flag } priv; } dap_client_request_t; ``` ### dap_client_auth_t Authentication context for secure client connections. ```c typedef struct dap_client_auth { struct { dap_auth_type_t auth_type; // Authentication method char *username; // Username for authentication char *realm; // Authentication realm bool is_authenticated; // Authentication status dap_time_t auth_time; // Authentication timestamp } pub; struct { char *password_hash; // Hashed password dap_pkey_t *private_key; // Private key for auth char *token; // Authentication token uint8_t *credentials; // Encrypted credentials size_t credentials_size; // Size of credentials pthread_mutex_t auth_mutex; // Authentication mutex } priv; } dap_client_auth_t; ``` ## Module Functions ### Client Management #### `dap_client_new()` Creates new DAP client instance with specified server address and port. ```c dap_client_t* dap_client_new(const char *a_server_addr, uint16_t a_server_port); ``` **Parameters:** - `a_server_addr` (const char*) - Server address or hostname to connect to - `a_server_port` (uint16_t) - Server port number for connection **Returns:** - `dap_client_t*` - New client instance ready for configuration - `NULL` - Client creation failed due to invalid parameters or memory allocation **Error Conditions:** - Returns NULL if a_server_addr is NULL or empty - Returns NULL if a_server_port is 0 or invalid - Returns NULL if memory allocation fails **Description:** Creates a new DAP client instance configured for the specified server. The client is created in an unconnected state and requires additional configuration before establishing connections. #### `dap_client_delete()` Destroys client instance and frees all associated resources. ```c void dap_client_delete(dap_client_t *a_client); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance to destroy **Description:** Safely destroys the client by disconnecting all connections, freeing allocated memory, and cleaning up resources. #### `dap_client_set_config()` Configures client with operational parameters. ```c int dap_client_set_config(dap_client_t *a_client, const dap_client_config_t *a_config); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance to configure - `a_config` (const dap_client_config_t*) - Configuration parameters **Returns:** - `0` - Configuration applied successfully - `-1` - Invalid client or configuration parameters - `-2` - Configuration validation failed ### Connection Operations #### `dap_client_connect()` Establishes connection to the configured server. ```c int dap_client_connect(dap_client_t *a_client); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance to connect **Returns:** - `0` - Connection established successfully - `-1` - Invalid client parameter - `-2` - Connection timeout - `-3` - Server unreachable - `-4` - Authentication failed **Error Conditions:** - Returns -1 if a_client is NULL or not properly configured - Returns -2 if connection attempt times out - Returns -3 if server is not reachable or refuses connection - Returns -4 if authentication credentials are invalid **Description:** Establishes a connection to the configured server with full authentication and encryption setup. #### `dap_client_disconnect()` Closes connection to server gracefully. ```c int dap_client_disconnect(dap_client_t *a_client); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance to disconnect **Returns:** - `0` - Disconnection completed successfully - `-1` - Invalid client parameter - `-2` - Client not connected ### Communication #### `dap_client_send_request()` Sends request to server with response handling. ```c int dap_client_send_request(dap_client_t *a_client, const dap_client_request_t *a_request); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance - `a_request` (const dap_client_request_t*) - Request to send **Returns:** - `0` - Request sent successfully - `-1` - Invalid parameters - `-2` - Client not connected - `-3` - Send buffer full #### `dap_client_send_data()` Sends raw data to server. ```c ssize_t dap_client_send_data(dap_client_t *a_client, const void *a_data, size_t a_data_size); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance - `a_data` (const void*) - Data to send - `a_data_size` (size_t) - Size of data in bytes **Returns:** - `>= 0` - Number of bytes sent - `-1` - Send operation failed ### Authentication #### `dap_client_set_auth()` Configures client authentication credentials. ```c int dap_client_set_auth(dap_client_t *a_client, const dap_client_auth_t *a_auth); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance - `a_auth` (const dap_client_auth_t*) - Authentication credentials **Returns:** - `0` - Authentication configured successfully - `-1` - Invalid parameters - `-2` - Authentication method not supported #### `dap_client_authenticate()` Performs authentication with server. ```c int dap_client_authenticate(dap_client_t *a_client); ``` **Parameters:** - `a_client` (dap_client_t*) - Client instance **Returns:** - `0` - Authentication successful - `-1` - Invalid client parameter - `-2` - Authentication failed ## Error Codes ### DAP Client Error Codes ```c typedef enum dap_client_error { DAP_CLIENT_ERROR_SUCCESS = 0, // Operation successful DAP_CLIENT_ERROR_INVALID_PARAM = -1, // Invalid parameter provided DAP_CLIENT_ERROR_NO_MEMORY = -2, // Memory allocation failed DAP_CLIENT_ERROR_NOT_CONNECTED = -3, // Not connected to server DAP_CLIENT_ERROR_CONNECTION_TIMEOUT = -4, // Connection timeout DAP_CLIENT_ERROR_CONNECTION_FAILED = -5, // Connection establishment failed DAP_CLIENT_ERROR_AUTH_FAILED = -6, // Authentication failed DAP_CLIENT_ERROR_REQUEST_TIMEOUT = -7, // Request timeout DAP_CLIENT_ERROR_SERVER_ERROR = -8, // Server returned error DAP_CLIENT_ERROR_PROTOCOL_ERROR = -9, // Protocol violation DAP_CLIENT_ERROR_ENCRYPTION_FAILED = -10, // Encryption/decryption failed DAP_CLIENT_ERROR_SERVICE_UNAVAILABLE = -11, // Requested service unavailable DAP_CLIENT_ERROR_BUFFER_FULL = -12 // Send/receive buffer full } dap_client_error_t; ``` ## Typical Examples ### Basic Client Connection Example ```c #include "dap_common.h" #include "dap_client.h" int example_client_connection() { log_it(L_INFO, "=== DAP Client Example ==="); // Step 1: Create client instance dap_client_t *client = dap_client_new("127.0.0.1", 8080); if (!client) { log_it(L_ERROR, "✗ Failed to create DAP client"); return -1; } log_it(L_INFO, "✓ DAP client created for server 127.0.0.1:8080"); // Step 2: Configure client dap_client_config_t config = { .pub.connection_timeout_ms = 5000, .pub.request_timeout_ms = 10000, .pub.max_connections = 5, .pub.keepalive_interval_sec = 30, .pub.auto_reconnect = true, .pub.max_reconnect_attempts = 3, .pub.enable_compression = false, .priv.buffer_size = 8192, .priv.encryption_type = DAP_ENC_KEY_TYPE_AES256, .priv.debug_mode = true }; int result = dap_client_set_config(client, &config); if (result != 0) { log_it(L_ERROR, "✗ Failed to configure client: %d", result); dap_client_delete(client); return -1; } log_it(L_INFO, "✓ Client configured successfully"); // Step 3: Connect to server result = dap_client_connect(client); if (result == 0) { log_it(L_INFO, "✓ Connected to server successfully"); } else { log_it(L_ERROR, "✗ Connection failed: %d", result); dap_client_delete(client); return -1; } // Step 4: Send test data const char *test_message = "Hello from DAP client!"; ssize_t bytes_sent = dap_client_send_data(client, test_message, strlen(test_message)); if (bytes_sent > 0) { log_it(L_INFO, "✓ Sent %zd bytes to server", bytes_sent); } else { log_it(L_ERROR, "✗ Failed to send data to server"); } // Step 5: Cleanup dap_client_disconnect(client); dap_client_delete(client); log_it(L_INFO, "✓ DAP Client example completed"); return 0; } ``` ### Authentication Example ```c #include "dap_common.h" #include "dap_client.h" int example_client_authentication() { log_it(L_INFO, "=== DAP Client Authentication Example ==="); // Step 1: Create client dap_client_t *client = dap_client_new("secure.example.com", 443); if (!client) { log_it(L_ERROR, "✗ Failed to create client"); return -1; } // Step 2: Set up authentication dap_client_auth_t auth = { .pub.auth_type = DAP_AUTH_TYPE_PASSWORD, .pub.username = "testuser", .pub.realm = "dap-service" }; int result = dap_client_set_auth(client, &auth); if (result != 0) { log_it(L_ERROR, "✗ Failed to configure authentication: %d", result); dap_client_delete(client); return -1; } log_it(L_INFO, "✓ Authentication configured"); // Step 3: Connect with authentication result = dap_client_connect(client); if (result == 0) { log_it(L_INFO, "✓ Authenticated connection established"); } else { log_it(L_ERROR, "✗ Authentication failed: %d", result); } // Step 4: Cleanup dap_client_delete(client); log_it(L_INFO, "✓ Authentication example completed"); return 0; } ``` --- **See also:** [[Module DAP Server|Module DAP Server]], [[Module DAP Stream|Module DAP Stream]], [[Module DAP IO|Module DAP IO]] --- *Based on: `dap-sdk/net/client/include/dap_client.h`, `dap-sdk/net/client/src/dap_client.c`*