connections.h File Reference

The server connection collection. More...

#include "common.h"
#include "qstp.h"

Go to the source code of this file.

Functions
bool	qstp_connections_active (size_t index)
	Check if a connection in the collection is active.
qstp_connection_state *	qstp_connections_add (void)
	Add a new connection state to the collection and mark it as active.
size_t	qstp_connections_available (void)
	Get the number of available (inactive) connection states in the collection.
qstp_connection_state *	qstp_connections_get (uint32_t instance)
	Retrieve a connection state pointer using its instance number.
void	qstp_connections_initialize (size_t count, size_t maximum)
	Initialize the connections collection.
void	qstp_connections_clear (void)
	Erase all connection states in the collection.
void	qstp_connections_dispose (void)
	Dispose of the connections collection.
qstp_connection_state *	qstp_connections_index (size_t index)
	Retrieve a connection state pointer by its collection index.
bool	qstp_connections_full (void)
	Check if the connection collection is full.
qstp_connection_state *	qstp_connections_next (void)
	Get the next available connection state.
void	qstp_connections_reset (uint32_t instance)
	Reset a connection state in the collection.
size_t	qstp_connections_size (void)
	Get the total number of connection state objects in the collection.
void	qstp_connections_self_test (void)
	Run the self-test for the connection collection.

Detailed Description

The server connection collection.

This header defines a set of internal functions for managing the QSTP connection collection. The connection collection is an array or list of QSTP connection state objects that represent active or available network connections. These functions provide mechanisms to:

• Check the active status of a connection at a given index.
• Add a new connection state to the collection.
• Retrieve connection states by instance number or by index.
• Initialize, clear, reset, and dispose of the entire connection collection.
• Determine the number of available connection states and the total size of the collection.

Additionally, a self-test function is provided to verify the correct operation of the connection collection management routines. The self-test exercises various operations including addition, retrieval, reset, and disposal of connection state items.

Note

These functions are internal and non-exportable.

Function Documentation

qstp_connections_active()

bool qstp_connections_active

(

size_t

index

)

Check if a connection in the collection is active.

This function checks whether the connection state at the specified index in the connection collection is currently marked as active.

Parameters

index

The index (zero-based) in the connections collection.

Returns

Returns true if the connection at the given index is active; otherwise, returns false.

qstp_connections_add()

qstp_connection_state * qstp_connections_add

(

void

)

Add a new connection state to the collection and mark it as active.

This function creates a new connection state object, adds it to the connections collection, and sets its status to active. If the collection is full or memory allocation fails, the function returns NULL.

Returns

Returns a pointer to the newly added QSTP connection state, or NULL on failure.

qstp_connections_available()

size_t qstp_connections_available

(

void

)

Get the number of available (inactive) connection states in the collection.

This function returns the count of connection state slots in the collection that are currently available for new connections.

Returns

The number of available connection state items.

qstp_connections_clear()

void qstp_connections_clear

(

void

)

Erase all connection states in the collection.

This function clears all entries in the connection collection, marking each state as inactive. It does not dispose of the collection itself, but resets its contents so that they may be reused.

qstp_connections_dispose()

void qstp_connections_dispose

(

void

)

Dispose of the connections collection.

This function releases all resources allocated for the connections collection and resets its state. It should be called when the collection is no longer needed.

qstp_connections_full()

bool qstp_connections_full

(

void

)

Check if the connection collection is full.

This function checks whether the connection collection has reached its maximum capacity. When the collection is full, no additional connection state objects can be added.

Returns

Returns true if the collection is full; otherwise, false.

qstp_connections_get()

qstp_connection_state * qstp_connections_get

(

uint32_t

instance

)

Retrieve a connection state pointer using its instance number.

This function locates and returns the connection state object corresponding to the provided instance number. The instance number uniquely identifies a connection within the collection.

Parameters

instance

The unique instance number associated with a connection.

Returns

Returns a pointer to the QSTP connection state if found; otherwise, returns NULL.

qstp_connections_index()

qstp_connection_state * qstp_connections_index

(

size_t

index

)

Retrieve a connection state pointer by its collection index.

This function returns the connection state object located at the specified index in the collection. If the index is out of bounds or invalid, the function returns NULL.

Parameters

index

The index of the connection state within the collection.

Returns

Returns a pointer to the QSTP connection state, or NULL if the index is invalid.

qstp_connections_initialize()

void qstp_connections_initialize	(	size_t	count,
		size_t	maximum )

Initialize the connections collection.

This function initializes the connection collection by creating an initial set of connection state objects. The count parameter specifies the number of connection states to create initially (must be at least one), and the maximum parameter defines the maximum capacity of the collection. The maximum must be greater than or equal to the count.

Parameters

count	The initial number of connection state objects to allocate.
maximum	The maximum number of connection states the collection can hold.

qstp_connections_next()

qstp_connection_state * qstp_connections_next

(

void

)

Get the next available connection state.

This function searches the connection collection for the next available (inactive) connection state and returns a pointer to it. If all connection states are active, the function returns NULL.

Returns

Returns a pointer to the next available QSTP connection state, or NULL if none are available.

qstp_connections_reset()

void qstp_connections_reset

(

uint32_t

instance

)

Reset a connection state in the collection.

This function resets the connection state identified by the given instance number. Resetting a connection typically clears its data and marks it as inactive so that the slot can be reused.

Parameters

instance

The unique instance number of the connection to reset.

qstp_connections_self_test()

void qstp_connections_self_test

(

void

)

Run the self-test for the connection collection.

This function performs a series of tests on the connection collection to verify its proper functioning. The self-test exercises various operations, such as adding new connection states, checking active status, retrieving connection states by index and instance, resetting connections, and ensuring that the reported sizes (available and total) are correct. This helps confirm the robustness and correctness of the connection management routines.

qstp_connections_size()

size_t qstp_connections_size

(

void

)

Get the total number of connection state objects in the collection.

This function returns the total size of the connection collection, including both active and inactive states.

Returns

Returns the total number of connection state items in the collection.