socketserver.h File Reference

The socket server function definitions. More...

#include "common.h"
#include "socketbase.h"

Go to the source code of this file.

Data Structures
struct	qsc_socket_server_accept_result
	The async socket result structure. More...
struct	qsc_socket_server_async_accept_state
	The async listener-accept state structure. The structure contains a pointer to the listener socket, and pointers to a callback and error functions. The callback function returns a populated qsc_socket_server_accept_result structure. The error function returns the listener socket and an qsc_socket_exceptions error code. More...

Macros
#define	QSC_SOCKET_SERVER_LISTEN_BACKLOG   128ULL
	The socket connection backlog, default is 128.
#define	QSC_SOCKET_SERVER_MAX_THREADS   1024ULL
	The maximum number of active threads.

Functions
QSC_EXPORT_API void	qsc_socket_server_accept_callback (qsc_socket_server_accept_result *ares)
	The socket server accept callback prototype.
QSC_EXPORT_API void	qsc_socket_server_error_callback (const qsc_socket *source, qsc_socket_exceptions error)
	The socket server error callback prototype.
QSC_EXPORT_API qsc_socket_address_families	qsc_socket_server_address_family (const qsc_socket *sock)
	Get the sockets address family, IPv4 or IPv6.
QSC_EXPORT_API qsc_socket_protocols	qsc_socket_server_socket_protocol (const qsc_socket *sock)
	Get the socket protocol type.
QSC_EXPORT_API qsc_socket_transports	qsc_socket_server_socket_transport (const qsc_socket *sock)
	Get the socket transport type.
QSC_EXPORT_API void	qsc_socket_server_close_socket (qsc_socket *sock)
	Shut down channels and close the socket.
QSC_EXPORT_API void	qsc_socket_server_initialize (qsc_socket *sock)
	Initialize the server socket.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_server_listen (qsc_socket *source, qsc_socket *target, const char *address, uint16_t port, qsc_socket_address_families family)
	Places the source socket in a blocking listening state, and waits for a connection. Returns a single socket, and must be called to listen for each new connection.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_server_listen_ipv4 (qsc_socket *source, qsc_socket *target, const qsc_ipinfo_ipv4_address *address, uint16_t port)
	Places the source IPv4 socket in a blocking listening state, and waits for a connection. Returns a single socket, and must be called to listen for each new connection.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_server_listen_ipv6 (qsc_socket *source, qsc_socket *target, const qsc_ipinfo_ipv6_address *address, uint16_t port)
	Places the source IPv6 socket in a blocking listening state, and waits for a connection. Returns a single socket, and must be called to listen for each new connection.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_server_listen_async (qsc_socket_server_async_accept_state *state, const char *address, uint16_t port, qsc_socket_address_families family)
	Places the socket in an asynchronous listening state.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_server_listen_async_ipv4 (qsc_socket_server_async_accept_state *state, const qsc_ipinfo_ipv4_address *address, uint16_t port)
	Places the IPv4 socket in an asynchronous listening state.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_server_listen_async_ipv6 (qsc_socket_server_async_accept_state *state, const qsc_ipinfo_ipv6_address *address, uint16_t port)
	Places the IPv6 socket in an asynchronous listening state.
QSC_EXPORT_API void	qsc_socket_server_set_options (const qsc_socket *sock, qsc_socket_protocols level, qsc_socket_options option, int32_t optval)
	Send an option command to the socket. Options that use a boolean are format: 0=false, 1=true.
QSC_EXPORT_API void	qsc_socket_server_shut_down (qsc_socket *sock)
	Shut down the server.

Detailed Description

The socket server function definitions.

This header provides the public API for socket server operations. It includes functions to initialize a server socket, listen for incoming connections (both synchronously and asynchronously), accept incoming connections, send and receive data, and manage socket options. The API supports both IPv4 and IPv6 addressing and is designed for use in multi-threaded server applications.

// Example usage: Initialize a server socket and accept a connection.
qsc_socket server, client;
qsc_socket_server_initialize(&server);
 
// Listen on the server socket for incoming connections on IPv4 at port 8080.
if (qsc_socket_server_listen_ipv4(&server, &client, &ipv4_address, 8080) != QSC_SOCKET_RET_SUCCESS)
{
    // Handle connection error.
}
 
// Alternatively, to accept connections asynchronously:
qsc_socket_server_async_accept_state asyncState;
asyncState.source = &server;
asyncState.callback = qsc_socket_server_accept_callback;
asyncState.error = qsc_socket_server_error_callback;
 
if (qsc_socket_server_listen_async_ipv4(&asyncState, &ipv4_address, 8080) != QSC_SOCKET_RET_SUCCESS)
{
    // Handle asynchronous connection error.
}

Reference Links:

• Windows Sockets (Winsock) Documentation
• POSIX Sockets Documentation

Function Documentation

qsc_socket_server_accept_callback()

QSC_EXPORT_API void qsc_socket_server_accept_callback

(

qsc_socket_server_accept_result *

ares

)

The socket server accept callback prototype.

Parameters

ares	[qsc_socket_server_accept_result*] A pointer to the server accept result structure

qsc_socket_server_address_family()

QSC_EXPORT_API qsc_socket_address_families qsc_socket_server_address_family

(

const qsc_socket *

sock

)

Get the sockets address family, IPv4 or IPv6.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket

Returns

[qsc_socket_address_families] The socket address family

qsc_socket_server_close_socket()

QSC_EXPORT_API void qsc_socket_server_close_socket

(

qsc_socket *

sock

)

Shut down channels and close the socket.

Parameters

sock	[qsc_socket*] A pointer to the socket structure

qsc_socket_server_error_callback()

QSC_EXPORT_API void qsc_socket_server_error_callback	(	const qsc_socket *	source,
		qsc_socket_exceptions	error )

The socket server error callback prototype.

Parameters

source	[const qsc_socket*] A pointer to the initialized socket
error	[qsc_socket_exceptions] The socket exception

qsc_socket_server_initialize()

QSC_EXPORT_API void qsc_socket_server_initialize

(

qsc_socket *

sock

)

Initialize the server socket.

Parameters

sock	[qsc_socket*] A pointer to the socket structure

qsc_socket_server_listen()

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_server_listen	(	qsc_socket *	source,
		qsc_socket *	target,
		const char *	address,
		uint16_t	port,
		qsc_socket_address_families	family )

Places the source socket in a blocking listening state, and waits for a connection. Returns a single socket, and must be called to listen for each new connection.

Parameters

source	[qsc_socket*] The listening socket
target	[qsc_socket*] The accepted remote socket
address	[const char*] The servers address
port	[uint16_t] The servers port number
family	[qsc_socket_address_families] The socket address family

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_server_listen_async()

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_server_listen_async	(	qsc_socket_server_async_accept_state *	state,
		const char *	address,
		uint16_t	port,
		qsc_socket_address_families	family )

Places the socket in an asynchronous listening state.

Parameters

state	[qsc_socket_server_async_accept_state*] The asynchronous server state
address	[const char*] The servers address
port	[uint16_t] The servers port number
family	[qsc_socket_address_families] The socket address family

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_server_listen_async_ipv4()

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_server_listen_async_ipv4	(	qsc_socket_server_async_accept_state *	state,
		const qsc_ipinfo_ipv4_address *	address,
		uint16_t	port )

Places the IPv4 socket in an asynchronous listening state.

Parameters

state	[qsc_socket_server_async_accept_state*] The asynchronous server state
address	[const qsc_ipinfo_ipv4_address*] The servers address
port	[uint16_t] The servers port number

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_server_listen_async_ipv6()

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_server_listen_async_ipv6	(	qsc_socket_server_async_accept_state *	state,
		const qsc_ipinfo_ipv6_address *	address,
		uint16_t	port )

Places the IPv6 socket in an asynchronous listening state.

Parameters

state	[qsc_socket_server_async_accept_state*] The asynchronous server state
address	[const qsc_ipinfo_ipv6_address*] The servers address
port	[uint16_t] The servers port number

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_server_listen_ipv4()

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_server_listen_ipv4	(	qsc_socket *	source,
		qsc_socket *	target,
		const qsc_ipinfo_ipv4_address *	address,
		uint16_t	port )

Places the source IPv4 socket in a blocking listening state, and waits for a connection. Returns a single socket, and must be called to listen for each new connection.

Parameters

source	[qsc_socket*] The listening socket
target	[qsc_socket*] The accepted remote socket
address	[const qsc_ipinfo_ipv4_address*] The servers IPv4 address
port	[uint16_t] The servers port number

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_server_listen_ipv6()

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_server_listen_ipv6	(	qsc_socket *	source,
		qsc_socket *	target,
		const qsc_ipinfo_ipv6_address *	address,
		uint16_t	port )

Places the source IPv6 socket in a blocking listening state, and waits for a connection. Returns a single socket, and must be called to listen for each new connection.

Parameters

source	[qsc_socket*] The listening socket
target	[qsc_socket*] The accepted remote socket
address	[const qsc_ipinfo_ipv6_address*] The servers IPv6 address
port	[uint16_t] The servers port number

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_server_set_options()

QSC_EXPORT_API void qsc_socket_server_set_options	(	const qsc_socket *	sock,
		qsc_socket_protocols	level,
		qsc_socket_options	option,
		int32_t	optval )

Send an option command to the socket. Options that use a boolean are format: 0=false, 1=true.

Parameters

sock	[const qsc_socket*] The socket instance
level	[qsc_socket_protocols] The level at which the option is assigned
option	[qsc_socket_options] The option command to send
optval	[int32_t] The value of the option command

qsc_socket_server_shut_down()

QSC_EXPORT_API void qsc_socket_server_shut_down

(

qsc_socket *

sock

)

Shut down the server.

Parameters

sock	[qsc_socket*] The listening socket

qsc_socket_server_socket_protocol()

QSC_EXPORT_API qsc_socket_protocols qsc_socket_server_socket_protocol

(

const qsc_socket *

sock

)

Get the socket protocol type.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket

Returns

[qsc_socket_protocols] The socket protocol type

qsc_socket_server_socket_transport()

QSC_EXPORT_API qsc_socket_transports qsc_socket_server_socket_transport

(

const qsc_socket *

sock

)

Get the socket transport type.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket

Returns

[qsc_socket_transports] The socket transport type