xentara::utils::network::SocketStream< Element > Class Template Reference

A stream socket that implements io::InputStream and io::OutputStream. More...

#include <network/SocketStream.hpp>

Inheritance diagram for xentara::utils::network::SocketStream< Element >:

Public Member Functions
	SocketStream () noexcept=default
	Default constructor.
	SocketStream (std::reference_wrapper< const io::StopSource > stopSource) noexcept
	Constructor that associates a stop source with the socket.
	SocketStream (SocketDevice &&device)
	Constructor from a socket device.
template<tools::OneOf< WithStopSource >... Options>
	SocketStream (Socket &&socket, Options... options)
	Constructor from a generic socket object.
template<tools::OneOf< Protocol, WithStopSource >... Options>
	SocketStream (int addressFamily, Options... options)
	Constructor that creates a stream socket.
template<tools::OneOf< WithStopSource >... Options>
	SocketStream (posix::File socketFileDescriptor, Options... options)
	Creates a socket object from a Posix file descriptor.
template<tools::OneOf< WithStopSource >... Options>
	SocketStream (windows::Socket socket, Options... options)
	Creates a socket object from a native Windows socket.
	~SocketStream () noexcept=default
	Noexcept Destructor.
internal auto	operator= (SocketDevice &&device) -> SocketStream &
	Assignment operator from a socket device.
auto	operator= (Socket &&socket) -> SocketStream &
	Assignment operator for a generic socket object.
auto	operator= (posix::File socketFileDescriptor) -> SocketStream &
	Assignment operator for a Posix file descriptor.
auto	operator= (windows::Socket socket) -> SocketStream &
	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	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.
Public Member Functions inherited from xentara::utils::io::AbstractBufferedInputStream< Element >
	AbstractBufferedInputStream ()=default
	Default constructor Creates a stream without a buffer.
Public Member Functions inherited from xentara::utils::io::InputStream< Element >
virtual	~InputStream () noexcept(false)=0
	Virtual, throwing destructor.
auto	readElement () -> Element
	Read a single element from the stream.
auto	tryReadElement () -> std::optional< Element >
	Tries to read a single element from a stream.
template<Element kNoMoreData>
auto	readElementOr () -> Element
	Tries to read a single element from a stream.
auto	peek () -> Element
	Look at the next element in the stream without actually reading it.
auto	tryPeek () -> std::optional< Element >
	Look at the next element in the stream without actually reading it.
template<Element kNoMoreData>
auto	peekOr () -> Element
	Look at the next element in the stream without actually reading it.
auto	readFromBuffer (std::size_t maxSize) -> std::span< const Element >
	Reads data from the buffer only.
auto	eof () -> bool
	Checks if the end of the stream has been reached.
template<Element... kAllowedElements>
auto	readElementIf () -> std::optional< Element >
	Read an element from the stream if it is one of a list of allowed elements.
template<std::predicate< Element > Predicate>
auto	readElementIf (Predicate predicate) -> std::optional< Element >
	Read an element from the stream if it fits a predicate.
template<Element kFallback, Element... kAllowedElements>
auto	readElementIfOr () -> Element
	Read an element from the stream if it is one of a list of allowed elements.
template<Element kFallback, std::predicate< Element > Predicate>
auto	readElementIfOr (Predicate predicate) -> Element
	Read an element from the stream if it fits a predicate.
template<tools::Allocator< Element > Allocator = std::allocator<Element>> requires (!tools::CharType<Element>)
auto	read (typename std::allocator_traits< Allocator >::size_type size, const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Read a block of data of a specific size.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	read (typename std::allocator_traits< Allocator >::size_type size, const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Read a block of text of a specific size.
template<std::size_t kArraySize>
auto	read (Element(&array)[kArraySize]) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	read (std::array< Element, kArraySize > &array) -> void
	Read a block of 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>>, Element>
auto	read (Iterator first, Sentinel last) -> void
	Read a block of data into an iterator range.
auto	read (Element *buffer, std::size_t size) -> void
	Read a block of data into a buffer.
template<Element... kTerminations> requires (!tools::CharType<Element>)
auto	readUntil () -> core::RawVector< Element >
	Reads all elements until a termination is found.
template<tools::Allocator< Element > Allocator, Element... kTerminations> requires (!tools::CharType<Element>)
auto	readUntil (const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Reads all elements until a termination is found.
template<tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readUntil (Predicate predicate, const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Skips all elements until a termination element that fits a predicate.
template<Element... kTerminations> requires tools::CharType<Element>
auto	readUntil () -> std::basic_string< Element >
	Reads all characters until a termination is found.
template<typename CharTraits , Element... kTerminations> requires tools::CharType<Element>
auto	readUntil () -> std::basic_string< Element, CharTraits >
	Reads all characters until a termination is found.
template<typename CharTraits , tools::Allocator< Element > Allocator, Element... kTerminations> requires tools::CharType<Element>
auto	readUntil (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads all characters until a termination is found.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readUntil (Predicate predicate, const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Skips all characters until a termination character that fits a predicate.
auto	skipElement () -> void
	Skips a single element from the stream.
auto	trySkipElement () -> bool
	Tries to skip a single element from a stream.
auto	skip (std::size_t size) -> void
	Skips a block of data.
template<Element... kSkippableElements>
auto	skipWhile () -> std::size_t
	Skips all elements than appear in a list of skippable elements.
template<std::predicate< Element > Predicate>
auto	skipWhile (Predicate predicate) -> std::size_t
	Skips all elements that fit a predicate.
auto	readPosition () const -> std::optional< ReadPosition >
	Gets the current read position within the stream.
auto	setReadPosition (ReadPosition position) -> void
	Sets the current read position within the device.
auto	rewind () -> void
	Sets the current read position to the beginning of the stream.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	readLine (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads a single line.
auto	skipLine () -> std::size_t
	Skips the rest of the line.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	readWord (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads a single whitespace-separated word.
auto	skipWord () -> std::size_t
	Skips the rest of a whitespace-separated word.
auto	skipLineEnding () -> bool
	Skips a single line termination.
auto	skipWhitespace () -> bool
	Skips all ASCII whitespace elements.
auto	readByte () -> Element
	Alternate name for readElement()
auto	tryReadByte () -> std::optional< Element >
	Alternate name for tryReadElement()
template<Element kNoMoreData> requires (!tools::CharType<Element>)
auto	readByteOr () -> Element
	Alternate name for readElementOr()
template<Element... kAllowedElements> requires (!tools::CharType<Element>)
auto	readByteIf () -> std::optional< Element >
	Alternate name for readElementIf()
template<std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readByteIf (Predicate predicate) -> std::optional< Element >
	Alternate name for readElementIf().
template<Element kFallback, Element... kAllowedElements> requires (!tools::CharType<Element>)
auto	readByteIfOr () -> Element
	Alternate name for readElementIfOr()
template<Element kFallback, std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readByteIfOr (Predicate predicate) -> Element
	Alternate name for readElementIfOr().
auto	skipByte () -> void
	Alternate name for skipElement()
auto	trySkipByte () -> bool
	Alternate name for trySkipElement() for character streams.
auto	readChar () -> Element
	Alternate name for readElement()
auto	tryReadChar () -> std::optional< Element >
	Alternate name for tryReadElement()
template<Element kNoMoreData> requires tools::CharType<Element>
auto	readCharOr () -> Element
	Alternate name for readElementOr()
template<Element... kAllowedElements> requires tools::CharType<Element>
auto	readCharIf () -> std::optional< Element >
	Alternate name for readElementIf()
template<std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readCharIf (Predicate predicate) -> std::optional< Element >
	Alternate name for readElementIf().
template<Element kFallback, Element... kAllowedElements> requires tools::CharType<Element>
auto	readCharIfOr () -> Element
	Alternate name for readElementIfOr()
template<Element kFallback, std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readCharIfOr (Predicate predicate) -> Element
	Alternate name for readElementIfOr().
auto	skipChar () -> void
	Alternate name for skipElement()
auto	trySkipChar () -> bool
	Alternate name for trySkipElement() for character streams.
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.
Public Member Functions inherited from xentara::utils::io::StreamBase
virtual	~StreamBase () noexcept(false)=0
	Virtual, throwing destructor.
auto	streamDescription () const -> std::string
	Get a description of the device.
Public Member Functions inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
	AbstractBufferedOutputStream ()=default
	Default constructor Creates a stream without a buffer.
Public Member Functions inherited from xentara::utils::io::OutputStream< Element >
virtual	~OutputStream () noexcept(false)=0
	Virtual, throwing destructor.
auto	write (Element element) -> void
	Write a single element to the stream.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, Element>
auto	write (const Data &data) -> void
	Write a block of data.
template<std::size_t kDataSize>
auto	write (const Element(&data)[kDataSize]) -> void
	Write a block of data contained in an array.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, Element>
auto	write (Iterator first, Sentinel last) -> void
	Write a block of data contained in an iterator range.
auto	write (const Element *data, std::size_t size) -> void
	Write a block of data contained in a region of memory.
auto	write (const Element *nullTerminatedString) -> void
	Write a NULL-teminated string.
auto	flush () -> void
	Flushes the buffer.

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) -> SocketStream
	Creates a socket that is compatible with an address.
template<tools::OneOf< Protocol, Timeout, WithStopSource >... Options>
static auto	connectedSocket (const Address &address, Options... options) -> SocketStream
	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) -> SocketStream
	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) -> SocketStream
	Creates a socket that is connected to a named host.

Protected Member Functions
auto	doGetStreamDescription () const -> std::string final
	Implementation of InputStream::doGetStreamDescription()
Protected Member Functions inherited from xentara::utils::io::AbstractDeviceInputStream< Element >
virtual auto	inputDevice () noexcept -> InputDevice &=0
	Called by the framework to get the device.
auto	doRead (Element *buffer, std::size_t size, bool waitForData) -> std::optional< std::size_t > final
	Implementation of InputStream::doRead()
virtual auto	doThrowEndOfStreamError () const -> void final
	Implementation of InputStream::doRead()
auto	doWaitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool final
	Implementation of InputStream::doWaitForData()
auto	doGetReadPosition () const -> std::optional< std::size_t > final
	Implementation of InputStream::doGetReadPosition()
auto	doSetReadPosition (std::size_t position) -> bool final
	Implementation of InputStream::doSetReadPosition()
auto	doAdvanceReadPosition (std::size_t offset) -> std::optional< std::size_t > final
	Implementation of InputStream::doAdvanceReadPosition()
Protected Member Functions inherited from xentara::utils::io::AbstractBufferedInputStream< Element >
auto	resetInputBuffer (std::size_t bufferSizeHint=kDefaultBufferSize) -> void
	Resets the buffer.
auto	destroyInputBuffer () -> void
	Destroys the buffer.
Protected Member Functions inherited from xentara::utils::io::InputStream< Element >
	InputStream () noexcept=default
	Default constructor.
	InputStream (Element *bufferBegin, Element *bufferEnd) noexcept
	Constructor that sets an initially empty buffer.
	InputStream (Element *bufferBegin, Element *bufferEnd, Element *dataBegin, Element *dataEnd) noexcept
	Constructor that sets a buffer that possibly already contains some data.
	InputStream (InputStream &&other) noexcept
	Move constructor.
auto	operator= (InputStream &&rhs) noexcept -> InputStream &
	Move assignemnt operator.
auto	setReadBuffer (Element *bufferBegin, Element *bufferEnd) noexcept -> void
	Sets a new empty buffer.
auto	setReadBuffer (Element *bufferBegin, Element *bufferEnd, Element *dataBegin, Element *dataEnd) noexcept -> void
	Sets the buffer.
auto	setReadData (Element *dataBegin, Element *dataEnd) noexcept -> void
	Sets the position of the data within the buffer.
auto	readBufferBegin () const -> Element *
	Reads back the buffer start position.
auto	readBufferEnd () const -> Element *
	Reads back the buffer end position.
auto	readBufferSize () const -> std::size_t
	Gets the buffer size.
auto	readDataBegin () const -> Element *
	Returns the beginning of the unconsumed data in the buffer.
auto	readDataEnd () const -> Element *
	Returns the end of the data in the buffer.
auto	readDataSize () const -> std::size_t
	Returns the size of the unconsumed data in the buffer.
virtual auto	doReplenishReadBuffer (bool waitForData) -> bool
	Called by the framework to place more data into the buffer when it is exhausted.
Protected Member Functions inherited from xentara::utils::io::AbstractDeviceOutputStream< Element >
virtual auto	outputDevice () noexcept -> OutputDevice &=0
	Called by the framework to get the device.
auto	doWrite (const Element *data, std::size_t size) -> std::size_t final
	Implementation of InputStream::doWrite()
Protected Member Functions inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
auto	resetOutputBuffer (std::size_t bufferSizeHint=kDefaultBufferSize) -> void
	Resets the buffer.
auto	destroyOutputBuffer () -> void
	Destroys the buffer.
Protected Member Functions inherited from xentara::utils::io::OutputStream< Element >
	OutputStream () noexcept=default
	Default constructor.
	OutputStream (Element *bufferBegin, Element *bufferEnd) noexcept
	Constructor that sets an initially empty buffer.
	OutputStream (Element *bufferBegin, Element *bufferEnd, Element *dataEnd) noexcept
	Constructor that sets a buffer that possibly already contains some data.
	OutputStream (OutputStream &&other) noexcept
	Move constructor.
auto	operator= (OutputStream &&rhs) noexcept -> OutputStream &
	Move assignemnt operator.
auto	setWriteBuffer (Element *bufferBegin, Element *bufferEnd) noexcept -> void
	Sets a new empty buffer.
auto	setWriteBuffer (Element *bufferBegin, Element *bufferEnd, Element *dataEnd) noexcept -> void
	Sets the buffer.
auto	setWriteDataEnd (Element *dataEnd) noexcept -> void
	Sets the end of the data within the buffer.
auto	writeBufferBegin () const -> Element *
	Writes back the buffer start position.
auto	writeBufferEnd () const -> Element *
	Writes back the buffer end position.
auto	writeBufferSize () const -> std::size_t
	Gets the buffer size.
auto	writeDataBegin () const -> Element *
	Returns the beginning of data in the buffer.
auto	writeDataEnd () const -> Element *
	Returns the end of the data in the buffer.
auto	writeDataSize () const -> std::size_t
	Returns the size of the unwritten data in the buffer.
auto	freeBufferBegin () const -> Element *
	Returns the beginning of the free region of the buffer.
auto	freeBufferSize () const -> std::size_t
	Returns the size of the unwritten data in the buffer.
virtual auto	doFlushWriteBuffer () -> void
	Called by the framework to write the buffered data to the underlying device once it is full.

Additional Inherited Members
Public Types inherited from xentara::utils::io::InputStream< Element >
using	element_type = Element
	The element type.
Public Types inherited from xentara::utils::io::OutputStream< Element >
using	element_type = Element
	The element type.
Static Protected Attributes inherited from xentara::utils::io::AbstractBufferedInputStream< Element >
static const std::size_t	kDefaultBufferSize
	The default buffer size.
Static Protected Attributes inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
static const std::size_t	kDefaultBufferSize
	The default buffer size.

Detailed Description

template<io::StreamElement Element>
requires (sizeof(Element) == sizeof(std::byte))
class xentara::utils::network::SocketStream< Element >

A stream socket that implements io::InputStream and io::OutputStream.

Constructor & Destructor Documentation

SocketStream() [1/7]

template<io::StreamElement Element>

xentara::utils::network::SocketStream< Element >::SocketStream ( )

defaultnoexcept

Default constructor.

Creates an invalid socket object.

SocketStream() [2/7]

template<io::StreamElement Element>

xentara::utils::network::SocketStream< Element >::SocketStream ( 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

SocketStream() [3/7]

template<io::StreamElement Element>

xentara::utils::network::SocketStream< Element >::SocketStream

(

SocketDevice &&

device

)

Constructor from a socket device.

Parameters

device

The socket device.

SocketStream() [4/7]

template<io::StreamElement Element>

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

xentara::utils::network::SocketStream< Element >::SocketStream	(	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::SocketStream 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.

SocketStream() [5/7]

template<io::StreamElement Element>

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

xentara::utils::network::SocketStream< Element >::SocketStream ( 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::SocketStream 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

SocketStream() [6/7]

template<io::StreamElement Element>

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

xentara::utils::network::SocketStream< Element >::SocketStream	(	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::SocketStream 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.

SocketStream() [7/7]

template<io::StreamElement Element>

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

xentara::utils::network::SocketStream< Element >::SocketStream	(	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::SocketStream 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.

~SocketStream()

template<io::StreamElement Element>

xentara::utils::network::SocketStream< Element >::~SocketStream ( )

defaultnoexcept

Noexcept Destructor.

This class's constructor never throws an exception

Member Function Documentation

addressFamily()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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 if the protocol does not use port numbers.

Exceptions

std::runtime_error

An error occurred binding the socket

close()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::close ( ) -> void

noexcept

Closes the socket, if one is open.

compatibleSocket()

template<io::StreamElement Element>

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

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

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]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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<io::StreamElement Element>

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

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

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::SocketStream::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<io::StreamElement Element>

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

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

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::SocketStream::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<io::StreamElement Element>

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

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

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::SocketStream::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()

template<io::StreamElement Element>

static constexpr auto xentara::utils::network::SocketStream< Element >::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::InputStream::readTimeout()

io::InputStream::writeTimeout()

doGetStreamDescription()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::doGetStreamDescription ( ) const -> std::string

finalprotectedvirtual

Implementation of InputStream::doGetStreamDescription()

Reimplemented from xentara::utils::io::AbstractDeviceInputStream< Element >.

getOption()

template<io::StreamElement Element>

template<typename Value >

auto xentara::utils::network::SocketStream< Element >::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()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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()

template<io::StreamElement Element>

xentara::utils::network::SocketStream< Element >::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/4]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::operator=

(

posix::File

socketFileDescriptor

)

-> SocketStream &

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/4]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::operator=

(

Socket &&

socket

)

-> SocketStream &

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/4]

template<io::StreamElement Element>

internal auto xentara::utils::network::SocketStream< Element >::operator=

(

SocketDevice &&

device

)

-> SocketStream &

Assignment operator from a socket device.

Parameters

device

The socket device.

Returns

A reference to this object

operator=() [4/4]

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::operator=

(

windows::Socket

socket

)

-> SocketStream &

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<io::StreamElement Element>

template<typename Value >

auto xentara::utils::network::SocketStream< Element >::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()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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.

remoteAddress()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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<io::StreamElement Element>

template<typename Value >

auto xentara::utils::network::SocketStream< Element >::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<io::StreamElement Element>

template<typename Value >

auto xentara::utils::network::SocketStream< Element >::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()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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::InputStream::readTimeout()

setTimeout()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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::InputStream::readTimeout()

io::InputStream::writeTimeout()

setWriteTimeout()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::setWriteTimeout ( std::chrono::nanoseconds  timeout )

noexcept

Sets the write timeout.

Parameters

timeout

The read timeout to used when writing data.

See also

io::InputStream::writeTimeout()

shutdown()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::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()

template<io::StreamElement Element>

auto xentara::utils::network::SocketStream< Element >::socket ( ) const & -> const Socket &

noexcept

Gets the socket as a generic socket.

Returns

The socket