xentara::utils::network::SocketServer Class Reference

A class to create a socket server. More...

#include <xentara/utils/network/SocketServer.hpp>

Inheritance diagram for xentara::utils::network::SocketServer:

Public Member Functions
	SocketServer ()=default
	Default constructor.
	SocketServer (std::reference_wrapper< const io::StopSource > stopSource) noexcept
	Constructor that associates a stop source with the socket server.
template<tools::OneOf< Protocol, AddressFamily, Backlog, WithStopSource >... Options>
	SocketServer (PortNumber portNumber, Options... options)
	Constructor for a server that listens on all local interfaces.
template<tools::OneOf< Protocol, Backlog, WithStopSource >... Options>
	SocketServer (const Address &address, Options... options)
	Constructor for a server that listens on a specific address.
auto	setStopSource (const io::StopSource &stopSource) noexcept -> void
	Associates a stop source with the server.
auto	removeStopSource () noexcept -> void
	Removes any associated stop source from the server.
template<tools::OneOf< Protocol, AddressFamily, Backlog >... Options>
auto	listen (PortNumber portNumber, Options... options) -> void
	Starts listening on all local interfaces.
template<tools::OneOf< Protocol, Backlog >... Options>
auto	listen (const Address &address, Options... options) -> void
	Starts listening on a specific address.
auto	address () const -> Address
	Gets the address the server is listening on.
auto	accept () -> SocketDevice
	Accepts a client connection.
auto	accept (std::optional< std::chrono::nanoseconds > timeout) -> SocketDevice
	Accepts a client connection.
auto	close () -> void
	Stops listening.

Detailed Description

A class to create a socket server.

Constructor & Destructor Documentation

SocketServer() [1/4]

xentara::utils::network::SocketServer::SocketServer ( )

default

Default constructor.

SocketServer() [2/4]

xentara::utils::network::SocketServer::SocketServer ( std::reference_wrapper< const io::StopSource >  stopSource )

explicitnoexcept

Constructor that associates a stop source with the socket server.

Parameters

stopSource

The stop source to watch for stop requests. The stop source can be used to interrupt the accept() function, usually to stop the server. If the stop source is triggered, accept() will throw an exception of type io::StopRequested. Accepted sockets returned by accept() will also use the specified stop source.

SocketServer() [3/4]

template<tools::OneOf< Protocol, AddressFamily, Backlog, WithStopSource >... Options>

xentara::utils::network::SocketServer::SocketServer	(	PortNumber	portNumber,
		Options...	options
	)

Constructor for a server that listens on all local interfaces.

Note

This function allows you to specify a number of options, described under Option Parameters below. Just pass the options in the options parameter pack. To create a socket server that is listening on a specific port with a backlog of 5 using a specific stop source, for example, use the following call:

SocketServer server { portNumber, xentara::utils::network::Backlog(5), xentara::utils::network::WithStopSource(stopSource) };

Parameters

portNumber

The port number to bind to, or 0 to allow the network stack to assign a port number. For protocols that do not use port numbers, the port should always be 0.

options

The Options to use. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should listen using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP or IPPROTO_SCTP. If you do not specify this option, or if you specify 0 for the protocol, then a suitable protocol will be selected based on the address and the socket type, if possible. xentara::utils::network::AddressFamily(addressFamily) Specifies a that the socket should only listen for connections for the address family addressFamily. addressFamily can be any of the AF_XXX address family defines, like AF_INET or AF_INET6. If you do not specify this option, or if you specify AF_UNSPEC for the address family, then the address family is automatically selected. You should usually not use this option, to allow connections over both IPv4 and IPv6. Only use this option if you need to restrict listening to only IPv6 or only IPv4. xentara::utils::network::Backlog Specifies a custom backlog. If you do not specify this option, then a backlog of 128 will be used. xentara::utils::network::WithStopSource(stopSource) Specifies the stop source to watch for stop requests. The stop source can be used to interrupt the accept() function, usually to stop the server. If the stop source is triggered, accept() will throw an exception of type io::StopRequested. Accepted sockets returned by accept() will also use the specified stop source. If you do not specify this option, no stop source will be used.

Exceptions

std::runtime_error	An error occurred creating the socket, or putting it into the listening state.
std::invalid_argument	A backlog of less than 1 was specified.

SocketServer() [4/4]

template<tools::OneOf< Protocol, Backlog, WithStopSource >... Options>

xentara::utils::network::SocketServer::SocketServer	(	const Address &	address,
		Options...	options
	)

Constructor for a server that listens on a specific address.

Note

This function allows you to specify a number of options, described under Option Parameters below. Just pass the options in the options parameter pack. To create a socket server that is listening on a specific address with a backlog of 5 using a specific stop source, for example, use the following call:

SocketServer server { address, xentara::utils::network::Backlog(5), xentara::utils::network::WithStopSource(stopSource) };

Parameters

address

The address to listen on. If you specify an address returned by Address::any(), then the socket will listen to the relevant port on all local interfaces.

options

The Options to use. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should listen using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP or IPPROTO_SCTP. If you do not specify this option, or if you specify 0 for the protocol, then a suitable protocol will be selected based on the address and the socket type, if possible. xentara::utils::network::Backlog Specifies a custom backlog. If you do not specify this option, then a backlog of 128 will be used. xentara::utils::network::WithStopSource(stopSource) Specifies the stop source to watch for stop requests. The stop source can be used to interrupt the accept() function, usually to stop the server. If the stop source is triggered, accept() will throw an exception of type io::StopRequested. Accepted sockets returned by accept() will also use the specified stop source. If you do not specify this option, no stop source will be used.

Exceptions

std::runtime_error	An error occurred creating the socket, or putting it into the listening state.
std::invalid_argument	The address is default constructed, or has an address family of AF_UNSPEC.
std::invalid_argument	A backlog of less than 1 was specified.

Member Function Documentation

accept() [1/2]

auto xentara::utils::network::SocketServer::accept

(

)

-> SocketDevice

Accepts a client connection.

Returns

The accepted socket. If the socket server has a stop source associated with it, the returned object will use the same stop source.

Exceptions

io::StopRequested	The stop source associated with the socket server was triggered.
std::runtime_error	An error occurred accepting the connection

accept() [2/2]

auto xentara::utils::network::SocketServer::accept

(

std::optional< std::chrono::nanoseconds >

timeout

)

-> SocketDevice

Accepts a client connection.

Parameters

timeout

The timeout, or std::nullopt to use an infinite timeout.

Returns

The accepted socket, or a default constructed socket on timeout. You can use the [operator bool()]SocketDevice::operator bool()) to check whether the returned socket is valid.

If the socket server has a stop source associated with it, the returned object will use the same stop source.

Since SocketStream has a conversion constructor from SocketDevice, you can assign the returned socket directly to a SocketStream, if desired.

Exceptions

io::StopRequested	The stop source associated with the socket server was triggered.
std::runtime_error	An error occurred accepting the connection

address()

auto xentara::utils::network::SocketServer::address

(

)

const -> Address

Gets the address the server is listening on.

Returns

The address of the listening server socket.

Exceptions

std::runtime_error

An error occurred getting the address

close()

auto xentara::utils::network::SocketServer::close

(

)

-> void

Stops listening.

listen() [1/2]

template<tools::OneOf< Protocol, Backlog >... Options>

auto xentara::utils::network::SocketServer::listen	(	const Address &	address,
		Options...	options
	)		-> void

Starts listening on a specific address.

Note

This function allows you to specify a number of options, described under Option Parameters below. Just pass the options in the options parameter pack. To listen on a specific address a backlog of 5, for example, use the following call:

server.listen(address, xentara::utils::network::Backlog(5));

Parameters

address

The address to listen on. If you specify an address returned by Address::any(), then the socket will listen to the relevant port on all local interfaces.

options

The Options to use. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should listen using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP or IPPROTO_SCTP. If you do not specify this option, or if you specify 0 for the protocol, then a suitable protocol will be selected based on the address and the socket type, if possible. xentara::utils::network::Backlog Specifies a custom backlog. If you do not specify this option, then a backlog of 128 will be used.

Exceptions

std::runtime_error	An error occurred creating the socket, or putting it into the listening state.
std::invalid_argument	The address is default constructed, or has an address family of AF_UNSPEC.
std::invalid_argument	A backlog of less than 1 was specified.

listen() [2/2]

template<tools::OneOf< Protocol, AddressFamily, Backlog >... Options>

auto xentara::utils::network::SocketServer::listen	(	PortNumber	portNumber,
		Options...	options
	)		-> void

Starts listening on all local interfaces.

Note

This function allows you to specify a number of options, described under Option Parameters below. Just pass the options in the options parameter pack. To listen on a specific port using a backlog of 5, for example, use the following call:

server.listen(portNumber, xentara::utils::network::Backlog(5));

Parameters

portNumber

The port number to bind to, or 0 to allow the network stack to assign a port number. For protocols that do not use port numbers, the port should always be 0.

options

The Options to use. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should listen using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP or IPPROTO_SCTP. If you do not specify this option, or if you specify 0 for the protocol, then a suitable protocol will be selected based on the address and the socket type, if possible. xentara::utils::network::AddressFamily(addressFamily) Specifies a that the socket should only listen for connections for the address family addressFamily. addressFamily can be any of the AF_XXX address family defines, like AF_INET or AF_INET6. If you do not specify this option, or if you specify AF_UNSPEC for the address family, then the address family is automatically selected. You should usually not use this option, to allow connections over both IPv4 and IPv6. Only use this option if you need to restrict listening to only IPv6 or only IPv4. xentara::utils::network::Backlog Specifies a custom backlog. If you do not specify this option, then a backlog of 128 will be used.

Exceptions

std::runtime_error	An error occurred creating the socket, or putting it into the listening state.
std::invalid_argument	A backlog of less than 1 was specified.

removeStopSource()

auto xentara::utils::network::SocketServer::removeStopSource ( ) -> void

noexcept

Removes any associated stop source from the server.

setStopSource()

auto xentara::utils::network::SocketServer::setStopSource ( const io::StopSource &  stopSource ) -> void

noexcept

Associates a stop source with the server.

The stop source can be used to interrupt the accept() function, usually to stop the server. If the stop source is triggered, accept() will throw an exception of type io::StopRequested. Accepted sockets returned by accept() will also use the specified stop source.

Parameters

stopSource

The stop source to watch for stop requests