A client module for the DAP protocol that establishes a connection to a remote server, first initiates the exchange of public keys through the server for encrypted requests and responses, and then connects to the streaming server. Some intermediate actions can be added to these steps, and not all of these steps can be executed - all this can be quite diverse and flexible using the functions of this module.
dap_client_t
An object that aggregates data for the implementation of the DAP client is created via dap_client_new and is further controlled by the rest of the functions. It has a private part, closed from users of this API, as well as the ._inheritor field for inherited objects, in order to receive a pointer to them in the callbacks of the functions dap_client_new (object creation), dap_client_go_stage (launching the state machine) and other functions. It is recommended to set the following internal parameters (properties) before starting the state machine:
● active_channels - List of active channels, set via the dap_client_set_active_channels function.
● auth_cert To prevent a Man-in-the-Middle attack, you should sign all your primary key exchanges with your own certificate.
● uplink_addr, uplink_port The address and port of the remote host with which the connection will be established are set together via the dap_client_set_uplink function or separately via the corresponding functions.
dap_client_stage_t
Describes all the basic steps of DAP connections. The minimum state to which it makes sense to start the state machine is STAGE_ENC_INIT, after which you can do encrypted request-response operations through the dap_client_request_enc functions. Also, in any state, you can already start making unencrypted dap_client_request requests, thus making regular non-DAP HTTP requests.
STAGE_BEGIN - the initial stage from which the state machine starts. Everything is off, there are no active connections.
STAGE_ENC_INIT - at the transition to this stage, the first connection occurs, during which the primary exchange of public keys occurs.
STAGE_STREAM_CTL - at this stage, an encrypted request is made to create a streaming session and receive a streaming key.
STAGE_STREAM_SESSION - the stream key is obtained and the session is created.
STAGE_STREAM_CONNECTED - at this stage, a connection is established with the host for streaming data exchange.
STAGE_STREAM_STREAMING - streaming has started, all logical channels are activated.
STAGE_STREAM_ABORT - streaming connection terminated.
dap_client_stage_status_t
STAGE_STATUS_NONE - step status not set.
STAGE_STATUS_IN_PROGRESS - stage in the process.
STAGE_STATUS_ABORTING - step in the interruption process.
STAGE_STATUS_ERROR - error state.
STAGE_STATUS_DONE - stage completed.
dap_client_error_t
An enumerated type indicating what kind of error occurred.
ERROR_NO_ERROR - no error, all is well.
ERROR_ENC_NO_KEY - there is no key at the stage of public key exchange.
ERROR_ENC_WRONG_KEY - the wrong key, for example, the signature does not match to the access lists.
ERROR_STREAM_CTL_ERROR - error at the stage of creating a streaming session.
ERROR_STREAM_CTL_ERROR_AUTH - authentication error: streaming session could not be created.
ERROR_STREAM_CTL_ERROR_RESPONSE_FORMAT - the format of request to the stream session management module is invalid.
ERROR_STREAM_RESPONSE_WRONG - Incorrect stream connection request format.
ERROR_STREAM_RESPONSE_TIMEOUT - timeout to establish a streaming connection.
ERROR_STREAM_FREEZED - the stream connection has stopped responding to the requests.
ERROR_NETWORK_CONNECTION_REFUSE - network error: connection refused.
ERROR_NETWORK_CONNECTION_TIMEOUT - network error: host not responding.
dap_client_init
int dap_client_init()
Initializes the DAP client module. Returns 0 if all is well.
dap_client_deinit
void dap_client_deinit()
Deinitializes the DAP client module.
dap_client_new
dap_client_t * dap_client_new(dap_events_t * a_events, dap_client_callback_t a_stage_status_callback, dap_client_callback_t a_stage_status_error_callback)
The function creates a new dap_client_t object, a_events points to the object controlling the I/O reactor dap_events_t, a_stage_status_callback is called every time the stage and/or stage status changes, a_stage_status_error_callback is called on error. All callbacks are executed in the context of an I/O reactor.
dap_client_set_uplink_unsafe
void dap_client_set_uplink_unsafe(dap_client_t * a_client,const char* a_addr, uint16_t a_port)
Sets the remote host address a_addr and the port a_port for the client a_client.
dap_client_get_uplink_addr_unsafe
const char* dap_client_get_uplink_addr_unsafe(dap_client_t * a_client)
Returns the address of the remote host for the client a_client.
dap_client_get_uplink_port_unsafe
uint16_t dap_client_get_uplink_port_unsafe(dap_client_t * a_client)
Returns the port of the remote host for the client a_client.
dap_client_delete_unsafe
void dap_client_delete_unsafe(dap_client_t * a_client)
Removes the client a_client.
dap_client_delete_unsafe_mt
void dap_client_delete_mt(dap_client_t * a_client)
Removes the client a_client, thread-safe.
dap_client_get_key_stream
dap_enc_key_t * dap_client_get_key_stream(dap_client_t * a_client)
Returns the stream key of the client a_client.
dap_client_go_stage
void dap_client_go_stage(dap_client_t * a_client, dap_client_stage_t a_stage_end, dap_client_callback_t a_stage_end_callback)
It starts the state machine up to the final stage a_stage_end for a client a_client and also executes the a_stage_end_callback at the end, in the context of the I/O reactor.
dap_client_request_enc_unsafe
void dap_client_request_enc_unsafe(dap_client_t * a_client, const char * a_path,const char * a_suburl,const char* a_query, void * a_request, size_t a_request_size, dap_client_callback_data_size_t a_response_proc, dap_client_callback_int_t a_response_error)
This function forms and sends an encrypted HTTP request to the remote host of the client a_client, which means that at the time of this request, the state machine must already be at least in the state STAGE_ENC_INIT : STAGE_STATUS_DONE. The path on the remote host is specified in a_path and a_suburl, the HTTP request field is in a_query, and the encrypted request body and its size are in a_request and a_request_size args. In case of a successful response, the a_response_proc callback is called, in case of failure - a_response_error.
dap_client_request_unsafe
void dap_client_request_unsafe(dap_client_t * a_client, const char * a_full_path, void * a_request, size_t a_request_size, dap_client_callback_data_size_t a_response_proc, dap_client_callback_int_t a_response_error)
Forms and sends a normal HTTP request to the remote host of the client a_client. The path on the remote host is specified in a_full_path, the request body and its size are in a_request and a_request_size. In case of a successful response, the a_response_proc callback is called, in case of failure - a_response_error.
dap_client_get_stage_str
const char * dap_client_get_stage_str(dap_client_t * a_client)
Returns a text representation of the current stage of the a_client client.
dap_client_stage_str
const char * dap_client_stage_str(dap_client_stage_t a_stage)
Returns the text representation of the a_stage stage.
dap_client_get_stage_status_str
const char * dap_client_get_stage_status_str(dap_client_t * a_client)
Returns a textual representation of the current status of the a_client client stage.
dap_client_stage_status_str
const char * dap_client_stage_status_str(dap_client_stage_status_t a_stage_status)
Returns a textual representation of the status of the a_stage stage.
dap_client_error_str
const char * dap_client_error_str(dap_client_error_t a_client_error)
Returns a text representation of the a_client_error error.
dap_client_get_error_str
const char * dap_client_get_error_str(dap_client_t * a_client)
Returns a textual representation of the a_client client error.
dap_client_from_esocket
dap_client_t * dap_client_from_esocket(dap_events_socket_t * a_esocket);
Returns a pointer to a dap_client_t structure for the given e-socket.
dap_client_get_auth_cookie
const char * dap_client_get_auth_cookie(dap_client_t * a_client)
Returns the authorization cookie (if any).
dap_client_get_stream
dap_stream_t * dap_client_get_stream(dap_client_t * a_client)
Returns a pointer to the dap_stream_t streaming connection (if set).
dap_client_get_stream_worker
dap_stream_worker_t * dap_client_get_stream_worker(dap_client_t * a_client)
Returns a pointer to the I/O reactor handler thread inheritor corresponding to this client. This object is initialized automatically for each handler thread and is used for thread-safe functions that work with stream channels.
dap_client_get_stream_ch_unsafe
dap_stream_ch_t * dap_client_get_stream_ch_unsafe(dap_client_t * a_client, uint8_t a_ch_id)
Returns a pointer to the stream channel with id a_ch_id corresponding to the a_client client.
dap_client_get_stream_id
const char * dap_client_get_stream_id(dap_client_t * a_client)
Returns the stream session ID.
dap_client_set_active_channels_unsafe
void dap_client_set_active_channels_unsafe (dap_client_t * a_client, const char * a_active_channels)
Sets the list of active channels for this client.
dap_client_set_auth_cert_unsafe
void dap_client_set_auth_cert_unsafe(dap_client_t * a_client, dap_cert_t *a_cert)
Sets the certificate that will be used to sign the public keys during the initial public key exchange.
dap_client_get_stage
dap_client_stage_t dap_client_get_stage(dap_client_t * a_client)
Returns the current stage.
dap_client_get_stage_status
dap_client_stage_status_t dap_client_get_stage_status(dap_client_t * a_client)
Returns the status of the current stage.
dap_client_get_is_always_reconnect
bool dap_client_get_is_always_reconnect(dap_client_t * a_client);
Returns a boolean value indicating whether to reconnect even if the number of connection attempts has been exhausted.
dap_client_set_is_always_reconnect
void dap_client_set_is_always_reconnect(dap_client_t * a_client, bool a_value);
Sets the value of a boolean variable that specifies whether to reconnect even if the number of connection attempts has been exhausted.
dap_client_http.h, dap_client_http.c
Ordinary HTTP client for ordinary HTTP requests.
dap_client_http_callback_error_t
Error handling callback.
dap_client_http_callback_error_ext_t
Extended error handling callback.
dap_client_http_callback_data_t
Callback for client-specific http operations.
dap_client_http_init
int dap_client_http_init();
Initialize the HTTP client module.
dap_client_http_deinit
void dap_client_http_deinit();
Deinitialization of the HTTP client module.
dap_client_http_get_connect_timeout_ms
uint64_t dap_client_http_get_connect_timeout_ms();
Get connection waiting timeout.
dap_client_http_set_connect_timeout_ms
void dap_client_http_set_connect_timeout_ms(uint64_t a_timeout_ms);
Set connection waiting timeout.
dap_client_http_request_custom
dap_client_http_request_custom(dap_worker_t * a_worker, const char *a_uplink_addr, uint16_t a_uplink_port, const char *a_method, const char *a_request_content_type, const char * a_path, const void *a_request, size_t a_request_size, char *a_cookie, dap_client_http_callback_data_t a_response_callback, dap_client_http_callback_error_t a_error_callback, void *a_obj, char *a_custom, bool a_over_ssl);
Forming and sending an http request a_request to the node a_uplink_addr, along the path a_path, to the port a_uplink_port. Request method (type) - a_method; a_worker is the I/O reactor worker thread assigned to the client; a_error_callback is the error handling callback, a_obj is the argument to this callback; a_cookie - cookies, if applicable. The a_over_ssl argument determines whether SSL encryption of the connection data will be applied.
dap_client_http_request
dap_client_http_request(dap_worker_t * a_worker, const char *a_uplink_addr, uint16_t a_uplink_port, const char * a_method, const char* a_request_content_type, const char * a_path, const void *a_request, size_t a_request_size, char * a_cookie, dap_client_http_callback_data_t a_response_callback, dap_client_http_callback_error_t a_error_callback, void *a_obj, void * a_custom);
Same as the previous function, but without the possibility of using SSL.
dap_client_pvt.h, dap_client_pvt.c, dap_client_pvt_hh.c
dap_client_pvt_t
Internal (private) client data structure.
dap_client_pvt_init
int dap_client_pvt_init();
Initialize the module.
dap_client_pvt_deinit
void dap_client_pvt_deinit();
Deinitialize the module.
dap_client_pvt_stage_transaction_begin
void dap_client_pvt_stage_transaction_begin(dap_client_pvt_t * a_client_internal, dap_client_stage_t a_stage_next, dap_client_callback_t a_done_callback);
Start executing and work out the next stage a_stage_next of the DAP connection for the client specified by the dap_client_pvt_t structure pointed to by a_client_internal. The a_done_callback callback will be executed at the end of this stage.
dap_client_pvt_request
int dap_client_pvt_request(dap_client_pvt_t * a_client_internal, const char * a_path, void * a_request, size_t a_request_size, dap_client_callback_data_size_t a_response_proc, dap_client_callback_int_t a_response_error);
Make an HTTP request to a remote host, without encryption. The host address and port are contained in the uplink_addr and uplink_port fields of the a_client_internal structure. The path on the remote host is specified in a_path. Request body and size: a_request, a_request_size. In case of a successful response, the a_response_proc callback is called, in case of failure - a_response_error.
dap_client_pvt_request_enc
void dap_client_pvt_request_enc(dap_client_pvt_t * a_client_internal, const char * a_path, const char * a_sub_url, const char * a_query, void * a_request, size_t a_request_size, dap_client_callback_data_size_t a_response_proc, dap_client_callback_int_t a_error_proc);
Make an encrypted HTTP request to the a_client_internal client remote host . The path on the remote host is specified in a_path and a_suburl, the HTTP request field is in a_query, and the encrypted request body and its size are in a_request and a_request_size. In case of a successful response, the a_response_proc callback is called, in case of failure - a_error_proc.
dap_client_pvt_new
void dap_client_pvt_new(dap_client_pvt_t * a_client_internal);
Create and initialize a new structure dap_client_pvt_t.
dap_client_pvt_delete
void dap_client_pvt_delete(dap_client_pvt_t * a_client_pvt);
Removing the dap_client_pvt_t structure with the release of memory from under all its elements.
dap_client_pvt_hh_add_unsafe
int dap_client_pvt_hh_add_unsafe(dap_client_pvt_t* a_client_pvt);
Adding the structure dap_client_pvt_t to the uthash hash table.
dap_client_pvt_hh_del_unsafe
int dap_client_pvt_hh_del_unsafe(dap_client_pvt_t *a_client_pvt);
Removing the structure dap_client_pvt_t from the hash table.
dap_client_pvt_find
dap_client_pvt_t *dap_client_pvt_find(uint64_t a_client_pvt_uuid);
Lookup the structure dap_client_pvt_t in the hash table by its uuid identifier.