Connection lifecycle, state queries, cloning, and group management. More...

Data Structures
struct	ct_receive_callbacks_t
	Callback functions for receiving messages on a connection. More...

struct	ct_connection_callbacks_t
	Callback functions for connection lifecycle events. More...

struct	ct_connection_t
	Opaque handle representing a connection. More...

Enumerations
enum	ct_protocol_enum_t { CT_PROTOCOL_ERROR = -1 , CT_PROTOCOL_TCP , CT_PROTOCOL_UDP , CT_PROTOCOL_QUIC }
	Enumeration of currently supported transport protocols. More...

Functions
int	ct_send_message (ct_connection_t connection, const ct_message_t message)
	Send a message over a connection with default properties.

int	ct_send_message_full (ct_connection_t connection, const ct_message_t message, const ct_message_context_t *message_context)
	Send a message with custom message context and properties.

int	ct_receive_message (ct_connection_t connection, const ct_receive_callbacks_t receive_callbacks)
	Register callbacks to receive messages on a connection.

const ct_transport_properties_t *	ct_connection_get_transport_properties (const ct_connection_t *connection)
	Get shared connection properties for a connection.

uint8_t	ct_connection_get_priority (const ct_connection_t *connection)
	Get relative priority when compared to other connections in the same group.

int	ct_connection_set_priority (ct_connection_t *connection, uint8_t priority)
	Set relative priority for a connection compared to other connections in the same group.

void *	ct_connection_get_callback_context (const ct_connection_t *connection)
	Get the connection's callback context.

const char *	ct_connection_get_uuid (const ct_connection_t *connection)
	Get the UUID of a connection.

const char *	ct_connection_get_protocol_name (const ct_connection_t *connection)
	Get the name of the underlying protocol.

const ct_remote_endpoint_t *	ct_connection_get_active_remote_endpoint (const ct_connection_t *connection)
	Get the currently active remote endpoint for the connection.

const ct_local_endpoint_t *	ct_connection_get_active_local_endpoint (const ct_connection_t *connection)
	Get the currently active local endpoint.

ct_connection_state_enum_t	ct_connection_get_state (const ct_connection_t *connection)
	Get the current state of a connection.

bool	ct_connection_is_closed (const ct_connection_t *connection)
	Check if a connection's state is CT_CONN_STATE_CLOSED.

bool	ct_connection_is_established (const ct_connection_t *connection)
	Check if a connection's state is CT_CONN_STATE_ESTABLISHED.

bool	ct_connection_is_establishing (const ct_connection_t *connection)
	Check if a connection's state is CT_CONN_STATE_ESTABLISHING.

bool	ct_connection_is_closing (const ct_connection_t *connection)
	Check if a connection's state is CT_CONN_STATE_CLOSING.

bool	ct_connection_is_closed_or_closing (const ct_connection_t *connection)
	Check if a connection's state is CT_CONN_STATE_CLOSED or CT_CONN_STATE_CLOSING.

bool	ct_connection_is_client (const ct_connection_t *connection)
	Check if a connection is a client connection.

bool	ct_connection_is_server (const ct_connection_t *connection)
	Check if a connection is a server connection.

bool	ct_connection_can_send (const ct_connection_t *connection)
	Check the value of the canSend connection property.

bool	ct_connection_can_receive (const ct_connection_t *connection)
	Check the value of the canReceive connection property.

void	ct_connection_free (ct_connection_t *connection)
	Free resources in a connection.

void	ct_connection_close (ct_connection_t *connection)
	Close a connection gracefully.

void	ct_connection_abort (ct_connection_t *connection)
	Forcefully abort a connection without graceful shutdown.

int	ct_connection_clone_full (const ct_connection_t source_connection, const ct_framer_impl_t framer, const ct_transport_properties_t *connection_properties)
	Clone a connection to create a new connection in the same connection group.

int	ct_connection_clone (ct_connection_t *source_connection)
	Clone a connection with only mandatory parameters.

size_t	ct_connection_get_total_num_grouped_connections (const ct_connection_t *connection)
	Get the total number of connections in a connection group (including closed ones).

size_t	ct_connection_get_num_open_grouped_connections (const ct_connection_t *connection)
	Get the number of open connections in a connection group.

void	ct_connection_close_group (ct_connection_t *connection)
	Close all connections in the same connection group gracefully.

void	ct_connection_abort_group (ct_connection_t *connection)
	Forcefully abort all connections in the same connection group.

ct_protocol_enum_t	ct_connection_get_transport_protocol (const ct_connection_t *connection)
	Get the transport protocol used by a connection.

bool	ct_connection_sent_early_data (const ct_connection_t *connection)
	Check if a connection has sent early data (e.g., 0-RTT).

Detailed Description

Connection lifecycle, state queries, cloning, and group management.

Enumeration Type Documentation

◆ ct_protocol_enum_t

enum ct_protocol_enum_t

Enumeration of currently supported transport protocols.

Enumerator
CT_PROTOCOL_ERROR	returned from getters in errors, e.g. null connection
CT_PROTOCOL_TCP
CT_PROTOCOL_UDP
CT_PROTOCOL_QUIC

Definition at line 1768 of file ctaps.h.

Function Documentation

◆ ct_connection_abort()

void ct_connection_abort ( ct_connection_t * connection )

Forcefully abort a connection without graceful shutdown.

Unlike ct_connection_close() which performs a graceful shutdown (e.g., FIN), this immediately terminates the connection (e.g., RST). Use when an error condition requires immediate termination.

Parameters

[in] connection Connection to abort

◆ ct_connection_abort_group()

void ct_connection_abort_group ( ct_connection_t * connection )

Forcefully abort all connections in the same connection group.

Immediately terminates all connections in the group without graceful shutdown. This is equivalent to calling ct_connection_abort() on each connection in the group.

Parameters

[in] connection Any connection in the group to abort

◆ ct_connection_can_receive()

bool ct_connection_can_receive ( const ct_connection_t * connection )

Check the value of the canReceive connection property.

Parameters

[in] connection The connection to check

Returns: false if connection is NULL or if canReceive is false.

◆ ct_connection_can_send()

bool ct_connection_can_send ( const ct_connection_t * connection )

Check the value of the canSend connection property.

Parameters

[in] connection The connection to check

Returns: false if connection is NULL or if canSend is false.

◆ ct_connection_clone()

int ct_connection_clone ( ct_connection_t * source_connection )

Clone a connection with only mandatory parameters.

See also: ct_connection_clone_full

◆ ct_connection_clone_full()

int ct_connection_clone_full	(	const ct_connection_t *	source_connection,
		const ct_framer_impl_t *	framer,
		const ct_transport_properties_t *	connection_properties
	)

Clone a connection to create a new connection in the same connection group.

Creates a new connection that shares the same transport session as the parent connection. This enables a multi-streaming protocols like QUIC to create multiple logical connections (streams) over a single transport session.

The callbacks of the source connection are copied into the cloned connection. The ready callback is invoked with the cloned connection as a parameter, when connection succeeds.

Note: The cloned connection will share callbacks with the source connection. When the clone is ready, it will invoke the source connection's ready callback with the cloned connection as a parameter.

Parameters

[in]	source_connection	The connection to clone
[in]	framer	Optional framer for the cloned connection (NULL to inherit)
[in]	connection_properties	Optional properties for cloned connection (Not implemented)

Returns: 0 on success, negative error code on failure

◆ ct_connection_close()

void ct_connection_close ( ct_connection_t * connection )

Close a connection gracefully.

Exact behaviour depends on the underlying transport protocol. For TCP, this performs a graceful shutdown (e.g., FIN). For UDP this simply stops further sends and receives and closes the socket. For QUIC it closes the connection, if the connection it is invoked on is the last open connection in the connection group. Otherwise it closes the connection one way (sending a FIN), stopping sending but allowing receives to continue until the remote also closes.

Parameters

[in] connection Connection to close

◆ ct_connection_close_group()

void ct_connection_close_group ( ct_connection_t * connection )

Close all connections in the same connection group gracefully.

Performs graceful shutdown of all connections in the group (the connection and all its clones). This is equivalent to calling ct_connection_close() on each connection in the group.

Parameters

[in] connection Any connection in the group to close

◆ ct_connection_free()

void ct_connection_free ( ct_connection_t * connection )

Free resources in a connection.

Parameters

[in] connection Connection to free

◆ ct_connection_get_active_local_endpoint()

const ct_local_endpoint_t * ct_connection_get_active_local_endpoint ( const ct_connection_t * connection )

Get the currently active local endpoint.

Parameters

[in] connection connection to get local endpoint for

Returns: Pointer to endpoint, NULL if connection is NULL

◆ ct_connection_get_active_remote_endpoint()

const ct_remote_endpoint_t * ct_connection_get_active_remote_endpoint ( const ct_connection_t * connection )

Get the currently active remote endpoint for the connection.

Parameters

[in] connection connection to get remote endpoint for

Returns: Pointer to endpoint, NULL if connection is NULL

◆ ct_connection_get_callback_context()

void * ct_connection_get_callback_context ( const ct_connection_t * connection )

Get the connection's callback context.

Parameters

[in] connection connection to get callback context for

Returns: Void pointer assigned to callback context null if connection is null or it hasn't been set

◆ ct_connection_get_num_open_grouped_connections()

size_t ct_connection_get_num_open_grouped_connections ( const ct_connection_t * connection )

Get the number of open connections in a connection group.

Parameters

[in] connection The connection to query

Returns: The number of open (non-closed) connections in the group

◆ ct_connection_get_priority()

uint8_t ct_connection_get_priority ( const ct_connection_t * connection )

Get relative priority when compared to other connections in the same group.

Lower values are higher priority.

Defaults to 100.

Returns: Priority value, or UINT8_MAX if connection is NULL

◆ ct_connection_get_protocol_name()

const char * ct_connection_get_protocol_name ( const ct_connection_t * connection )

Get the name of the underlying protocol.

Parameters

[in] connection connection to get protocol name for

Returns: Pointer to protocol name, NULL if connection is NULL

◆ ct_connection_get_state()

ct_connection_state_enum_t ct_connection_get_state ( const ct_connection_t * connection )

Get the current state of a connection.

Parameters

[in] connection The connection to query

Returns: connection lifecycle state, -1 if connection is NULL

◆ ct_connection_get_total_num_grouped_connections()

size_t ct_connection_get_total_num_grouped_connections ( const ct_connection_t * connection )

Get the total number of connections in a connection group (including closed ones).

Parameters

[in] connection The connection to query

Returns: The total number of connections in the group

◆ ct_connection_get_transport_properties()

const ct_transport_properties_t * ct_connection_get_transport_properties ( const ct_connection_t * connection )

Get shared connection properties for a connection.

Parameters

[in] connection The connection to query

Returns: pointer to transport properties shared with connections in the same connection group, or NULL if connection is NULL

◆ ct_connection_get_transport_protocol()

ct_protocol_enum_t ct_connection_get_transport_protocol ( const ct_connection_t * connection )

Get the transport protocol used by a connection.

Parameters

[in] connection The connection to query

Returns: The transport protocol enum value, or CT_PROTOCOL_ERROR if protocol cannot be determined

◆ ct_connection_get_uuid()

const char * ct_connection_get_uuid ( const ct_connection_t * connection )

Get the UUID of a connection.

Parameters

[in] connection connection to get uuid for

Returns: Pointer to uuid string

◆ ct_connection_is_client()

bool ct_connection_is_client ( const ct_connection_t * connection )

Check if a connection is a client connection.

Parameters

[in] connection The connection to check

Returns: true if connection role matches, false otherwise, including if connection is NULL

◆ ct_connection_is_closed()

bool ct_connection_is_closed ( const ct_connection_t * connection )

Check if a connection's state is CT_CONN_STATE_CLOSED.

See also: ct_connection_get_state() for a generic getter

Parameters

[in] connection The connection to check

Returns: true if connection is closed, false if open or connection is NULL

◆ ct_connection_is_closed_or_closing()

bool ct_connection_is_closed_or_closing ( const ct_connection_t * connection )

Check if a connection's state is CT_CONN_STATE_CLOSED or CT_CONN_STATE_CLOSING.

See also: ct_connection_get_state() for a generic getter

Parameters

[in] connection The connection to check

Returns: true if connection state matches, false otherwise, including if connection is NULL

◆ ct_connection_is_closing()

bool ct_connection_is_closing ( const ct_connection_t * connection )

Check if a connection's state is CT_CONN_STATE_CLOSING.

See also: ct_connection_get_state() for a generic getter

Parameters

[in] connection The connection to check

Returns: true if connection state matches, false otherwise, including if connection is NULL

◆ ct_connection_is_established()

bool ct_connection_is_established ( const ct_connection_t * connection )

Check if a connection's state is CT_CONN_STATE_ESTABLISHED.

See also: ct_connection_get_state() for a generic getter

Parameters

[in] connection The connection to check

Returns: true if connection state matches, false otherwise, including if connection is NULL

◆ ct_connection_is_establishing()

bool ct_connection_is_establishing ( const ct_connection_t * connection )

Check if a connection's state is CT_CONN_STATE_ESTABLISHING.

See also: ct_connection_get_state() for a generic getter

Parameters

[in] connection The connection to check

Returns: true if connection state matches, false otherwise, including if connection is NULL

◆ ct_connection_is_server()

bool ct_connection_is_server ( const ct_connection_t * connection )

Check if a connection is a server connection.

Parameters

[in] connection The connection to check

Returns: true if connection role matches, false otherwise, including if connection is NULL

◆ ct_connection_sent_early_data()

bool ct_connection_sent_early_data ( const ct_connection_t * connection )

Check if a connection has sent early data (e.g., 0-RTT).

Parameters

[in] connection The connection to check

Returns: true if early data was sent, false if not or if connection is NULL

◆ ct_connection_set_priority()

int ct_connection_set_priority	(	ct_connection_t *	connection,
		uint8_t	priority
	)

Set relative priority for a connection compared to other connections in the same group.

Returns: 0 on success, negative error code on failure

Note: If a protocol does not support prioritization this does not return any error, but the value is not used.

◆ ct_receive_message()

int ct_receive_message	(	ct_connection_t *	connection,
		const ct_receive_callbacks_t *	receive_callbacks
	)

Register callbacks to receive messages on a connection.

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

Parameters

[in]	connection	The connection to receive on
[in]	receive_callbacks	Callbacks for receive events

Returns: 0 on success, negative error code on failure

◆ ct_send_message()

int ct_send_message	(	ct_connection_t *	connection,
		const ct_message_t *	message
	)

Send a message over a connection with default properties.

Takes a deep copy of the sent message, application can free or reuse the original message after this function returns.

Parameters

[in]	connection	The connection to send on
[in]	message	The message to send

Returns: 0 on success, negative error code on failure

◆ ct_send_message_full()

int ct_send_message_full	(	ct_connection_t *	connection,
		const ct_message_t *	message,
		const ct_message_context_t *	message_context
	)

Send a message with custom message context and properties.

Takes a deep copy of the sent message, application can free or reuse the original message after this function returns.

Parameters

[in]	connection	The connection to send on
[in]	message	The message to send
[in]	message_context	Message properties and context

Returns: 0 on success, negative error code on failure

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ct_protocol_enum_t

Function Documentation

◆ ct_connection_abort()

◆ ct_connection_abort_group()

◆ ct_connection_can_receive()

◆ ct_connection_can_send()

◆ ct_connection_clone()

◆ ct_connection_clone_full()

◆ ct_connection_close()

◆ ct_connection_close_group()

◆ ct_connection_free()

◆ ct_connection_get_active_local_endpoint()

◆ ct_connection_get_active_remote_endpoint()

◆ ct_connection_get_callback_context()

◆ ct_connection_get_num_open_grouped_connections()

◆ ct_connection_get_priority()

◆ ct_connection_get_protocol_name()

◆ ct_connection_get_state()

◆ ct_connection_get_total_num_grouped_connections()

◆ ct_connection_get_transport_properties()

◆ ct_connection_get_transport_protocol()

◆ ct_connection_get_uuid()

◆ ct_connection_is_client()

◆ ct_connection_is_closed()

◆ ct_connection_is_closed_or_closing()

◆ ct_connection_is_closing()

◆ ct_connection_is_established()

◆ ct_connection_is_establishing()

◆ ct_connection_is_server()

◆ ct_connection_sent_early_data()

◆ ct_connection_set_priority()

◆ ct_receive_message()

◆ ct_send_message()

◆ ct_send_message_full()