Types (structs, unions and typedefs)

typedef ptrdiff_t dwnx_ssize: dwnx_ssize is signed counterpart of size_t.

typedef void *(*dwnx_malloc)(size_t size, void *user_data): dwnx_malloc is a custom memory allocator to replace malloc(3). The user_data is dwnx_mem.user_data.

typedef void (*dwnx_free)(void *ptr, void *user_data): dwnx_free is a custom memory allocator to replace free(3). The user_data is dwnx_mem.user_data.

typedef void *(*dwnx_calloc)(size_t nmemb, size_t size, void *user_data): dwnx_calloc is a custom memory allocator to replace calloc(3). The user_data is the dwnx_mem.user_data.

typedef void *(*dwnx_realloc)(void *ptr, size_t size, void *user_data): dwnx_realloc is a custom memory allocator to replace realloc(3). The user_data is the dwnx_mem.user_data.

type dwnx_mem

dwnx_mem is a custom memory allocator. The 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 malloc(3), free(3), calloc(3) and 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,
  };

  ...
}

void *user_data: user_data is an arbitrary user supplied data. This is passed to each allocator function.

dwnx_malloc malloc: malloc is a custom allocator function to replace malloc(3).

dwnx_free free: free is a custom allocator function to replace free(3).

dwnx_calloc calloc: calloc is a custom allocator function to replace calloc(3).

dwnx_realloc realloc: realloc is a custom allocator function to replace realloc(3).

type dwnx_vec

dwnx_vec is struct iovec compatible structure to reference arbitrary array of bytes.

uint8_t *base: base points to the data.

size_t len: len is the number of bytes which the buffer pointed by base contains.

typedef uint64_t dwnx_tstamp: 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.

typedef uint64_t dwnx_duration: 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

dwnx_transport_params represents QUIC transport parameters.

uint64_t initial_max_stream_data_bidi_local: 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.

uint64_t initial_max_stream_data_bidi_remote: 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.

uint64_t initial_max_stream_data_uni: 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.

uint64_t initial_max_data: initial_max_data is the connection level flow control window.

uint64_t initial_max_streams_bidi: initial_max_streams_bidi is the number of concurrent streams that the remote endpoint can create.

uint64_t initial_max_streams_uni: initial_max_streams_uni is the number of concurrent unidirectional streams that the remote endpoint can create.

dwnx_duration max_idle_timeout: max_idle_timeout is a duration during which sender allows quiescent. 0 means no idle timeout. It must not be UINT64_MAX.

uint64_t max_record_size: max_record_size is the maximum QMux record size that the sender accepts. It must be greater than or equal to DWNX_DEFAULT_MAX_RECORD_SIZE.

type dwnx_conn: dwnx_conn represents a single QMux connection.

typedef void (*dwnx_log_write)(void *user_data, char *msg, size_t len): 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

dwnx_settings defines QMux connection settings.

uint64_t conn_id: 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.

dwnx_tstamp initial_ts: initial_ts is an initial timestamp given to the library.

dwnx_log_write log_write: log_write is the callback function when a single log message is emitted. If this field is NULL, logging is disabled.

typedef int (*dwnx_recv_transport_params)(dwnx_conn *conn, const dwnx_transport_params *params, void *user_data)

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 DWNX_ERR_CALLBACK_FAILURE which makes the library return immediately.

typedef 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)

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 DWNX_STREAM_DATA_FLAG_*. If flags & 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 DWNX_ERR_CALLBACK_FAILURE which makes the library return immediately.

typedef int (*dwnx_stream_open)(dwnx_conn *conn, int64_t stream_id, void *user_data)

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 DWNX_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

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 DWNX_STREAM_CLOSE_FLAG_*. rx_app_error_code indicates the error code that shut down the receiving side of the stream if 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 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 DWNX_STREAM_CLOSE_FLAG_TX_APP_ERROR_CODE_SET is set in flags. Meanwhile, the client receives the response body without any error. Then 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 DWNX_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

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 DWNX_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*dwnx_stream_stop_sending)(dwnx_conn *conn, int64_t stream_id, uint64_t app_error_code, void *user_data, void *stream_user_data)

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 DWNX_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*dwnx_recv_stop_sending)(dwnx_conn *conn, int64_t stream_id, uint64_t app_error_code, void *user_data, void *stream_user_data)

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 DWNX_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*dwnx_extend_max_stream_data)(dwnx_conn *conn, int64_t stream_id, uint64_t max_data, void *user_data, void *stream_user_data)

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 DWNX_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*dwnx_extend_max_streams)(dwnx_conn *conn, uint64_t max_streams, void *user_data)

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 DWNX_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef void (*dwnx_rand)(uint8_t *dest, size_t destlen): 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

dwnx_callbacks holds a set of callback functions.

dwnx_rand rand: rand is a callback function which is invoked when the library needs random data. This callback function must be specified.

dwnx_recv_transport_params recv_transport_params: recv_transport_params is a callback function which is invoked when transport parameters are received from the remote endpoint.

dwnx_recv_stream_data recv_stream_data: recv_stream_data is a callback function which is invoked when stream data, which includes application data, is received. This callback function is optional.

dwnx_stream_open stream_open: stream_open is a callback function which is invoked when new remote stream is opened by a remote endpoint. This callback function is optional.

dwnx_stream_close stream_close: stream_close is a callback function which is invoked when a stream is closed. This callback function is optional.

dwnx_stream_reset stream_reset: stream_reset is a callback function which is invoked when a stream is reset by a remote endpoint. This callback function is optional.

dwnx_stream_stop_sending stream_stop_sending: 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.

dwnx_recv_stop_sending recv_stop_sending: 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.

dwnx_extend_max_stream_data extend_max_stream_data: 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.

dwnx_extend_max_streams extend_max_local_streams_bidi: 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.

dwnx_extend_max_streams extend_max_local_streams_uni: 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.

dwnx_extend_max_streams extend_max_remote_streams_bidi: 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.

dwnx_extend_max_streams extend_max_remote_streams_uni: 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

dwnx_ccerr contains connection error code, its type, a frame type that caused this error, and the optional reason phrase.

dwnx_ccerr_type type: type is the type of this error.

uint64_t error_code: error_code is the error code for connection closure. Its interpretation depends on type.

uint64_t frame_type: 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.

const uint8_t *reason: 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.

size_t reasonlen: reasonlen is the length of data pointed by reason.