xentara::utils::windows::Socket Class Reference

A Windows socket that closes itself on destruct. More...

#include <windows/Socket.hpp>

Inheritance diagram for xentara::utils::windows::Socket:

Public Types
using	NativeType = SOCKET
	A native Windows socket.

Public Member Functions
constexpr	Socket () noexcept=default
	Default constructor.
constexpr	Socket (SOCKET nativeSocket) noexcept
	Conversion from a native socket.
constexpr	Socket (Socket &&other) noexcept
	Move constructor.
	~Socket ()
	Destructor. Silently closes the socket.
auto	operator= (Socket &&rhs) noexcept -> Socket &
	Move assignment operator.
constexpr	operator SOCKET () const noexcept
	Conversion to a native socket.
constexpr	operator bool () const noexcept
	Checks whether the object contains a socket.
auto	operator= (SOCKET nativeSocket) noexcept -> Socket &
	Assignment from a native socket.
constexpr auto	release () noexcept -> SOCKET
	Removes the socket and passes ownership to the caller.
auto	close () noexcept -> bool
	Closes the socket, if any.
auto	performOverlappedIo (const std::function< auto(SOCKET, OVERLAPPED *) → BOOL > &operation, HANDLE event, std::optional< std::chrono::nanoseconds > timeout=std::nullopt) -> std::optional< DWORD >
	Performs an overlapped I/O operation.
auto	performOverlappedIo (const std::function< auto(SOCKET, OVERLAPPED *) → BOOL > &operation, std::span< HANDLE > waitObjects, std::optional< std::chrono::nanoseconds > timeout=std::nullopt) -> std::optional< OverlappedResult >
	Performs an overlapped I/O operation.

Static Public Attributes
static constexpr SOCKET	kInvalid { INVALID_SOCKET }
	An invalid socket.

Detailed Description

A Windows socket that closes itself on destruct.

This class can be moved but not copied.

Note

This class is only available under Windows

Member Typedef Documentation

NativeType

using xentara::utils::windows::Socket::NativeType = SOCKET

A native Windows socket.

Constructor & Destructor Documentation

Socket() [1/3]

constexpr xentara::utils::windows::Socket::Socket ( )

constexprdefaultnoexcept

Default constructor.

Creates an empty object that does not contain a socket.

Socket() [2/3]

constexpr xentara::utils::windows::Socket::Socket ( SOCKET  nativeSocket )

constexprnoexcept

Conversion from a native socket.

Parameters

nativeSocket

The native socket, or INVALID_SOCKET for none.

Socket() [3/3]

constexpr xentara::utils::windows::Socket::Socket ( Socket &&  other )

constexprnoexcept

Move constructor.

Takes ownership of the other object's socket, if any.

Parameters

other

The object to move. Will be reset and no longer contain a socket afterwards.

~Socket()

xentara::utils::windows::Socket::~Socket

(

)

Destructor. Silently closes the socket.

Member Function Documentation

close()

auto xentara::utils::windows::Socket::close ( ) -> bool

noexcept

Closes the socket, if any.

Returns

Returns true on success, or false on failure. The socket will be closed in either case, though.

operator bool()

constexpr xentara::utils::windows::Socket::operator bool ( ) const

explicitconstexprnoexcept

Checks whether the object contains a socket.

operator SOCKET()

constexpr xentara::utils::windows::Socket::operator SOCKET ( ) const

constexprnoexcept

Conversion to a native socket.

Returns

The contained socket, or INVALID_SOCKET for none.

operator=() [1/2]

auto xentara::utils::windows::Socket::operator= ( Socket &&  rhs ) -> Socket &

noexcept

Move assignment operator.

Takes ownership of the other socket's value. Any existing socket is silently closed.

Parameters

rhs	The object to move. Will be reset and no longer contain a socket afterwards.

operator=() [2/2]

auto xentara::utils::windows::Socket::operator= ( SOCKET  nativeSocket ) -> Socket &

noexcept

Assignment from a native socket.

Any existing socket is silently closed.

Parameters

nativeSocket

The native socket, or INVALID_SOCKET for none.

performOverlappedIo() [1/2]

auto xentara::utils::windows::Socket::performOverlappedIo	(	const std::function< auto(SOCKET, OVERLAPPED *) → BOOL > &	operation,
		HANDLE	event,
		std::optional< std::chrono::nanoseconds >	timeout = std::nullopt
	)		-> std::optional< DWORD >

Performs an overlapped I/O operation.

This function creates an OVERLAPPED structure and calls a function object with it. The function object must call a Windows overlapped socket function like WSARecv() or WSASend(), passing the overlapped structure to it, and return the result. The function must also preserve the error code stored in GetLastError(), specifically the error code ERROR_IO_PENDING, which the function uses to determine if waiting is necessary.

Parameters

operation

The operation to perform. operation will be called with the socket and an overlapped structure as parameters. It must return TRUE on success or FALSE on error. If FALSE is returned, the last error code must be set to an appropriate error. If an overlapped I/O operation is pending, the function must return FALSE and set the last error to ERROR_IO_PENDING in the manner of overlapped I/O functions like WSARecv() and WSASend().

Precondition

The socket must be an overlapped socket. Windows sockets are overlapped by default, unless you created the socket using WSASocket() and didn’t specify WSA_FLAG_OVERLAPPED in dwFlags.

Parameters

event	The event to use in the OVERLAPPED structure.
timeout	The timeout, or std::nullopt for infinite. Negative timeouts are treated the same as a timeout of 0.

Returns

Returns the number of bytes transferred on success, or std::nullopt on error. To get extended error information, call GetLastError(). On timeout, the last error is set to ERROR_OPERATION_ABORTED.

The meaning of “number of bytes transferred” depends on the overlapped operation. See the documentation of the lpNumberOfBytesTransferred parameter of GetOverlappedResult().

See also

Synchronization and Overlapped Input and Output in the Windows technical documentation

performOverlappedIo() [2/2]

auto xentara::utils::windows::Socket::performOverlappedIo	(	const std::function< auto(SOCKET, OVERLAPPED *) → BOOL > &	operation,
		std::span< HANDLE >	waitObjects,
		std::optional< std::chrono::nanoseconds >	timeout = std::nullopt
	)		-> std::optional< OverlappedResult >

Performs an overlapped I/O operation.

This function creates an OVERLAPPED structure and calls a function object with it. The function object must call a Windows overlapped socket function like WSARecv() or WSASend(), passing the overlapped structure to it, and return the result. The function must also preserve the error code stored in GetLastError(), specifically the error code ERROR_IO_PENDING, which the function uses to determine if waiting is necessary.

Parameters

operation

The operation to perform. operation will be called with the socket and an overlapped structure as parameters. It must return TRUE on success or FALSE on error. If FALSE is returned, the last error code must be set to an appropriate error. If an overlapped I/O operation is pending, the function must return FALSE and set the last error to ERROR_IO_PENDING in the manner of overlapped I/O functions like WSARecv() and WSASend().

Precondition

The socket must be an overlapped socket. Windows sockets are overlapped by default, unless you created the socket using WSASocket() and didn’t specify WSA_FLAG_OVERLAPPED in dwFlags.

Parameters

waitObjects	The objects to wait for. The first position in the span must contain the event to use in the OVERLAPPED structure.
timeout	The timeout, or std::nullopt for infinite. Negative timeouts are treated the same as a timeout of 0.

Returns

Returns the result of the operation on success, or std::nullopt on error. To get extended error information, call GetLastError(). On timeout, the last error is set to ERROR_OPERATION_ABORTED.

Exceptions

std::invalid_argument

waitObjects is empty, or contains more objects than Windows can handle.

See also

Synchronization and Overlapped Input and Output in the Windows technical documentation

release()

constexpr auto xentara::utils::windows::Socket::release ( ) -> SOCKET

constexprnoexcept

Removes the socket and passes ownership to the caller.

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

Returns

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

Member Data Documentation

kInvalid

constexpr SOCKET xentara::utils::windows::Socket::kInvalid { INVALID_SOCKET }

staticconstexpr

An invalid socket.