Preconnection

Preconnection creation, configuration, and initiation. More...

Data Structures
struct	ct_preconnection_t
	Opaque handle representing a preconnection. More...

Functions
ct_preconnection_t *	ct_preconnection_new (const ct_local_endpoint_t *const *local_endpoints, size_t num_local_endpoints, const ct_remote_endpoint_t *const *remote_endpoints, size_t num_remote_endpoints, const ct_transport_properties_t *transport_properties, const ct_security_parameters_t *security_parameters)
	Create a new preconnection with transport properties and endpoints.
void	ct_preconnection_free (ct_preconnection_t *preconnection)
	Free a preconnection object.
int	ct_preconnection_set_framer (ct_preconnection_t *preconnection, const ct_framer_impl_t *framer_impl)
	Set a message framer for the preconnection.
int	ct_preconnection_initiate (const ct_preconnection_t *preconnection, const ct_connection_callbacks_t *connection_callbacks)
	Initiate a connection.
int	ct_preconnection_initiate_with_send (const ct_preconnection_t *preconnection, const ct_connection_callbacks_t *connection_callbacks, const ct_message_t *message, const ct_message_context_t *message_context)
	Initiate a connection and send a message immediately upon establishment.
int	ct_preconnection_listen (const ct_preconnection_t *preconnection, const ct_listener_callbacks_t *listener_callbacks, const ct_connection_callbacks_t *connection_callbacks)
	Start listening for incoming connections using the configured Preconnection.

Detailed Description

Preconnection creation, configuration, and initiation.

Function Documentation

ct_preconnection_free()

void ct_preconnection_free

(

ct_preconnection_t *

preconnection

)

Free a preconnection object.

Releases all resources associated with the preconnection object,

Parameters

[in]

preconnection

Pointer to preconnection to free. Does nothing if NULL.

ct_preconnection_initiate()

int ct_preconnection_initiate	(	const ct_preconnection_t *	preconnection,
		const ct_connection_callbacks_t *	connection_callbacks
	)

Initiate a connection.

Initiates a connection using the configured Preconnection. The connection is allocated internally and provided to the user via the ready() callback.

CTaps does not take ownership of the passed preconnection pointer, so it can be safely freed after return.

CTaps does not take ownership of the passed connection_callbacks pointer, so it can be safely freed after return.

Parameters

[in]	preconnection	Pointer to the Preconnection object containing the connection configuration.
[in]	connection_callbacks	Struct containing callback functions for connection events:

Returns

0 on success, negative error code on synchronous failure

Note

Asynchronous errors are reported via the establishment_error callback

ct_preconnection_initiate_with_send()

int ct_preconnection_initiate_with_send	(	const ct_preconnection_t *	preconnection,
		const ct_connection_callbacks_t *	connection_callbacks,
		const ct_message_t *	message,
		const ct_message_context_t *	message_context
	)

Initiate a connection and send a message immediately upon establishment.

Initiates a connection using the configured Preconnection. The connection is allocated internally and provided to the user via the ready() callback. If the underlying protocol supports 0-RTT or early data, the message may be sent during the handshake. Otherwise the data will be sent immediately after establishment.

CTaps does not take ownership of any passed pointer, so they can all be safely freed after this connection returns.

Parameters

[in]	preconnection	Pointer to the Preconnection object containing the connection configuration.
[in]	connection_callbacks	Struct containing callback functions for connection events:

Returns

0 on success, negative error code on synchronous failure

Note

Asynchronous errors are reported via the establishment_error callback

the message context must have the MSG_SAFELY_REPLAYABLE property set to make use of 0-RTT

ct_preconnection_listen()

int ct_preconnection_listen	(	const ct_preconnection_t *	preconnection,
		const ct_listener_callbacks_t *	listener_callbacks,
		const ct_connection_callbacks_t *	connection_callbacks
	)

Start listening for incoming connections using the configured Preconnection.

CTaps does not take ownership of any passed pointer, so they can all be safely freed after this connection returns.

Parameters

[in]	preconnection	Pointer to preconnection with listener configuration
[in]	listener_callbacks	Callbacks for listener events (ready, connection_received, etc.)
[in]	connection_callbacks	Callbacks for connection events on accepted connections

Returns

0 on success, negative error code on synchronous failure

See also

ct_listener_close() to stop accepting new connections

ct_preconnection_new()

ct_preconnection_t * ct_preconnection_new	(	const ct_local_endpoint_t *const *	local_endpoints,
		size_t	num_local_endpoints,
		const ct_remote_endpoint_t *const *	remote_endpoints,
		size_t	num_remote_endpoints,
		const ct_transport_properties_t *	transport_properties,
		const ct_security_parameters_t *	security_parameters
	)

Create a new preconnection with transport properties and endpoints.

Allocates and initializes a new preconnection object on the heap. The returned object must be freed with ct_preconnection_free().

Takes deep copies of all passed endpoints and transport/security parameters. The caller can therefore safely free or reuse the original parameters after this function returns.

Parameters

[in]	local_endpoints	Array of local endpoints to bind to, or NULL
[in]	num_local_endpoints	Number of local endpoints (0 if local_endpoints is NULL)
[in]	remote_endpoints	Array of remote endpoints to connect to, or NULL
[in]	num_remote_endpoints	Number of remote endpoints (0 if remote_endpoints is NULL)
[in]	transport_properties	Transport property preferences, or NULL for defaults
[in]	security_parameters	Security configuration (TLS/QUIC), or NULL

Returns

Pointer to newly allocated preconnection, or NULL on allocation failure

ct_preconnection_set_framer()

int ct_preconnection_set_framer	(	ct_preconnection_t *	preconnection,
		const ct_framer_impl_t *	framer_impl
	)

Set a message framer for the preconnection.

CTaps does not take ownership of the passed framer pointer, so it can be safely freed after return.

Parameters

[in,out]	preconnection	Preconnection to modify
[in]	framer_impl	Framer implementation to use, or NULL for no framing

Returns

0 on success, negative error code on failure