xentara::utils::network::SocketDevice Class Reference

A stream socket that implements io::InputDevice and io::OutputDevice. More...

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

Inheritance diagram for xentara::utils::network::SocketDevice:

Public Member Functions
	SocketDevice () noexcept=default
	Default constructor.
	SocketDevice (std::reference_wrapper< const io::StopSource > stopSource) noexcept
	Constructor that associates a stop source with the socket.
template<tools::OneOf< WithStopSource >... Options>
	SocketDevice (Socket &&socket, Options... options)
	Constructor from a generic socket object.
template<tools::OneOf< Protocol, WithStopSource >... Options>
	SocketDevice (int addressFamily, Options... options)
	Constructor that creates a stream socket.
template<tools::OneOf< WithStopSource >... Options>
	SocketDevice (posix::File socketFileDescriptor, Options... options)
	Creates a socket object from a Posix file descriptor.
template<tools::OneOf< WithStopSource >... Options>
	SocketDevice (windows::Socket socket, Options... options)
	Creates a socket object from a native Windows socket.
	~SocketDevice () noexcept=default
	Noexcept Destructor.
internal auto	operator= (Socket &&socket) -> SocketDevice &
	Assignment operator for a generic socket object.
auto	operator= (posix::File socketFileDescriptor) -> SocketDevice &
	Assignment operator for a Posix file descriptor.
auto	operator= (windows::Socket socket) -> SocketDevice &
	Assignment operator for a native Windows socket.
	operator bool () const noexcept
	Checks whether the object contains a valid socket.
auto	addressFamily () const noexcept -> int
	Gets the address family of the socket, also called the socket domain.
auto	protocol () const noexcept -> int
	Gets the protocol of the socket.
auto	setReadTimeout (std::chrono::nanoseconds timeout) noexcept
	Sets the read timeout.
auto	setWriteTimeout (std::chrono::nanoseconds timeout) noexcept
	Sets the write timeout.
auto	setTimeout (std::chrono::nanoseconds timeout) noexcept
	Sets the read and write timeout to the same value.
template<typename Value >
auto	option (int level, int optionName) const -> Value
	Gets a socket option.
template<typename Value >
auto	setOption (int level, int optionName, const Value &value) -> void
	Sets a socket option.
template<typename Value >
auto	getOption (int level, int optionName, std::nothrow_t) const noexcept -> xentara::utils::eh::expected< Value, std::error_code >
	Gets a socket option.
template<typename Value >
auto	setOption (int level, int optionName, const Value &value, std::nothrow_t) noexcept -> std::error_code
	Sets a socket option without throwing exceptions.
auto	connect (const Address &address) -> void
	Connects to an address.
auto	connect (const Address &address, std::optional< std::chrono::nanoseconds > timeout) -> bool
	Connects to an address with optional timeout.
auto	bind (PortNumber portNumber) -> void
	Binds the socket to a port number on all local interfaces.
auto	bind (const Address &address) -> void
	Binds the socket to a specific address.
auto	localAddress () const -> Address
	Gets the local address of a bound or connected socket.
auto	remoteAddress () const -> Address
	Gets the address that the socket is connected to.
auto	shutdown (Socket::Direction directions=Socket::Direction::ReadWrite) -> void
	Shuts down the socket.
auto	close () noexcept -> void
	Closes the socket, if one is open.
auto	socket () const &noexcept -> const Socket &
	Gets the socket as a generic socket.
auto	socket () &&noexcept -> Socket &&
	Gets the socket as a generic socket.
auto	native () const noexcept -> int
	Gets the underlying Posix file descriptor for the socket.
auto	native () const noexcept -> SOCKET
	Gets the underlying Windows Sockets 2 SOCKET.
auto	release () noexcept -> int
	Removes the the socket and passes ownership to the caller.
auto	release () noexcept -> SOCKET
	Removes the socket and passes ownership to the caller.
Public Member Functions inherited from xentara::utils::io::InputDevice
virtual	~InputDevice () noexcept(false)=0
	Virtual, throwing destructor.
auto	read (std::size_t size) -> core::RawDataBlock
	Reads a block of data of a specific size.
auto	readByte () -> std::byte
	Reads a single byte.
auto	tryReadByte () -> std::optional< std::byte >
	Tries to read a single byte from a device.
auto	readAll () -> core::RawDataBlock
	Reads all remaining data.
auto	readAll (std::size_t maxSize) -> core::RawDataBlock
	Reads all remaining data up to a maximum size.
auto	readChunk () -> core::RawDataBlock
	Reads a single chunk of data.
auto	readChunk (std::size_t maxSize) -> core::RawDataBlock
	Reads a single chunk of data up to a maximum size.
auto	readAvailable () -> std::pair< core::RawDataBlock, bool >
	Reads all immediately available data.
auto	readAvailable (std::size_t maxSize) -> std::pair< core::RawDataBlock, bool >
	Reads immediately available data up to a maximum size.
template<std::size_t kArraySize>
auto	read (std::byte(&array)[kArraySize]) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	read (std::array< std::byte, kArraySize > &array) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	readChunk (std::byte(&array)[kArraySize]) -> core::RawDataBlock
	Reads a single chunk of data into an array.
template<std::size_t kArraySize>
auto	readChunk (std::array< std::byte, kArraySize > &array) -> core::RawDataBlock
	Reads a single chunk of data into an array.
template<std::size_t kArraySize>
auto	readAvailable (std::byte(&array)[kArraySize]) -> std::pair< std::size_t, bool >
	Reads immediately available data into an array.
template<std::size_t kArraySize>
auto	readAvailable (std::array< std::byte, kArraySize > &array) -> std::pair< std::size_t, bool >
	Reads immediately available data into an array.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_volatile_t<std::iter_value_t<Iterator>>, std::byte>
auto	read (Iterator first, Sentinel last) -> void
	Read data to fill an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	readChunk (Iterator first, Sentinel last) -> Iterator
	Reads a single chunk of data data into an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	readAvailable (Iterator first, Sentinel last) -> std::pair< Iterator, bool >
	Reads immediately available data into an iterator range.
auto	read (std::byte *buffer, std::size_t size) -> void
	Read a block of data into a buffer.
auto	readChunk (std::byte *buffer, std::size_t size) -> std::size_t
	Reads a single chunk of data into a buffer.
auto	readAvailable (std::byte *buffer, std::size_t size) -> std::pair< std::size_t, bool >
	Reads immediately available data into a buffer.
auto	availableReadSize () const -> std::optional< std::size_t >
	Get the number of bytes for reading without blocking.
auto	remainingReadSize () const -> std::optional< std::size_t >
	Get the number of bytes remaining before the end of the device.
auto	readPosition () const -> std::optional< std::size_t >
	Gets the current read position within the device.
auto	setReadPosition (std::size_t position) -> std::optional< std::size_t >
	Sets the current read position within the device.
auto	moveReadPosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Advances or retreats the current read position within the device.
auto	advanceReadPosition (std::size_t offset) -> std::optional< std::size_t >
	Advance the current read position within the device.
auto	rewind () -> bool
	Sets the current read position to the beginning of the device.
auto	waitForData () -> void
	Waits for more read data to become available.
auto	waitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Waits for more read data to become available within a certain time.
auto	readTimeout () const noexcept -> std::chrono::nanoseconds
	Returns the read timeout for communication devices.
auto	throwEndOfStreamError () const -> void
	Throws an error denoting the end of the stream.
Public Member Functions inherited from xentara::utils::io::DeviceBase
virtual	~DeviceBase () noexcept(false)=0
	Virtual, throwing destructor.
auto	deviceDescription () const -> std::string
	Get a description of the device.
Public Member Functions inherited from xentara::utils::io::OutputDevice
virtual	~OutputDevice () noexcept(false)=0
	Virtual, throwing destructor.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	write (const Data &data) -> void
	Writes a block of data.
auto	writeByte (std::byte byte) -> void
	Write a single byte.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	writeChunk (const Data &data) -> std::ranges::range_size_t< Data >
	Writes a single chunk of data contained in an iterator range.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	tryWrite (const Data &data) -> std::ranges::range_size_t< Data >
	Write as much of a data block as is possible without blocking.
auto	tryWriteByte (std::byte byte) -> bool
	Write a single byte, if this can be done without blocking.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, std::byte>
auto	write (Iterator first, Sentinel last) -> void
	Writes the data contained in an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, std::byte>
auto	writeChunk (Iterator first, Sentinel last) -> Iterator
	Writes a single chunk of data from an an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	tryWrite (Iterator first, Sentinel last) -> Iterator
	Write as much of the data contained in an iterator range as is possible without blocking.
auto	write (const std::byte *data, std::size_t size) -> void
	Write a block of data.
auto	writeChunk (const std::byte *data, std::size_t size) -> std::size_t
	Writes a single chunk of data.
auto	tryWrite (const std::byte *data, std::size_t size) -> std::size_t
	Write as much of a data block as is possible without blocking.
auto	writePosition () const -> std::optional< std::size_t >
	Gets the current write position within the device.
auto	setWritePosition (std::size_t position) -> std::optional< std::size_t >
	Sets the current write position within the device.
auto	moveWritePosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Advances or retreats the current write position within the device.
auto	waitUntilWritable (std::chrono::nanoseconds timeout) -> bool
	Waits for the device to be able to accept more write data within a certain time.
auto	writeTimeout () const noexcept -> std::chrono::nanoseconds
	Returns the write timeout for communication devices.

Static Public Member Functions
static constexpr auto	defaultTimeout () noexcept -> std::chrono::nanoseconds
	Gets the default timeout used if you do not specifiy a timeout.
template<tools::OneOf< Protocol, WithStopSource >... Options>
static auto	compatibleSocket (const Address &address, Options... options) -> SocketDevice
	Creates a socket that is compatible with an address.
template<tools::OneOf< Protocol, Timeout, WithStopSource >... Options>
static auto	connectedSocket (const Address &address, Options... options) -> SocketDevice
	Creates a socket that is connected to an address.
template<tools::OneOf< Protocol, Timeout, WithStopSource >... Options>
static auto	connectedSocket (const std::vector< Address > &addresses, Options... options) -> SocketDevice
	Creates a socket that is connected to the first available address in a list.
template<tools::OneOf< Protocol, DefaultPort, WithPort, AddressFamily, Timeout, WithStopSource >... Options>
static auto	connectedSocket (std::string_view hostName, Options... options) -> SocketDevice
	Creates a socket that is connected to a named host.

Additional Inherited Members
Protected Member Functions inherited from xentara::utils::io::InputDevice
virtual auto	doRead (std::byte *buffer, std::size_t size) -> std::optional< std::size_t >=0
	Called by the framework to read available data into a buffer up to a maximum size.
virtual auto	doThrowEndOfStreamError () const -> void
	Called by the framework to throw an error denoting the end of the stream.
virtual auto	doGetAvailableReadSize () const -> std::optional< std::size_t >
	Called by the framework to get the number of bytes that will be read by the next call to doRead().
virtual auto	doGetRemainingReadSize () const -> std::optional< std::size_t >
	Called by the framework to get the number of bytes remaining before the end of the device.
virtual auto	doWaitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Called by the framework to wait for more read data to become available.
virtual auto	doWaitForDataAndRead (std::byte *buffer, std::size_t size, std::chrono::nanoseconds timeout) -> std::optional< std::size_t >
	Called by the framework to wait for read data to become available, and then read it.
virtual auto	doGetReadTimeout () const noexcept -> std::chrono::nanoseconds
	Called by the framework to get the read timeout.
virtual auto	doGetReadPosition () const -> std::optional< std::size_t >
	Called by the framework to get the current read position within the device.
virtual auto	doSetReadPosition (std::size_t position) -> std::optional< std::size_t >
	Called by the framework to set the current read position within the device.
virtual auto	doMoveReadPosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Called by the framework to advance or retreat the current read position within the device.
virtual auto	doAdvanceReadPosition (std::size_t offset) -> std::optional< std::size_t >
	Called by the framework to advance the current read position within the device.
Protected Member Functions inherited from xentara::utils::io::DeviceBase
virtual auto	doGetDeviceDescription () const -> std::string=0
	Called by the framework to get a description of the device.
Protected Member Functions inherited from xentara::utils::io::OutputDevice
virtual auto	doWrite (const std::byte *data, std::size_t size) -> std::size_t=0
	Called by the framework to write data up to a maximum size.
virtual auto	doWaitUntilWritable (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Called by the framework to wait for the device to be able to accept more write data with an optional timeout.
virtual auto	doWaitUntilWritableAndWrite (const std::byte *data, std::size_t size, std::chrono::nanoseconds timeout) -> std::size_t
	Called by the framework to wait for the device to be able to accept more write data, and then write to it.
virtual auto	doGetWriteTimeout () const noexcept -> std::chrono::nanoseconds
	Called by the framework to get the write timeout.
virtual auto	doGetWritePosition () const -> std::optional< std::size_t >
	Called by the framework to get the current write position within the device.
virtual auto	doSetWritePosition (std::size_t position) -> std::optional< std::size_t >
	Called by the framework to set the current write position within the device.
virtual auto	doMoveWritePosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Called by the framework to advance or retreat the current write position within the device.

Detailed Description

A stream socket that implements io::InputDevice and io::OutputDevice.

Constructor & Destructor Documentation

SocketDevice() [1/6]

xentara::utils::network::SocketDevice::SocketDevice ( )

defaultnoexcept

Default constructor.

Creates an invalid socket object.

SocketDevice() [2/6]

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

explicitnoexcept

Constructor that associates a stop source with the socket.

Creates an invalid socket object.

Attention

The stop source will be overwritten if you assign a pipe returned by Socket::accept() to this object.

Parameters

stopSource

The stop source to associates with the socket

SocketDevice() [3/6]

template<tools::OneOf< WithStopSource >... Options>

xentara::utils::network::SocketDevice::SocketDevice	(	Socket &&	socket,
		Options...	options
	)

Constructor from a generic socket object.

Note

This constructor allows you to specify a number of options for the socket, described under Option Parameters below. Just pass the options in the options parameter pack. To create a TCP socket, for example, use the following call:

xentara::utils::network::SocketDevice socket { AF_INET6, xentara::utils::network::Protocol(IPPROTO_TCP) };

Parameters

socket	The socket. This must be either a default-constructed socket, or a socket of type SOCK_STREAM.
options	The options for the socket. See Option Parameters below. Option Parameters xentara::utils::network::WithStopSource(stopSource) Specifies the stop source to associate with the socket. If you do not specify this option, no stop source will be used.

SocketDevice() [4/6]

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

xentara::utils::network::SocketDevice::SocketDevice ( int  addressFamily, Options...  options  )

explicit

Constructor that creates a stream socket.

Note

This constructor allows you to specify a number of options for the socket, described under Option Parameters below. Just pass the options in the options parameter pack. To create a TCP socket, for example, use the following call:

xentara::utils::network::SocketDevice socket { AF_INET6, xentara::utils::network::Protocol(IPPROTO_TCP) };

Note

The original BSD socket specification distinguished between address families (AF_INET etc.) unsed for socket addresses and protocol families (PF_INET etc.) used for sockets. The man pages on FreeBSD, Darwin, and macOS consequently state that PF_XXX constants should be used when creating sockets, rather than AF_XXX constants. The POSIX socket standard, however, makes no mention of PF_XXX constants, and uses AF_XXX constants for both socket addresses and sockets. The documentation for Linux, WinSock, as well as OpenBSD and many other Unix flavours also use AF_XXX in both cases. We recommend using AF_XXX when creating sockets instead of PF_XXX so as to be POSIX compliant. This will also work on BSD style socket implementations, as the corresponding AF_XXX and PF_XXX defines are always the same.

Parameters

addressFamily

The address family, also called the socket domain. Can be any of the AF_XXX address family defines, like AF_INET or AF_INET6.

options

The options for the socket. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the socket should use 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 family, if possible. xentara::utils::network::WithStopSource(stopSource) Specifies the stop source to associate with the socket. If you do not specify this option, no stop source will be used.

Exceptions

std::runtime_error	An error occurred getting the option
std::invalid_argument	An address family of AF_UNSPEC was specified

SocketDevice() [5/6]

template<tools::OneOf< WithStopSource >... Options>

xentara::utils::network::SocketDevice::SocketDevice	(	posix::File	socketFileDescriptor,
		Options...	options
	)

Creates a socket object from a Posix file descriptor.

This constructor takes ownership of the socket.

Note

This constructor allows you to specify a stop source for the socket using the option parameter, as described under Option Parameters below. Just pass the stop source using the option xentara::utils::network::WithStopSource:

xentara::utils::network::SocketDevice socket { rawSocket, xentara::utils::network::WithStopSource(stopSource) };

Note

This constructor is not available under Windows.

Parameters

socketFileDescriptor	The file descriptor of the new socket, or -1 to create a object that does not contain a socket. If socketFileDescriptor is not -1, it must be a socket of type SOCK_STREAM.
options	The options for the socket. See Option Parameters below. Option Parameters xentara::utils::network::WithStopSource(stopSource) Specifies the stop source to associate with the socket. If you do not specify this option, no stop source will be used.

SocketDevice() [6/6]

template<tools::OneOf< WithStopSource >... Options>

xentara::utils::network::SocketDevice::SocketDevice	(	windows::Socket	socket,
		Options...	options
	)

Creates a socket object from a native Windows socket.

This constructor takes ownership of the socket.

Note

This constructor allows you to specify a stop source for the socket using the option parameter, as described under Option Parameters below. Just pass the stop source using the option xentara::utils::network::WithStopSource:

xentara::utils::network::SocketDevice socket { rawSocket, xentara::utils::network::WithStopSource(stopSource) };

Note

This constructor is only available under Windows.

Parameters

socket	The new socket, or INVALID_SOCKET to create a object that does not contain a socket. If socket is not INVALID_SOCKET, it must be of type SOCK_STREAM.
options	The options for the socket. See Option Parameters below. Option Parameters xentara::utils::network::WithStopSource(stopSource) Specifies the stop source to associate with the socket. If you do not specify this option, no stop source will be used.

~SocketDevice()

xentara::utils::network::SocketDevice::~SocketDevice ( )

defaultnoexcept

Noexcept Destructor.

This class's constructor never throws an exception

Member Function Documentation

addressFamily()

auto xentara::utils::network::SocketDevice::addressFamily ( ) const -> int

noexcept

Gets the address family of the socket, also called the socket domain.

Returns

The address family. This will be one of the AF_XXX address family defines, like AF_INET or AF_INET6. For default constructed objects, or if the address family could not be determined, this function returns AF_UNSPEC.

bind() [1/2]

auto xentara::utils::network::SocketDevice::bind

(

const Address &

address

)

-> void

Binds the socket to a specific address.

Parameters

address

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

Exceptions

std::runtime_error	An error occurred binding the socket
std::invalid_argument	The address is default constructed, or has an address family of AF_UNSPEC.

bind() [2/2]

auto xentara::utils::network::SocketDevice::bind

(

PortNumber

portNumber

)

-> void

Binds the socket to a port number on all local interfaces.

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.

Exceptions

std::runtime_error

An error occurred binding the socket

close()

auto xentara::utils::network::SocketDevice::close ( ) -> void

noexcept

Closes the socket, if one is open.

compatibleSocket()

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

static auto xentara::utils::network::SocketDevice::compatibleSocket ( const Address &  address, Options...  options  ) -> SocketDevice

static

Creates a socket that is compatible with an address.

This function creates a socket that can be used to communicate with a certain address. The socket will not actually be bound or connected to the address, use bind() or connect() if you need to bind to or connect to the address.

Note

This function allows you to specify a number of options for the socket, described under Option Parameters below. Just pass the options in the options parameter pack. To create a TCP socket, for example, use the following call:

auto socket = xentara::utils::network::Socket::compatibleSocket(xentara::utils::network::Protocol(IPPROTO_TCP));

Parameters

address

The addresses that the socket will be used for.

options

The Options to use for the socket. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should be established using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP. 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 family, if possible. xentara::utils::network::WithStopSource(stopSource) Specifies the stop source to associate with the socket. If you do not specify this option, no stop source will be used.

Returns

A socket connected to the address

Exceptions

std::runtime_error	An error occurred creating or connecting the socket for all of the given addresses
std::invalid_argument	The address is default constructed, or has an address family of AF_UNSPEC.

connect() [1/2]

auto xentara::utils::network::SocketDevice::connect

(

const Address &

address

)

-> void

Connects to an address.

Parameters

address

The address to connect to

Exceptions

std::runtime_error	An error occurred connecting the socket
std::invalid_argument	The address is default constructed, or has an address family of AF_UNSPEC.

connect() [2/2]

auto xentara::utils::network::SocketDevice::connect	(	const Address &	address,
		std::optional< std::chrono::nanoseconds >	timeout
	)		-> bool

Connects to an address with optional timeout.

Parameters

address	The address to connect to
timeout	The connection timeout, or std::nullopt for an infinite timeout.

Returns

Returns true if the connection was successfully established, or false on timeout. Please note that the socket will still have a pending connection if false is returned, so it has become essentially unusable.

Exceptions

std::runtime_error	An error occurred connecting the socket
std::invalid_argument	The address is default constructed, or has an address family of AF_UNSPEC.

connectedSocket() [1/3]

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

static auto xentara::utils::network::SocketDevice::connectedSocket ( const Address &  address, Options...  options  ) -> SocketDevice

static

Creates a socket that is connected to an address.

Note

This function allows you to specify a number of options for the socket, described under Option Parameters below. Just pass the options in the options parameter pack. To connect a to a list of addresses using the TCP protocol and a timeout of 5s, for example, use the following call:

auto socket = xentara::utils::network::SocketDevice::connectedSocket(addresses,
    xentara::utils::network::Protocol(IPPROTO_TCP),
    xentara::utils::network::Timeout(5s));

Parameters

address

The addresses to connect to.

options

The Options to use for the connection. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should be established using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP. 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 family, if possible. xentara::utils::network::Timeout(timeout) Specifies the timeout for the connect. If you do not specify this option, or if you specify std::nullopt for the timeout, an infinite timeout 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 wait, usually to shutdown and close the socket. If the stop source is triggered, the function will throw an exception of type io::StopRequested. If you do not specify this option, no stop source will be used. The returned socket is automatically associated with the given stop source.

Returns

A socket connected to the given address. If you specified a timeout, and the connection could not be completed within in the given time, a default constructed socket is returned. You can use the operator bool() to check whether the returned socket is valid.

Exceptions

std::runtime_error	An error occurred creating or connecting the socket for all of the given addresses
std::invalid_argument	The address is default constructed, or has an address family of AF_UNSPEC.

connectedSocket() [2/3]

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

static auto xentara::utils::network::SocketDevice::connectedSocket ( const std::vector< Address > &  addresses, Options...  options  ) -> SocketDevice

static

Creates a socket that is connected to the first available address in a list.

Note

This function allows you to specify a number of options for the socket, described under Option Parameters below. Just pass the options in the options parameter pack. To connect a to a list of addresses using the TCP protocol and a timeout of 5s, for example, use the following call:

auto socket = xentara::utils::network::SocketDevice::connectedSocket(addresses,
    xentara::utils::network::Protocol(IPPROTO_TCP),
    xentara::utils::network::Timeout(5s));

Parameters

addresses

The addresses to try to connect to, in the order that they should be tried. Addresses that do not support stream sockets are ignored, as are default constructed addresses and addresses with address family AF_UNSPEC.

options

The Options to use for the connection. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should be established using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP. 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 family, if possible. xentara::utils::network::Timeout(timeout) Specifies the timeout for the connect. If you do not specify this option, or if you specify std::nullopt for the timeout, an infinite timeout 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 wait, usually to shutdown and close the socket. If the stop source is triggered, the function will throw an exception of type io::StopRequested. If you do not specify this option, no stop source will be used. The returned socket is automatically associated with the given stop source.

Returns

A socket connected to the first address that accepted the connection. If you specified a timeout, and the connection could not be completed within in the given time, a default constructed socket is returned. You can use the operator bool() to check whether the returned socket is valid.

Exceptions

HostNotFoundError	The address list did not contain any suitable addresses.
std::runtime_error	An error occurred creating or connecting the socket for all of the given addresses

connectedSocket() [3/3]

template<tools::OneOf< Protocol, DefaultPort, WithPort, AddressFamily, Timeout, WithStopSource >... Options>

static auto xentara::utils::network::SocketDevice::connectedSocket ( std::string_view  hostName, Options...  options  ) -> SocketDevice

static

Creates a socket that is connected to a named host.

Normally, hostName must contain a port number after the host name or address string. You can pass the options xentara::utils::network::DefaultPort or xentara::utils::network::WithPort in the options parameter pack to make the port number optional, or to specify a fixed port number. See Option Parameters below for a description of these options.

Note

This function allows you to specify a number of options for the socket and the address lookup, described under Option Parameters below. Just pass the options in the options parameter pack. To connect to a host name with a default port of 8080 using a timeout of 5s, for example, use the following call:

auto socket = xentara::utils::network::SocketDevice::connectedSocket(hostName,
    xentara::utils::network::DefaultPort(8080),
    xentara::utils::network::Timeout(5s));

Parameters

hostName

The host name to connect to

options

The Options to use for the connection. See Option Parameters below. Option Parameters xentara::utils::network::Protocol(protocol) Specifies that the connection should be established using the protocol protocol. protocol can be any of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP. 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 family, if possible. xentara::utils::network::DefaultPort(portNumber) Specifies that including port number in hostName is optional. If hostName does not contain a port number, portNumber will be used instead. Cannot be combined with xentara::utils::network::WithPort. xentara::utils::network::WithPort(portNumber) Specifies that hostName must be a host name or address string, and may not contain a port number. The connection will be established on port number portNumber. This option Cannot be combined with xentara::utils::network::DefaultPort. xentara::utils::network::AddressFamily(addressFamily) Specifies a that the connection may only be established using addresses with 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 addresses of any address family are tried. You should usually not use this option, to allow communication over both IPv4 and IPv6. Only use this option if you are planning to communicate with legacy software that does not support IPv6. xentara::utils::network::Timeout(timeout) Specifies the timeout for the connect. If you do not specify this option, or if you specify std::nullopt for the timeout, an infinite timeout 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 wait, usually to shutdown and close the socket. If the stop source is triggered, the function will throw an exception of type io::StopRequested. If you do not specify this option, no stop source will be used. The returned socket is automatically associated with the given stop source.

Returns

A socket connected to the host name. If you specified a timeout, and the connection could not be completed within in the given time, a default constructed socket is returned. You can use the operator bool() to check whether the returned socket is valid.

Exceptions

std::runtime_error

An error occurred creating or connecting the socket

defaultTimeout()

static constexpr auto xentara::utils::network::SocketDevice::defaultTimeout ( ) -> std::chrono::nanoseconds

staticconstexprnoexcept

Gets the default timeout used if you do not specifiy a timeout.

Returns

The default timeout. The timeout is the default for both the read and the write timeouts.

See also

setReadTimeout()

setWriteTimeout()

io::InputDevice::readTimeout()

io::InputDevice::writeTimeout()

getOption()

template<typename Value >

auto xentara::utils::network::SocketDevice::getOption ( int  level, int  optionName, std::nothrow_t    ) const -> xentara::utils::eh::expected<Value, std::error_code>

noexcept

Gets a socket option.

This function behaves the same as option(), but returns an error code on error instead of throwing an exception. Use this function if you want to do your own error handling, like throwing an exception with a more descriptive what() string.

Template Parameters

Value

The type of the socket option's value. Each option requires a specific type of value. Refer to the documentation for the appropriate option for the supported types.

Parameters

level	The level at which the option resides. Must be SOL_SOCKET to get a socket level option, or one of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP, to get a protocol level options. Other socket levels may also be defined by the operating system.
optionName	The name of the option. This is an option level specific integer that describes which option to set.

Returns

The value of the option, or an error code on error

localAddress()

auto xentara::utils::network::SocketDevice::localAddress

(

)

const -> Address

Gets the local address of a bound or connected socket.

Returns

The local address of the socket.

Exceptions

std::runtime_error

An error occurred getting the socket address, or the socket is not bound and not connected.

native() [1/2]

auto xentara::utils::network::SocketDevice::native ( ) const -> int

noexcept

Gets the underlying Posix file descriptor for the socket.

Note

This function is not available under Windows.

Returns

The file descriptor, or -1 if no socket is open.

native() [2/2]

auto xentara::utils::network::SocketDevice::native ( ) const -> SOCKET

noexcept

Gets the underlying Windows Sockets 2 SOCKET.

Note

This function is only available under Windows.

Returns

The native socket, or INVALID_SOCKET if no socket is open.

operator bool()

xentara::utils::network::SocketDevice::operator bool ( ) const

explicitnoexcept

Checks whether the object contains a valid socket.

Returns

Returns true if the object contains a valid socket, or false if the object is default constructed, has been released using release(), or moved away using std::move() etc.

operator=() [1/3]

auto xentara::utils::network::SocketDevice::operator=

(

posix::File

socketFileDescriptor

)

-> SocketDevice &

Assignment operator for a Posix file descriptor.

This constructor takes ownership of the socket.

Parameters

socketFileDescriptor

The file descriptor of the new socket, or -1 to create a object that does not contain a socket. If socketFileDescriptor is not -1, it must be a socket of type SOCK_STREAM.

Returns

A reference to this object

operator=() [2/3]

internal auto xentara::utils::network::SocketDevice::operator=

(

Socket &&

socket

)

-> SocketDevice &

Assignment operator for a generic socket object.

Parameters

socket

The socket. This must be either a default-constructed socket, or a socket of type SOCK_STREAM.

Returns

A reference to this object

operator=() [3/3]

auto xentara::utils::network::SocketDevice::operator=

(

windows::Socket

socket

)

-> SocketDevice &

Assignment operator for a native Windows socket.

This constructor takes ownership of the socket.

Parameters

socket

The new socket, or INVALID_SOCKET to create a object that does not contain a socket. If socket is not INVALID_SOCKET, it must be of type SOCK_STREAM.

Returns

A reference to this object

option()

template<typename Value >

auto xentara::utils::network::SocketDevice::option	(	int	level,
		int	optionName
	)		const -> Value

Gets a socket option.

Template Parameters

Value

The type of the socket option's value. Each option requires a specific type of value. Refer to the documentation for the appropriate option for the supported types.

Parameters

level	The level at which the option resides. Must be SOL_SOCKET to get a socket level option, or one of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP, to get a protocol level options. Other socket levels may also be defined by the operating system.
optionName	The name of the option. This is an option level specific integer that describes which option to set.

Returns

The value of the option

Exceptions

std::runtime_error

An error occurred getting the option

protocol()

auto xentara::utils::network::SocketDevice::protocol ( ) const -> int

noexcept

Gets the protocol of the socket.

Returns

The protocol. XXXPROTO_YYY protocol defines, like IPPROTO_TCP. For default constructed objects, or if the protocol could not be determined, this function returns 0.

release() [1/2]

auto xentara::utils::network::SocketDevice::release ( ) -> int

noexcept

Removes the the socket and passes ownership to the caller.

After this call, this object will no longer contain a socket.

Note

This function is not available under Windows.

Returns

The file descriptor of the socket, or -1 if no socket was open. The caller must assume ownership of the file descriptor and close it when it is no longer needed.

release() [2/2]

auto xentara::utils::network::SocketDevice::release ( ) -> SOCKET

noexcept

Removes the socket and passes ownership to the caller.

After this call, this object will no longer contain a socket.

Note

This function is only available under Windows.

Returns

The native socket, or INVALID_SOCKET if the socket is open. The caller must assume ownership of the socket and close it when it is no longer needed.

remoteAddress()

auto xentara::utils::network::SocketDevice::remoteAddress

(

)

const -> Address

Gets the address that the socket is connected to.

Returns

The remote address of the socket.

Exceptions

std::runtime_error

An error occurred getting the socket address, or the socket is not connected.

setOption() [1/2]

template<typename Value >

auto xentara::utils::network::SocketDevice::setOption	(	int	level,
		int	optionName,
		const Value &	value
	)		-> void

Sets a socket option.

Template Parameters

Value

The type of the socket option's value. Each option requires a specific type of value. Refer to the documentation for the appropriate option for the supported types.

Parameters

level	The level at which the option resides. Must be SOL_SOCKET to set a socket level option, or one of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP, to set a protocol level option. Other socket levels may also be defined by the operating system.
optionName	The name of the option. This is an option level specific integer that describes which option to set.
value	The value to set

Exceptions

std::runtime_error

An error occurred setting the option

setOption() [2/2]

template<typename Value >

auto xentara::utils::network::SocketDevice::setOption ( int  level, int  optionName, const Value &  value, std::nothrow_t    ) -> std::error_code

noexcept

Sets a socket option without throwing exceptions.

This function behaves the same as setOption(), but returns an error code on error instead of throwing an exception. Use this function if you want to do your own error handling, like throwing an exception with a more descriptive what() string.

Parameters

level	The level at which the option resides. Must be SOL_SOCKET to get a socket level option, or one of the XXXPROTO_YYY protocol defines, like IPPROTO_TCP, to get a protocol level options. Other socket levels may also be defined by the operating system.
optionName	The name of the option. This is an option level specific integer that describes which option to set.
value	The value to set

Returns

Returns an error code on error, or std::error_code() on success.

setReadTimeout()

auto xentara::utils::network::SocketDevice::setReadTimeout ( std::chrono::nanoseconds  timeout )

noexcept

Sets the read timeout.

Parameters

timeout

The read timeout to used when new data is expected.

See also

io::InputDevice::readTimeout()

setTimeout()

auto xentara::utils::network::SocketDevice::setTimeout ( std::chrono::nanoseconds  timeout )

noexcept

Sets the read and write timeout to the same value.

Parameters

timeout

The read timeout to used when new data is expected.

See also

setReadTimeout()

setWriteTimeout()

io::InputDevice::readTimeout()

io::InputDevice::writeTimeout()

setWriteTimeout()

auto xentara::utils::network::SocketDevice::setWriteTimeout ( std::chrono::nanoseconds  timeout )

noexcept

Sets the write timeout.

Parameters

timeout

The read timeout to used when writing data.

See also

io::InputDevice::writeTimeout()

shutdown()

auto xentara::utils::network::SocketDevice::shutdown

(

Socket::Direction

directions = Socket::Direction::ReadWrite

)

-> void

Shuts down the socket.

Parameters

directions

Which directions to shut down.

Exceptions

std::runtime_error

An error occurred.

socket() [1/2]

auto xentara::utils::network::SocketDevice::socket ( ) && -> Socket &&

noexcept

Gets the socket as a generic socket.

Returns

The socket

socket() [2/2]

auto xentara::utils::network::SocketDevice::socket ( ) const & -> const Socket &

noexcept

Gets the socket as a generic socket.

Returns

The socket