Types (structs, unions and typedefs) ==================================== .. type:: ptrdiff_t dwnx_ssize :type:`dwnx_ssize` is signed counterpart of size_t. .. type:: void *(*dwnx_malloc)(size_t size, void *user_data) :type:`dwnx_malloc` is a custom memory allocator to replace :manpage:`malloc(3)`. The *user_data* is :member:`dwnx_mem.user_data`. .. type:: void (*dwnx_free)(void *ptr, void *user_data) :type:`dwnx_free` is a custom memory allocator to replace :manpage:`free(3)`. The *user_data* is :member:`dwnx_mem.user_data`. .. type:: void *(*dwnx_calloc)(size_t nmemb, size_t size, void *user_data) :type:`dwnx_calloc` is a custom memory allocator to replace :manpage:`calloc(3)`. The *user_data* is the :member:`dwnx_mem.user_data`. .. type:: void *(*dwnx_realloc)(void *ptr, size_t size, void *user_data) :type:`dwnx_realloc` is a custom memory allocator to replace :manpage:`realloc(3)`. The *user_data* is the :member:`dwnx_mem.user_data`. .. type:: dwnx_mem :type:`dwnx_mem` is a custom memory allocator. The :member:`user_data` field is passed to each allocator function. This can be used, for example, to achieve per-connection memory pool. In the following example code, ``my_malloc``, ``my_free``, ``my_calloc`` and ``my_realloc`` are the replacement of the standard allocators :manpage:`malloc(3)`, :manpage:`free(3)`, :manpage:`calloc(3)` and :manpage:`realloc(3)` respectively:: void *my_malloc_cb(size_t size, void *user_data) { (void)user_data; return my_malloc(size); } void my_free_cb(void *ptr, void *user_data) { (void)user_data; my_free(ptr); } void *my_calloc_cb(size_t nmemb, size_t size, void *user_data) { (void)user_data; return my_calloc(nmemb, size); } void *my_realloc_cb(void *ptr, size_t size, void *user_data) { (void)user_data; return my_realloc(ptr, size); } void conn_new() { dwnx_mem mem = { .malloc = my_malloc_cb, .free = my_free_cb, .calloc = my_calloc_cb, .realloc = my_realloc_cb, }; ... } .. member:: void *user_data :member:`user_data` is an arbitrary user supplied data. This is passed to each allocator function. .. member:: dwnx_malloc malloc :member:`malloc` is a custom allocator function to replace :manpage:`malloc(3)`. .. member:: dwnx_free free :member:`free` is a custom allocator function to replace :manpage:`free(3)`. .. member:: dwnx_calloc calloc :member:`calloc` is a custom allocator function to replace :manpage:`calloc(3)`. .. member:: dwnx_realloc realloc :member:`realloc` is a custom allocator function to replace :manpage:`realloc(3)`. .. type:: dwnx_vec :type:`dwnx_vec` is struct iovec compatible structure to reference arbitrary array of bytes. .. member:: uint8_t *base :member:`base` points to the data. .. member:: size_t len :member:`len` is the number of bytes which the buffer pointed by base contains. .. type:: uint64_t dwnx_tstamp :type:`dwnx_tstamp` is a timestamp with nanosecond resolution. ``UINT64_MAX`` is an invalid value, and it is often used to indicate that no value is set. .. type:: uint64_t dwnx_duration :type:`dwnx_duration` is a period of time in nanosecond resolution. ``UINT64_MAX`` is an invalid value, and it is often used to indicate that no value is set. .. type:: dwnx_transport_params :type:`dwnx_transport_params` represents QUIC transport parameters. .. member:: uint64_t initial_max_stream_data_bidi_local :member:`initial_max_stream_data_bidi_local` is the size of flow control window of locally initiated stream. This is the number of bytes that the remote endpoint can send, and the local endpoint must ensure that it has enough buffer to receive them. .. member:: uint64_t initial_max_stream_data_bidi_remote :member:`initial_max_stream_data_bidi_remote` is the size of flow control window of remotely initiated stream. This is the number of bytes that the remote endpoint can send, and the local endpoint must ensure that it has enough buffer to receive them. .. member:: uint64_t initial_max_stream_data_uni :member:`initial_max_stream_data_uni` is the size of flow control window of remotely initiated unidirectional stream. This is the number of bytes that the remote endpoint can send, and the local endpoint must ensure that it has enough buffer to receive them. .. member:: uint64_t initial_max_data :member:`initial_max_data` is the connection level flow control window. .. member:: uint64_t initial_max_streams_bidi :member:`initial_max_streams_bidi` is the number of concurrent streams that the remote endpoint can create. .. member:: uint64_t initial_max_streams_uni :member:`initial_max_streams_uni` is the number of concurrent unidirectional streams that the remote endpoint can create. .. member:: dwnx_duration max_idle_timeout :member:`max_idle_timeout` is a duration during which sender allows quiescent. 0 means no idle timeout. It must not be UINT64_MAX. .. member:: uint64_t max_record_size :member:`max_record_size` is the maximum QMux record size that the sender accepts. It must be greater than or equal to :macro:`DWNX_DEFAULT_MAX_RECORD_SIZE`. .. type:: dwnx_conn :type:`dwnx_conn` represents a single QMux connection. .. type:: void (*dwnx_log_write)(void *user_data, char *msg, size_t len) :type:`dwnx_log_write` is a callback function for logging. *user_data* is the same object passed to `dwnx_conn_client_new` or `dwnx_conn_server_new`. The caller guarantees that the memory region [*msg*, *msg* + *len*], inclusive, are writable, and *msg*[*len*] == '\0'. If application needs to emit a single line with a line terminator, one can do msg[len] = '\n', and write *len* + 1 bytes from *msg*. .. type:: dwnx_settings :type:`dwnx_settings` defines QMux connection settings. .. member:: uint64_t conn_id :member:`conn_id` is the identifier of this connection. Currently, it is used in a log header so that people can distinguish the particular connection from the others. .. member:: dwnx_tstamp initial_ts :member:`initial_ts` is an initial timestamp given to the library. .. member:: dwnx_log_write log_write :member:`log_write` is the callback function when a single log message is emitted. If this field is NULL, logging is disabled. .. type:: int (*dwnx_recv_transport_params)(dwnx_conn *conn, const dwnx_transport_params *params, void *user_data) :type:`dwnx_recv_transport_params` is invoked when transport parameters *params* are received from the remote endpoint. The callback function must return 0 if it succeeds, or :macro:`DWNX_ERR_CALLBACK_FAILURE` which makes the library return immediately. .. type:: int (*dwnx_recv_stream_data)(dwnx_conn *conn, uint32_t flags, int64_t stream_id, uint64_t offset, const uint8_t *data, size_t datalen, void *user_data, void *stream_user_data) :type:`dwnx_recv_stream_data` is invoked when stream data is received. The stream is specified by *stream_id*. *flags* is the bitwise-OR of zero or more of :macro:`DWNX_STREAM_DATA_FLAG_* `. If *flags* & :macro:`DWNX_STREAM_DATA_FLAG_FIN` is nonzero, this portion of the data is the last data in this stream. *offset* is the offset where this data begins. The library ensures that data is passed to the application in the non-decreasing order of *offset* without any overlap. The data is passed as *data* of length *datalen*. *datalen* may be 0 if and only if *fin* is nonzero. The callback function must return 0 if it succeeds, or :macro:`DWNX_ERR_CALLBACK_FAILURE` which makes the library return immediately. .. type:: int (*dwnx_stream_open)(dwnx_conn *conn, int64_t stream_id, void *user_data) :type:`dwnx_stream_open` is a callback function which is called when remote stream is opened by a remote endpoint. This function is not called if stream is opened by implicitly (we might reconsider this behaviour later). The implementation of this callback should return 0 if it succeeds. Returning :macro:`DWNX_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*dwnx_stream_close)(dwnx_conn *conn, uint32_t flags, int64_t stream_id, uint64_t rx_app_error_code, uint64_t tx_app_error_code, void *user_data, void *stream_user_data) :type:`dwnx_stream_close` is invoked when a stream is closed. This callback is not called when QUIC connection is closed before existing streams are closed. *flags* is the bitwise-OR of zero or more of :macro:`DWNX_STREAM_CLOSE_FLAG_* `. *rx_app_error_code* indicates the error code that shut down the receiving side of the stream if :macro:`DWNX_STREAM_CLOSE_FLAG_RX_APP_ERROR_CODE_SET` is set in *flags*. *tx_app_error_code* indicates the error code that shut down the sending side of the stream if :macro:`DWNX_STREAM_CLOSE_FLAG_TX_APP_ERROR_CODE_SET` is set in *flags*. Because QUIC can close the send and receive sides of a stream independently, this callback has 2 application error codes for both directions. No error code means that its direction of a stream is closed cleanly. For example, a client gets STOP_SENDING frame from a server, and it sends back RESET_STREAM frame with the error code included in STOP_SENDING frame. This error code is reported as *tx_app_error_code* and :macro:`DWNX_STREAM_CLOSE_FLAG_TX_APP_ERROR_CODE_SET` is set in *flags*. Meanwhile, the client receives the response body without any error. Then :macro:`DWNX_STREAM_CLOSE_FLAG_RX_APP_ERROR_CODE_SET` is not set in *flags*. The implementation of this callback should return 0 if it succeeds. Returning :macro:`DWNX_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*dwnx_stream_reset)(dwnx_conn *conn, int64_t stream_id, uint64_t final_size, uint64_t app_error_code, void *user_data, void *stream_user_data) :type:`dwnx_stream_reset` is invoked when a stream identified by *stream_id* is reset by a remote endpoint. The implementation of this callback should return 0 if it succeeds. Returning :macro:`DWNX_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*dwnx_stream_stop_sending)(dwnx_conn *conn, int64_t stream_id, uint64_t app_error_code, void *user_data, void *stream_user_data) :type:`dwnx_stream_stop_sending` is invoked when a stream is no longer read by a local endpoint before it receives all stream data. This function is called at most once per stream. *app_error_code* is the error code passed to `dwnx_conn_shutdown_stream_read` or `dwnx_conn_shutdown_stream`. The callback function must return 0 if it succeeds. Returning :macro:`DWNX_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*dwnx_recv_stop_sending)(dwnx_conn *conn, int64_t stream_id, uint64_t app_error_code, void *user_data, void *stream_user_data) :type:`dwnx_recv_stop_sending` is invoked when a STOP_SENDING frame is received from a remote endpoint for a stream identified by *stream_id*. *app_error_code* is the application error code carried by the STOP_SENDING frame. This callback is called at most once per stream. The callback function must return 0 if it succeeds. Returning :macro:`DWNX_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*dwnx_extend_max_stream_data)(dwnx_conn *conn, int64_t stream_id, uint64_t max_data, void *user_data, void *stream_user_data) :type:`dwnx_extend_max_stream_data` is a callback function which is invoked when max stream data is extended. *stream_id* identifies the stream. *max_data* is a cumulative number of bytes an endpoint can send on this stream. The callback function must return 0 if it succeeds. Returning :macro:`DWNX_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*dwnx_extend_max_streams)(dwnx_conn *conn, uint64_t max_streams, void *user_data) :type:`dwnx_extend_max_streams` is a callback function which is called every time max stream ID is strictly extended. *max_streams* is the cumulative number of streams which an endpoint can open. The callback function must return 0 if it succeeds. Returning :macro:`DWNX_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: void (*dwnx_rand)(uint8_t *dest, size_t destlen) :type:`dwnx_rand` is a callback function which is invoked when unpredictable data of *destlen* bytes are needed. The implementation must write unpredictable data of *destlen* bytes into the buffer pointed by *dest*. .. type:: dwnx_callbacks :type:`dwnx_callbacks` holds a set of callback functions. .. member:: dwnx_rand rand :member:`rand` is a callback function which is invoked when the library needs random data. This callback function must be specified. .. member:: dwnx_recv_transport_params recv_transport_params :member:`recv_transport_params` is a callback function which is invoked when transport parameters are received from the remote endpoint. .. member:: dwnx_recv_stream_data recv_stream_data :member:`recv_stream_data` is a callback function which is invoked when stream data, which includes application data, is received. This callback function is optional. .. member:: dwnx_stream_open stream_open :member:`stream_open` is a callback function which is invoked when new remote stream is opened by a remote endpoint. This callback function is optional. .. member:: dwnx_stream_close stream_close :member:`stream_close` is a callback function which is invoked when a stream is closed. This callback function is optional. .. member:: dwnx_stream_reset stream_reset :member:`stream_reset` is a callback function which is invoked when a stream is reset by a remote endpoint. This callback function is optional. .. member:: dwnx_stream_stop_sending stream_stop_sending :member:`stream_stop_sending` is a callback function which is invoked when a local endpoint no longer reads from a stream before it receives all stream data. This callback function is optional. .. member:: dwnx_recv_stop_sending recv_stop_sending :member:`recv_stop_sending` is a callback function which is invoked when a STOP_SENDING frame is received from a remote endpoint. This callback function is optional. .. member:: dwnx_extend_max_stream_data extend_max_stream_data :member:`extend_max_stream_data` is callback function which is invoked when the maximum offset of stream data that a local endpoint can send is increased. This callback function is optional. .. member:: dwnx_extend_max_streams extend_max_local_streams_bidi :member:`extend_max_local_streams_bidi` is a callback function which is invoked when the number of bidirectional stream which a local endpoint can open is increased. This callback function is optional. .. member:: dwnx_extend_max_streams extend_max_local_streams_uni :member:`extend_max_local_streams_uni` is a callback function which is invoked when the number of unidirectional stream which a local endpoint can open is increased. This callback function is optional. .. member:: dwnx_extend_max_streams extend_max_remote_streams_bidi :member:`extend_max_remote_streams_bidi` is a callback function which is invoked when the number of bidirectional streams which a remote endpoint can open is increased. This callback function is optional. .. member:: dwnx_extend_max_streams extend_max_remote_streams_uni :member:`extend_max_remote_streams_uni` is a callback function which is invoked when the number of unidirectional streams which a remote endpoint can open is increased. This callback function is optional. .. type:: dwnx_ccerr :type:`dwnx_ccerr` contains connection error code, its type, a frame type that caused this error, and the optional reason phrase. .. member:: dwnx_ccerr_type type :member:`type` is the type of this error. .. member:: uint64_t error_code :member:`error_code` is the error code for connection closure. Its interpretation depends on :member:`type`. .. member:: uint64_t frame_type :member:`frame_type` is the type of QUIC frame which triggers this connection error. This field is set to 0 if the frame type is unknown. .. member:: const uint8_t *reason :member:`reason` points to the buffer which contains a reason phrase. It may be NULL if there is no reason phrase. If it is received from a remote endpoint, it is truncated to at most 1024 bytes. .. member:: size_t reasonlen :member:`reasonlen` is the length of data pointed by :member:`reason`.