connections.h File Reference

The server connection collection. More...

#include "common.h"
#include "qsmp.h"

Go to the source code of this file.

Functions
bool	qsmp_connections_active (size_t index)
	Determine if a connection state at the specified index is active.
qsmp_connection_state *	qsmp_connections_add (void)
	Add a new connection state to the collection and mark it as active.
size_t	qsmp_connections_available (void)
	Get the number of available (inactive) connection states in the collection.
qsmp_connection_state *	qsmp_connections_get (uint32_t instance)
	Retrieve a connection state by its unique instance number.
void	qsmp_connections_initialize (size_t count, size_t maximum)
	Initialize the QSMP connections collection.
void	qsmp_connections_clear (void)
	Clear all connection states in the collection.
void	qsmp_connections_dispose (void)
	Dispose of the QSMP connections collection.
qsmp_connection_state *	qsmp_connections_index (size_t index)
	Retrieve a connection state pointer by its collection index.
bool	qsmp_connections_full (void)
	Check if the connections collection is full.
qsmp_connection_state *	qsmp_connections_next (void)
	Retrieve the next available (inactive) connection state from the collection.
void	qsmp_connections_reset (uint32_t instance)
	Reset a specific connection state in the collection.
size_t	qsmp_connections_size (void)
	Get the total number of connection state items in the collection.
void	qsmp_connections_self_test (void)
	Run the self-test routine for the connections collection.

Detailed Description

The server connection collection.

This header file defines internal functions for managing the collection of connection state objects used by the QSMP server. The connections collection maintains an array of connection states (of type qsmp_connection_state), each representing an active or available socket connection. The functions declared herein allow for:

• Checking the active status of a connection slot.
• Adding new connection states to the collection.
• Retrieving connection states by instance or index.
• Initializing and disposing of the connections collection.
• Resetting and clearing connection states.
• Determining the capacity and availability of the collection.
• Running self-tests to ensure the collection operates correctly.

Note

These functions are internal and non-exportable.

Function Documentation

qsmp_connections_active()

bool qsmp_connections_active

(

size_t

index

)

Determine if a connection state at the specified index is active.

This function checks whether the connection state at the provided index in the connections collection is currently marked as active. This is useful for verifying if a connection slot is in use.

Parameters

index

The index number of the connection slot in the collection.

Returns

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

qsmp_connections_add()

qsmp_connection_state * qsmp_connections_add

(

void

)

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

This function creates a new connection state, adds it to the QSMP connections collection, and sets its status to active. If the collection has reached its maximum capacity or if the allocation fails, the function returns NULL.

Returns

A pointer to the newly added connection state, or NULL on failure.

qsmp_connections_available()

size_t qsmp_connections_available

(

void

)

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

This function returns the count of connection slots in the collection that are currently available (i.e., not active). This number indicates how many additional connections can be accommodated.

Returns

The number of available connection state items.

qsmp_connections_clear()

void qsmp_connections_clear

(

void

)

Clear all connection states in the collection.

This function resets or erases all entries in the connections collection, marking each as inactive. This operation prepares the collection for new connection assignments without disposing of the collection itself.

qsmp_connections_dispose()

void qsmp_connections_dispose

(

void

)

Dispose of the QSMP connections collection.

This function releases all resources allocated for the connections collection and cleans up its internal state. It should be called when the connections collection is no longer required.

qsmp_connections_full()

bool qsmp_connections_full

(

void

)

Check if the connections collection is full.

This function determines whether the connections collection has reached its maximum capacity. When the collection is full, no additional connection states can be added.

Returns

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

qsmp_connections_get()

qsmp_connection_state * qsmp_connections_get

(

uint32_t

instance

)

Retrieve a connection state by its unique instance number.

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

Parameters

instance

The unique instance number of the connection.

Returns

A pointer to the connection state if found; otherwise, NULL.

qsmp_connections_index()

qsmp_connection_state * qsmp_connections_index

(

size_t

index

)

Retrieve a connection state pointer by its collection index.

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

Parameters

index

The index of the connection state within the collection.

Returns

A pointer to the connection state if the index is valid; otherwise, NULL.

qsmp_connections_initialize()

void qsmp_connections_initialize	(	size_t	count,
		size_t	maximum )

Initialize the QSMP connections collection.

This function sets up the internal connections collection by creating an initial set of connection states. The count parameter specifies the number of connection states to create initially (minimum of one), and maximum defines the upper limit of connection states the collection can hold.

Parameters

count	The initial number of connection states to create (must be at least one).
maximum	The maximum number of connection states allowed in the collection (must be greater than or equal to count).

qsmp_connections_next()

qsmp_connection_state * qsmp_connections_next

(

void

)

Retrieve the next available (inactive) connection state from the collection.

This function searches for and returns a pointer to the next available connection state in the collection. If all connection slots are active, the function returns NULL.

Returns

A pointer to the next available connection state, or NULL if none are available.

qsmp_connections_reset()

void qsmp_connections_reset

(

uint32_t

instance

)

Reset a specific connection state in the collection.

This function resets the connection state identified by the provided instance number. Resetting a connection typically involves clearing its data and marking it as inactive so that the slot can be reused.

Parameters

instance

The unique instance number of the connection to reset.

qsmp_connections_self_test()

void qsmp_connections_self_test

(

void

)

Run the self-test routine for the connections collection.

This function executes a series of internal tests to verify the proper functioning of the QSMP connections collection. The self-test routine may include the following:

• Adding new connection states and verifying they are correctly marked as active.
• Checking the active status of connection slots.
• Retrieving connection states by instance or index.
• Resetting connection states and confirming they become inactive.
• Ensuring that the collection correctly reports the number of available and total connection slots.

The self-test is used to validate the robustness and reliability of the connection management subsystem.

qsmp_connections_size()

size_t qsmp_connections_size

(

void

)

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

This function returns the total number of connection states maintained in the collection, including both active and inactive items.

Returns

The total size of the connections collection.