ConcurrentTasks Docs

Socket class

Owns one Winsock SOCKET and wraps the Winsock calls on it.

Use: import ThinkMeta.ConcurrentTasks.Windows.Socket;
Namespace: ThinkMeta::ConcurrentTasks::Windows

Syntax

class Socket

Remarks

The socket is closed on destruction. Socket::Startup must have succeeded before any other use: it calls WSAStartup and loads the extension functions (AcceptEx, ConnectEx, DisconnectEx, GetAcceptExSockaddrs, TransmitFile, TransmitPackets, WSARecvMsg, WSASendMsg) that Socket::AcceptAsync, Socket::ConnectAsync etc. call through. Errors are reported as WinsockErrorCode (WinsockError::Success or a WSA* code from WSAGetLastError); nothing throws. The caller meets the preconditions (the object holds a socket, required pointers are given); Debug builds assert them. The plain calls (Socket::Bind, Socket::Connect, Socket::Listen, Socket::Shutdown, options ...) are ordinary Winsock calls: on a blocking socket a blocking call (e.g. Connect) blocks the OS thread, it does not suspend a task - use AsyncIo::AsyncSocket's forms inside tasks. The XxxAsync(..., OVERLAPPED) forms only start an overlapped operation and return Success (completed synchronously), WinsockError::Pending or the WSA error; completing, waiting and lifetime of the OVERLAPPED and buffers are the caller's business (AsyncSocket ties them to the core's completion port). Several operations may be outstanding at once, each with its own OVERLAPPED. Calls that change the object (Socket::Create, Socket::Close, assignment) must not run concurrently with other calls on it.

See also

AsyncIo::AsyncSocket, IpSocket

Constructors

Socket

Creates an object without a socket.

Syntax

Socket() noexcept;

Takes over other's socket; other is left without one.

Syntax

Socket(Socket&& other) noexcept;

Parameters

otherSocket&&: The object whose socket is taken over; it holds no socket afterwards.

~Socket

Closes the socket if there is one (see Close).

Syntax

~Socket() noexcept;

Methods

Startup

Initializes Winsock 2.2 (WSAStartup) and loads the extension functions.

Syntax

static WinsockErrorCode Startup() noexcept;

Return value

Type: WinsockErrorCode

WinsockError::Success, the error of WSAStartup, or the error of creating the helper socket or loading an extension pointer (then Winsock has been cleaned up again).

Remarks

Call once per process (or per Cleanup) before any socket is created, from any thread. Calls are counted by Winsock; balance each successful Startup with Cleanup.

See also

Cleanup

Takes back one Startup (WSACleanup); no socket may be in use any more.

Syntax

static WinsockErrorCode Cleanup() noexcept;

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of WSACleanup.

See also

operator=

Takes over other's socket; other is left without one.

Syntax

Socket& operator=(Socket&& other) noexcept;

Parameters

otherSocket&&: The object whose socket is taken over; it holds no socket afterwards.

Return value

Type: Socket&

This object.

Remarks

A socket this object already holds is closed first (see Close).

IsValid

true if the object holds a socket.

Syntax

bool IsValid() const noexcept;

Return value

Type: bool

true if the object holds a socket; false if it has none.

Create

Creates the socket (WSASocket; parameters as there).

Syntax

WinsockErrorCode Create(
    int addressFamily,
    int type,
    int protocol,
    WSAPROTOCOL_INFO* protocolInfo = nullptr,
    GROUP g = 0,
    DWORD flags = 0
) noexcept;

Parameters

addressFamilyint: The address family, e.g. AF_INET or AF_INET6.
typeint: The socket type, e.g. SOCK_STREAM or SOCK_DGRAM.
protocolint: The protocol, e.g. IPPROTO_TCP or IPPROTO_UDP; 0 lets the provider choose.
protocolInfoWSAPROTOCOL_INFO*: Optional WSAPROTOCOL_INFO that selects the provider (and overrides the first three parameters when they are FROM_PROTOCOL_INFO); nullptr for the default.Default: nullptr
gGROUP: The socket group (0 for none, which is the usual value).Default: 0
flagsDWORD: WSA_FLAG_* flags, e.g. WSA_FLAG_OVERLAPPED.Default: 0

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of WSASocket.

Remarks

The object must not hold a socket yet. Add WSA_FLAG_OVERLAPPED to flags for overlapped operations; AsyncIo::AsyncSocket::Create does that and associates the socket with the core's completion port.

See also

Close, Startup

Close

Closes the socket (closesocket), if there is one; the object is then without socket.

Syntax

WinsockErrorCode Close() noexcept;

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of closesocket.

Remarks

Closing aborts pending overlapped operations (they complete with WinsockError::OperationAborted); their OVERLAPPED and buffers must stay valid until those completions have been delivered.

See also

Create, CancelAllAsyncRequests

AcceptAsync

Starts an AcceptEx on this listening socket (raw OVERLAPPED form).

Syntax

WinsockErrorCode AcceptAsync(
    Socket& acceptSocket,
    void* outputBuffer,
    DWORD receiveDataLength,
    DWORD localAddressLength,
    DWORD remoteAddressLength,
    DWORD* bytesReceived,
    OVERLAPPED& overlapped
) const noexcept;

Parameters

acceptSocketSocket&: Takes the accepted connection. A created, unbound and unconnected socket.
outputBuffervoid*: Receives the first receiveDataLength bytes of data followed by the local and remote address (parse with GetAcceptExSockaddrs). Must stay valid until completion.
receiveDataLengthDWORD: Bytes of initial data to wait for; 0 completes as soon as a connection arrives, otherwise only after that data (or the connection's end).
localAddressLengthDWORD: Space reserved for the local address: at least the address size + 16.
remoteAddressLengthDWORD: Space reserved for the remote address: at least the address size + 16.
bytesReceivedDWORD*: Required. Receives the byte count on synchronous completion.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Remarks

See also AsyncIo::AsyncSocket::AcceptAsync. After the accept has completed, call acceptSocket.SetOptionUpdateAcceptContext(*this).

See also

Bind

Binds the socket to addr (bind).

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode Bind(const _SockAddr& addr) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

addrconst _SockAddr&: The local address and port; port 0 lets the system choose one.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of bind.

Connect

Connects to addr (connect); blocks the calling thread on a blocking socket.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode Connect(const _SockAddr& addr) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

addrconst _SockAddr&: The remote address and port.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of connect.

See also

Connects with WSAConnect (caller/callee data, QoS).

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode Connect(
    const _SockAddr& addr,
    WSABUF* callerData,
    WSABUF* calleeData,
    QOS* sQos
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

addrconst _SockAddr&: The remote address and port.
callerDataWSABUF*: Optional user data sent to the peer during connection setup; nullptr for none.
calleeDataWSABUF*: Optional; receives user data sent back by the peer during connection setup.
sQosQOS*: Optional flow specifications (QOS) for the socket; nullptr for none.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of WSAConnect.

Remarks

Blocks the calling thread on a blocking socket.

ConnectAsync

Starts a ConnectEx (raw OVERLAPPED form).

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode ConnectAsync(
    const _SockAddr& addr,
    void* sendBuffer,
    DWORD sendDataLength,
    DWORD* bytesSent,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

addrconst _SockAddr&: The remote address and port.
sendBuffervoid*: Optional data sent once connected; bytesSent is required with it.
sendDataLengthDWORD: The size of sendBuffer in bytes; 0 without send data.
bytesSentDWORD*: Required when sendBuffer is given; receives the bytes sent on synchronous completion.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Remarks

The socket must be bound first (Bind). After the connect has completed, call SetOptionUpdateConnectContext.

See also

AsyncIo::AsyncSocket::ConnectAsync

Starts a ConnectEx to an address of a given size (raw OVERLAPPED form).

Syntax

WinsockErrorCode ConnectAsync(
    const sockaddr* addr,
    int addrSize,
    void* sendBuffer,
    DWORD sendDataLength,
    DWORD* bytesSent,
    OVERLAPPED& overlapped
) noexcept;

Parameters

addrconst sockaddr*: Required; e.g. a sockaddr_in or sockaddr_in6 (or a sockaddr_storage holding one).
addrSizeint: The size of the actual address at addr, e.g. sizeof(sockaddr_in).
sendBuffervoid*: Optional data sent once connected; bytesSent is required with it.
sendDataLengthDWORD: The size of sendBuffer in bytes; 0 without send data.
bytesSentDWORD*: Required when sendBuffer is given; receives the bytes sent on synchronous completion.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Remarks

The socket must be bound first (Bind). After the connect has completed, call SetOptionUpdateConnectContext.

See also

AsyncIo::AsyncSocket::ConnectAsync

DisconnectAsync

Starts a DisconnectEx (raw OVERLAPPED form).

Syntax

WinsockErrorCode DisconnectAsync(OVERLAPPED& overlapped, DWORD flags = 0) noexcept;

Parameters

overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.
flagsDWORD: 0 or TF_REUSE_SOCKET (the socket can then be passed to AcceptAsync/ ConnectAsync again).Default: 0

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

GetPeerName

Gets the peer's address (getpeername).

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode GetPeerName(_SockAddr& addr) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the buffer length.

Parameters

addr_SockAddr&: Receives the peer's address; must be large enough for the socket's address family.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getpeername.

See also

GetSockName

Gets the local address (getsockname), e.g. the port chosen by Bind with port 0.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode GetSockName(_SockAddr& addr) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the buffer length.

Parameters

addr_SockAddr&: Receives the local address; must be large enough for the socket's address family.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockname.

See also

GetOption

Gets a socket option into a raw buffer (getsockopt).

Syntax

WinsockErrorCode GetOption(
    int level,
    int optionName,
    char* optionValue,
    int* valueLength
) noexcept;

Parameters

levelint: The option level, e.g. SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP.
optionNameint: The option at that level, e.g. SO_RCVBUF.
optionValuechar*: Required. Receives the option value.
valueLengthint*: Required. In: the size of optionValue in bytes; out: the size written.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

See also

Gets a socket option of type T (buffer size sizeof(T)).

Syntax

template <typename T>
WinsockErrorCode GetOption(int level, int optionName, T* optionValue) noexcept;

Template parameters

Ttypename: The option's value type, e.g. DWORD or linger.

Parameters

levelint: The option level, e.g. SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP.
optionNameint: The option at that level, e.g. SO_RCVBUF.
optionValueT*: Required. Receives the option value.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

Gets a BOOL-sized socket option as bool.

Syntax

template <>
WinsockErrorCode GetOption<bool>(
    int level,
    int optionName,
    bool* optionValue
) noexcept;

Parameters

levelint: The option level, e.g. SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP.
optionNameint: The option at that level, e.g. SO_KEEPALIVE.
optionValuebool*: Required. Receives true if the option is set (non-zero); unchanged on failure.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOption

Sets a socket option from a raw buffer (setsockopt).

Syntax

WinsockErrorCode SetOption(
    int level,
    int optionName,
    const char* optionValue,
    int valueLength
) noexcept;

Parameters

levelint: The option level, e.g. SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP.
optionNameint: The option at that level, e.g. SO_RCVBUF.
optionValueconst char*: Required. The new option value.
valueLengthint: The size of optionValue in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

See also

Sets a socket option that takes no value (e.g. SO_UPDATE_CONNECT_CONTEXT).

Syntax

WinsockErrorCode SetOption(int level, int option) noexcept;

Parameters

levelint: The option level, e.g. SOL_SOCKET.
optionint: The option at that level.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

Sets a socket option from a value of type T.

Syntax

template <typename T>
WinsockErrorCode SetOption(
    int level,
    int optionName,
    const T& optionValue
) noexcept;

Template parameters

Ttypename: The option's value type, e.g. DWORD or linger.

Parameters

levelint: The option level, e.g. SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP.
optionNameint: The option at that level, e.g. SO_RCVBUF.
optionValueconst T&: The new option value.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

Remarks

The value is passed by address with size sizeof(T).

Sets a BOOL-sized socket option from bool.

Syntax

template <>
WinsockErrorCode SetOption<bool>(
    int level,
    int optionName,
    const bool& optionValue
) noexcept;

Parameters

levelint: The option level, e.g. SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP.
optionNameint: The option at that level, e.g. SO_KEEPALIVE.
optionValueconst bool&: true to enable the option, false to disable it.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

Shutdown

Disables sends and/or receives (shutdown).

Syntax

WinsockErrorCode Shutdown(int how) noexcept;

Parameters

howint: SD_RECEIVE, SD_SEND or SD_BOTH.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of shutdown.

See also

DisconnectAsync

SetOptionProviderConfiguration

Sets the service provider's configuration data (PVD_CONFIG).

Syntax

WinsockErrorCode SetOptionProviderConfiguration(
    const char* configuration,
    int length
) noexcept;

Parameters

configurationconst char*: Required. The provider-specific configuration data.
lengthint: The size of configuration in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionProviderConfiguration

Gets the service provider's configuration data (PVD_CONFIG).

Syntax

WinsockErrorCode GetOptionProviderConfiguration(
    char* configuration,
    int* length
) noexcept;

Parameters

configurationchar*: Required. Receives the provider-specific configuration data.
lengthint*: Required. In: the size of configuration in bytes; out: the bytes written.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionIsListening

Gets whether the socket is listening (SO_ACCEPTCONN).

Syntax

WinsockErrorCode GetOptionIsListening(bool* isListening) noexcept;

Parameters

isListeningbool*: Required. Receives true if the socket is in listening state.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionBroadcast

Enables sending broadcast messages (SO_BROADCAST).

Syntax

WinsockErrorCode SetOptionBroadcast(bool enable) noexcept;

Parameters

enablebool: true to allow sending to broadcast addresses, false to forbid it.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionBroadcast

Gets whether broadcast is enabled (SO_BROADCAST).

Syntax

WinsockErrorCode GetOptionBroadcast(bool* enable) noexcept;

Parameters

enablebool*: Required. Receives true if sending broadcast messages is allowed.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionBspState

Gets the local and remote address (SO_BSP_STATE).

Syntax

WinsockErrorCode GetOptionBspState(void* buffer, int* length) noexcept;

Parameters

buffervoid*: Receives a CSADDR_INFO followed by the addresses it points to.
lengthint*: In: the size of buffer; out: the bytes written. A CSADDR_INFO plus two SOCKADDR_STORAGE is always enough.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionConditionalAccept

Enables conditional accept (WSAAccept condition function) (SO_CONDITIONAL_ACCEPT).

Syntax

WinsockErrorCode SetOptionConditionalAccept(bool accept) noexcept;

Parameters

acceptbool: true to enable conditional accept, false to disable it.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionConditionalAccept

Gets whether conditional accept is enabled (SO_CONDITIONAL_ACCEPT).

Syntax

WinsockErrorCode GetOptionConditionalAccept(bool* accept) noexcept;

Parameters

acceptbool*: Required. Receives true if conditional accept is enabled.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionConnectionData

Sets the connect data (protocols that support it) (SO_CONNDATA).

Syntax

WinsockErrorCode SetOptionConnectionData(const char* data, int length) noexcept;

Parameters

dataconst char*: Required. The data to send with the connection request.
lengthint: The size of data in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionConnectionData

Gets the connect data (SO_CONNDATA).

Syntax

WinsockErrorCode GetOptionConnectionData(char* data, int* length) noexcept;

Parameters

datachar*: Required. Receives the connect data.
lengthint*: Required. In: the size of data in bytes; out: the bytes written.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionConnectionDataLength

Sets the length of the connect data buffer (SO_CONNDATALEN).

Syntax

WinsockErrorCode SetOptionConnectionDataLength(ULONG length) noexcept;

Parameters

lengthULONG: The buffer size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionConnectionTime

Gets the seconds the socket has been connected (SO_CONNECT_TIME).

Syntax

WinsockErrorCode GetOptionConnectionTime(ULONG* connectTime) noexcept;

Parameters

connectTimeULONG*: Required. Receives the connection time in seconds.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

Remarks

0xFFFFFFFF if not connected.

SetOptionConnectOptionData

Sets the connect options data (SO_CONNOPT).

Syntax

WinsockErrorCode SetOptionConnectOptionData(const char* data, int length) noexcept;

Parameters

dataconst char*: Required. The connect options data.
lengthint: The size of data in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionConnectOptionData

Gets the connect options data (SO_CONNOPT).

Syntax

WinsockErrorCode GetOptionConnectOptionData(char* data, int* length) noexcept;

Parameters

datachar*: Required. Receives the connect options data.
lengthint*: Required. In: the size of data in bytes; out: the bytes written.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionConnectOptionDataLength

Sets the length of the connect options buffer (SO_CONNOPTLEN).

Syntax

WinsockErrorCode SetOptionConnectOptionDataLength(ULONG length) noexcept;

Parameters

lengthULONG: The buffer size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

SetOptionDisconnectionData

Sets the disconnect data (SO_DISCDATA).

Syntax

WinsockErrorCode SetOptionDisconnectionData(const char* data, int length) noexcept;

Parameters

dataconst char*: Required. The data to send with the disconnect.
lengthint: The size of data in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionDisconnectionData

Gets the disconnect data (SO_DISCDATA).

Syntax

WinsockErrorCode GetOptionDisconnectionData(char* data, int* length) noexcept;

Parameters

datachar*: Required. Receives the disconnect data.
lengthint*: Required. In: the size of data in bytes; out: the bytes written.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionDisconnectionDataLength

Sets the length of the disconnect data buffer (SO_DISCDATALEN).

Syntax

WinsockErrorCode SetOptionDisconnectionDataLength(ULONG length) noexcept;

Parameters

lengthULONG: The buffer size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

SetOptionDisconnectOptionData

Sets the disconnect options data (SO_DISCOPT).

Syntax

WinsockErrorCode SetOptionDisconnectOptionData(
    const char* data,
    int length
) noexcept;

Parameters

dataconst char*: Required. The disconnect options data.
lengthint: The size of data in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionDisconnectOptionData

Gets the disconnect options data (SO_DISCOPT).

Syntax

WinsockErrorCode GetOptionDisconnectOptionData(char* data, int* length) noexcept;

Parameters

datachar*: Required. Receives the disconnect options data.
lengthint*: Required. In: the size of data in bytes; out: the bytes written.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionDisconnectOptionDataLength

Sets the length of the disconnect options buffer (SO_DISCOPTLEN).

Syntax

WinsockErrorCode SetOptionDisconnectOptionDataLength(ULONG length) noexcept;

Parameters

lengthULONG: The buffer size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

SetOptionDebug

Enables debug output (SO_DEBUG).

Syntax

WinsockErrorCode SetOptionDebug(bool debug) noexcept;

Parameters

debugbool: true to enable debug output, false to disable it.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionDebug

Gets whether debug output is enabled (SO_DEBUG).

Syntax

WinsockErrorCode GetOptionDebug(bool* debug) noexcept;

Parameters

debugbool*: Required. Receives true if debug output is enabled.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionDontLinger

Sets whether close returns without lingering for unsent data (SO_DONTLINGER).

Syntax

WinsockErrorCode SetOptionDontLinger(bool dontLinger) noexcept;

Parameters

dontLingerbool: true: close does not wait for unsent data; false: the SO_LINGER setting applies.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionDontLinger

Gets the don't-linger setting (SO_DONTLINGER).

Syntax

WinsockErrorCode GetOptionDontLinger(bool* dontLinger) noexcept;

Parameters

dontLingerbool*: Required. Receives true if close does not linger for unsent data.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionDontRoute

Sets whether outgoing data bypasses routing (SO_DONTROUTE).

Syntax

WinsockErrorCode SetOptionDontRoute(bool dontRoute) noexcept;

Parameters

dontRoutebool: true to send directly to the interface without routing, false for normal routing.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionDontRoute

Gets the don't-route setting (SO_DONTROUTE).

Syntax

WinsockErrorCode GetOptionDontRoute(bool* dontRoute) noexcept;

Parameters

dontRoutebool*: Required. Receives true if outgoing data bypasses routing.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionError

Gets and clears the socket's pending error (SO_ERROR).

Syntax

WinsockErrorCode GetOptionError(DWORD* error) noexcept;

Parameters

errorDWORD*: Required. Receives the pending WSA error code, 0 if there is none.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionExclusiveAddressUse

Prevents other sockets from binding to the same address (SO_EXCLUSIVEADDRUSE).

Syntax

WinsockErrorCode SetOptionExclusiveAddressUse(bool exclusiveAddressUse) noexcept;

Parameters

exclusiveAddressUsebool: true for exclusive use of the address; set before Bind.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionExclusiveAddressUse

Gets the exclusive-address setting (SO_EXCLUSIVEADDRUSE).

Syntax

WinsockErrorCode GetOptionExclusiveAddressUse(bool* exclusiveAddressUse) noexcept;

Parameters

exclusiveAddressUsebool*: Required. Receives true if the address is used exclusively.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionGroupId

Gets the socket group id (SO_GROUP_ID).

Syntax

WinsockErrorCode GetOptionGroupId(unsigned int* groupId) noexcept;

Parameters

groupIdunsigned int*: Required. Receives the id of the group the socket belongs to (0 for none).

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionGroupPriority

Sets the priority within the socket group (SO_GROUP_PRIORITY).

Syntax

WinsockErrorCode SetOptionGroupPriority(int priority) noexcept;

Parameters

priorityint: The relative priority; 0 is the highest.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionGroupPriority

Gets the priority within the socket group (SO_GROUP_PRIORITY).

Syntax

WinsockErrorCode GetOptionGroupPriority(int* priority) noexcept;

Parameters

priorityint*: Required. Receives the relative priority; 0 is the highest.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionKeepAlive

Enables keep-alive packets (SO_KEEPALIVE).

Syntax

WinsockErrorCode SetOptionKeepAlive(bool keepAlive) noexcept;

Parameters

keepAlivebool: true to send keep-alive packets, false to stop them.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionKeepAlive

Gets whether keep-alive is enabled (SO_KEEPALIVE).

Syntax

WinsockErrorCode GetOptionKeepAlive(bool* keepAlive) noexcept;

Parameters

keepAlivebool*: Required. Receives true if keep-alive packets are sent.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionLinger

Sets the linger behaviour of close (SO_LINGER).

Syntax

WinsockErrorCode SetOptionLinger(const linger& l) noexcept;

Parameters

lconst linger&: l_onoff non-zero to linger on close; l_linger is the timeout in seconds (0 resets the connection on close).

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionLinger

Gets the linger behaviour of close (SO_LINGER).

Syntax

WinsockErrorCode GetOptionLinger(linger* l) noexcept;

Parameters

llinger*: Required. Receives the linger setting.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionMaxMessageSize

Gets the maximum message size of a message-oriented socket (SO_MAX_MSG_SIZE).

Syntax

WinsockErrorCode GetOptionMaxMessageSize(ULONG* size) noexcept;

Parameters

sizeULONG*: Required. Receives the maximum message size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionMaxDatagramSize

Gets the maximum datagram size (SO_MAXDG).

Syntax

WinsockErrorCode GetOptionMaxDatagramSize(ULONG* size) noexcept;

Parameters

sizeULONG*: Required. Receives the maximum datagram size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionMaxPathDatagramSize

Gets the maximum datagram size for a destination (SO_MAXPATHDG).

Syntax

WinsockErrorCode GetOptionMaxPathDatagramSize(ULONG* size) noexcept;

Parameters

sizeULONG*: Required. Receives the maximum datagram size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionOobInLine

Sets whether out-of-band data is received inline (SO_OOBINLINE).

Syntax

WinsockErrorCode SetOptionOobInLine(bool inLine) noexcept;

Parameters

inLinebool: true to receive out-of-band data in the normal data stream.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionOobInLine

Gets the out-of-band-inline setting (SO_OOBINLINE).

Syntax

WinsockErrorCode GetOptionOobInLine(bool* inLine) noexcept;

Parameters

inLinebool*: Required. Receives true if out-of-band data is received inline.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionOpenType

Sets the open type of sockets later created by this thread (SO_OPENTYPE).

Syntax

WinsockErrorCode SetOptionOpenType(DWORD type) noexcept;

Parameters

typeDWORD: 0 (overlapped) or SO_SYNCHRONOUS_ALERT / SO_SYNCHRONOUS_NONALERT.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionOpenType

Gets the open type (SO_OPENTYPE).

Syntax

WinsockErrorCode GetOptionOpenType(DWORD* type) noexcept;

Parameters

typeDWORD*: Required. Receives the open type (0, SO_SYNCHRONOUS_ALERT or SO_SYNCHRONOUS_NONALERT).

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionPortScalability

Enables local port scalability (SO_PORT_SCALABILITY).

Syntax

WinsockErrorCode SetOptionPortScalability(bool enable) noexcept;

Parameters

enablebool: true to enable port scalability, false to disable it.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionPortScalability

Gets the port scalability setting (SO_PORT_SCALABILITY).

Syntax

WinsockErrorCode GetOptionPortScalability(bool* enable) noexcept;

Parameters

enablebool*: Required. Receives true if port scalability is enabled.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionProtocolInfo

Gets the protocol information (ANSI) (SO_PROTOCOL_INFOA).

Syntax

WinsockErrorCode GetOptionProtocolInfo(WSAPROTOCOL_INFOA* protocolInfo) noexcept;

Parameters

protocolInfoWSAPROTOCOL_INFOA*: Required. Receives the protocol information of the socket's provider.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

Gets the protocol information (Unicode) (SO_PROTOCOL_INFOW).

Syntax

WinsockErrorCode GetOptionProtocolInfo(WSAPROTOCOL_INFOW* protocolInfo) noexcept;

Parameters

protocolInfoWSAPROTOCOL_INFOW*: Required. Receives the protocol information of the socket's provider.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionReceiveBufferSize

Sets the receive buffer size (SO_RCVBUF).

Syntax

WinsockErrorCode SetOptionReceiveBufferSize(DWORD size) noexcept;

Parameters

sizeDWORD: The buffer size in bytes; 0 disables the provider's receive buffering.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionReceiveBufferSize

Gets the receive buffer size (SO_RCVBUF).

Syntax

WinsockErrorCode GetOptionReceiveBufferSize(DWORD* size) noexcept;

Parameters

sizeDWORD*: Required. Receives the buffer size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionReceiveTimeout

Sets the receive timeout in milliseconds (SO_RCVTIMEO).

Syntax

WinsockErrorCode SetOptionReceiveTimeout(DWORD timeout) noexcept;

Parameters

timeoutDWORD: The timeout in milliseconds; 0 waits without limit.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

Remarks

Applies to blocking calls only; overlapped operations ignore it - use the timeout of AsyncIo::AsyncSocket's waiting forms.

GetOptionReceiveTimeout

Gets the receive timeout in milliseconds (SO_RCVTIMEO).

Syntax

WinsockErrorCode GetOptionReceiveTimeout(DWORD* timeout) noexcept;

Parameters

timeoutDWORD*: Required. Receives the timeout in milliseconds; 0 means no limit.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionReuseAddress

Allows binding to an address in use (SO_REUSEADDR).

Syntax

WinsockErrorCode SetOptionReuseAddress(bool reuseAddress) noexcept;

Parameters

reuseAddressbool: true to allow binding to an address already in use; set before Bind.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionReuseAddress

Gets the reuse-address setting (SO_REUSEADDR).

Syntax

WinsockErrorCode GetOptionReuseAddress(bool* reuseAddress) noexcept;

Parameters

reuseAddressbool*: Required. Receives true if binding to an address in use is allowed.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionSendBufferSize

Sets the send buffer size (SO_SNDBUF).

Syntax

WinsockErrorCode SetOptionSendBufferSize(DWORD size) noexcept;

Parameters

sizeDWORD: The buffer size in bytes; 0 disables the provider's send buffering.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionSendBufferSize

Gets the send buffer size (SO_SNDBUF).

Syntax

WinsockErrorCode GetOptionSendBufferSize(DWORD* size) noexcept;

Parameters

sizeDWORD*: Required. Receives the buffer size in bytes.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionSendTimeout

Sets the send timeout in milliseconds (SO_SNDTIMEO).

Syntax

WinsockErrorCode SetOptionSendTimeout(DWORD timeout) noexcept;

Parameters

timeoutDWORD: The timeout in milliseconds; 0 waits without limit.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

Remarks

Applies to blocking calls only; overlapped operations ignore it.

GetOptionSendTimeout

Gets the send timeout in milliseconds (SO_SNDTIMEO).

Syntax

WinsockErrorCode GetOptionSendTimeout(DWORD* timeout) noexcept;

Parameters

timeoutDWORD*: Required. Receives the timeout in milliseconds; 0 means no limit.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOptionType

Gets the socket type (SOCK_STREAM, SOCK_DGRAM, ...) (SO_TYPE).

Syntax

WinsockErrorCode GetOptionType(DWORD* socketType) noexcept;

Parameters

socketTypeDWORD*: Required. Receives the socket type.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

SetOptionUpdateAcceptContext

Sets SO_UPDATE_ACCEPT_CONTEXT on an accepted socket.

Syntax

WinsockErrorCode SetOptionUpdateAcceptContext(const Socket& listenSocket) noexcept;

Parameters

listenSocketconst Socket&: The listening socket the AcceptEx ran on.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

Remarks

Call on the accepted socket after AcceptAsync has completed; getpeername, shutdown etc. work on it only after that. AsyncIo::AsyncTcpSocket::Accept does it.

See also

SetOptionUpdateConnectContext

SetOptionUpdateConnectContext

Sets SO_UPDATE_CONNECT_CONTEXT on a socket connected by ConnectEx.

Syntax

WinsockErrorCode SetOptionUpdateConnectContext() noexcept;

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

Remarks

Call after ConnectAsync has completed; getpeername, shutdown etc. work on the socket only after that. AsyncIo::AsyncTcpSocket::Connect does it.

See also

SetOptionUpdateAcceptContext

SetOptionUseLoopback

Sets whether the loopback is used (SO_USELOOPBACK).

Syntax

WinsockErrorCode SetOptionUseLoopback(bool useLoopback) noexcept;

Parameters

useLoopbackbool: true to use the loopback where possible, false otherwise.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of setsockopt.

GetOptionUseLoopback

Gets the use-loopback setting (SO_USELOOPBACK).

Syntax

WinsockErrorCode GetOptionUseLoopback(bool* useLoopback) noexcept;

Parameters

useLoopbackbool*: Required. Receives true if the loopback is used.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of getsockopt.

GetOverlappedResult

Gets the result of an overlapped operation (WSAGetOverlappedResult).

Syntax

WinsockErrorCode GetOverlappedResult(
    OVERLAPPED& overlapped,
    DWORD* bytesTransferred,
    BOOL wait,
    DWORD* flags
) const noexcept;

Parameters

overlappedOVERLAPPED&: The OVERLAPPED the operation was started with.
bytesTransferredDWORD*: Required. Receives the bytes transferred.
waitBOOL: TRUE blocks the calling thread until the operation has completed; FALSE returns WSA_IO_INCOMPLETE while pending.
flagsDWORD*: Receives the operation's result flags.

Return value

Type: WinsockErrorCode

WinsockError::Success, WinsockError::Incomplete (still pending, wait FALSE) or the operation's error.

IoctlAsync

Starts an overlapped WSAIoctl (raw OVERLAPPED form).

Syntax

WinsockErrorCode IoctlAsync(
    DWORD ioControlCode,
    void* inBuffer,
    DWORD inBufferSize,
    void* outBuffer,
    DWORD outBufferSize,
    DWORD* bytesReturned,
    OVERLAPPED& overlapped
) noexcept;

Parameters

ioControlCodeDWORD: The control code, e.g. a SIO_* constant.
inBuffervoid*: The input data of the control code; nullptr if it takes none.
inBufferSizeDWORD: The size of inBuffer in bytes.
outBuffervoid*: Receives the output data; nullptr if the control code returns none. Must stay valid until completion.
outBufferSizeDWORD: The size of outBuffer in bytes.
bytesReturnedDWORD*: Required. Receives the output byte count on synchronous completion.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending or the WSA error.

See also

Ioctl

Performs a WSAIoctl synchronously.

Syntax

WinsockErrorCode Ioctl(
    DWORD ioControlCode,
    void* inBuffer,
    DWORD inBufferSize,
    void* outBuffer,
    DWORD outBufferSize,
    DWORD* bytesReturned
) noexcept;

Parameters

ioControlCodeDWORD: The control code, e.g. a SIO_* constant.
inBuffervoid*: The input data of the control code; nullptr if it takes none.
inBufferSizeDWORD: The size of inBuffer in bytes.
outBuffervoid*: Receives the output data; nullptr if the control code returns none.
outBufferSizeDWORD: The size of outBuffer in bytes.
bytesReturnedDWORD*: Required. Receives the number of bytes written to outBuffer.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of WSAIoctl.

See also

IoctlGetExtensionFunctionPointer

Loads a Winsock extension function pointer (SIO_GET_EXTENSION_FUNCTION_POINTER).

Syntax

template <class T>
WinsockErrorCode IoctlGetExtensionFunctionPointer(
    GUID& functionGuid,
    T& functionPointer
) noexcept;

Template parameters

Tclass: The function pointer type, e.g. LPFN_ACCEPTEX.

Parameters

functionGuidGUID&: The extension function's GUID, e.g. WSAID_ACCEPTEX.
functionPointerT&: Receives the function pointer.

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of WSAIoctl.

Listen

Puts the bound socket into listening state (listen).

Syntax

WinsockErrorCode Listen(int backlog = SOMAXCONN) noexcept;

Parameters

backlogint: The maximum length of the queue of pending connections; SOMAXCONN lets the provider choose.Default: SOMAXCONN

Return value

Type: WinsockErrorCode

WinsockError::Success, or the WSA error of listen.

See also

CancelAllAsyncRequests

Requests cancellation of all overlapped operations on this socket (CancelIoEx).

Syntax

WinsockErrorCode CancelAllAsyncRequests() noexcept;

Return value

Type: WinsockErrorCode

WinsockError::Success if cancellation was requested, ERROR_NOT_FOUND if no operation was pending, or another error.

Remarks

Covers operations issued by any thread. Does not wait: each cancelled operation still completes (normally with WinsockError::OperationAborted); keep its OVERLAPPED/request and buffers alive until then.

See also

RecvAsync

Starts a WSARecv (raw OVERLAPPED form).

Syntax

WinsockErrorCode RecvAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    DWORD* flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
flagsDWORD*: Required. In: MSG_* flags for the call; the result flags come from GetOverlappedResult.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecv without flags (raw OVERLAPPED form).

Syntax

WinsockErrorCode RecvAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecv into one buffer (raw OVERLAPPED form).

Syntax

WinsockErrorCode RecvAsync(
    void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    DWORD* flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffervoid*: Receives the data; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
flagsDWORD*: Required. In: MSG_* flags for the call; the result flags come from GetOverlappedResult.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecv into one buffer without flags (raw OVERLAPPED form).

Syntax

WinsockErrorCode RecvAsync(
    void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffervoid*: Receives the data; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

RecvFromAsync

Starts a WSARecvFrom without the sender's address (raw OVERLAPPED form).

Syntax

WinsockErrorCode RecvFromAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    DWORD* flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
flagsDWORD*: Required. In: MSG_* flags for the call; the result flags come from GetOverlappedResult.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecvFrom without flags or sender address.

Syntax

WinsockErrorCode RecvFromAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecvFrom into one buffer without the sender's address.

Syntax

WinsockErrorCode RecvFromAsync(
    void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    DWORD* flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffervoid*: Receives the data; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
flagsDWORD*: Required. In: MSG_* flags for the call; the result flags come from GetOverlappedResult.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecvFrom into one buffer without flags or sender address.

Syntax

WinsockErrorCode RecvFromAsync(
    void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffervoid*: Receives the data; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecvFrom with the sender's address (raw OVERLAPPED form).

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode RecvFromAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    DWORD* flags,
    _SockAddr& addr,
    int& addrLength,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the buffer length.

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
flagsDWORD*: Required. In: MSG_* flags for the call; the result flags come from GetOverlappedResult.
addr_SockAddr&: Receives the sender's address on completion; must stay valid until then.
addrLengthint&: Receives the size of the sender's address on completion; must stay valid until then.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecvFrom without flags, with the sender's address.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode RecvFromAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    _SockAddr& addr,
    int& addrLength,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the buffer length.

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
addr_SockAddr&: Receives the sender's address on completion; must stay valid until then.
addrLengthint&: Receives the size of the sender's address on completion; must stay valid until then.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecvFrom into one buffer, with the sender's address.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode RecvFromAsync(
    void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    DWORD* flags,
    _SockAddr& addr,
    int& addrLength,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the buffer length.

Parameters

buffervoid*: Receives the data; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
flagsDWORD*: Required. In: MSG_* flags for the call; the result flags come from GetOverlappedResult.
addr_SockAddr&: Receives the sender's address on completion; must stay valid until then.
addrLengthint&: Receives the size of the sender's address on completion; must stay valid until then.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSARecvFrom into one buffer without flags, with the sender's address.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode RecvFromAsync(
    void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    _SockAddr& addr,
    int& addrLength,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the buffer length.

Parameters

buffervoid*: Receives the data; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes received on synchronous completion; may be nullptr.
addr_SockAddr&: Receives the sender's address on completion; must stay valid until then.
addrLengthint&: Receives the size of the sender's address on completion; must stay valid until then.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

SendAsync

Starts a WSASend (raw OVERLAPPED form).

Syntax

WinsockErrorCode SendAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    DWORD flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
flagsDWORD: MSG_* flags for WSASend.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASend without flags.

Syntax

WinsockErrorCode SendAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASend of one buffer.

Syntax

WinsockErrorCode SendAsync(
    const void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    DWORD flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

bufferconst void*: The data to send; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
flagsDWORD: MSG_* flags for WSASend.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASend of one buffer without flags.

Syntax

WinsockErrorCode SendAsync(
    const void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

bufferconst void*: The data to send; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

SendToAsync

Starts a WSASendTo without address (raw OVERLAPPED form).

Syntax

WinsockErrorCode SendToAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    DWORD flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
flagsDWORD: MSG_* flags for WSASendTo.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Remarks

Sends to the connected/default peer.

Starts a WSASendTo without address or flags.

Syntax

WinsockErrorCode SendToAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASendTo of one buffer without address.

Syntax

WinsockErrorCode SendToAsync(
    const void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    DWORD flags,
    OVERLAPPED& overlapped
) noexcept;

Parameters

bufferconst void*: The data to send; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
flagsDWORD: MSG_* flags for WSASendTo.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASendTo of one buffer without address or flags.

Syntax

WinsockErrorCode SendToAsync(
    const void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

bufferconst void*: The data to send; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASendTo to an address (raw OVERLAPPED form).

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode SendToAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    DWORD flags,
    const _SockAddr& addr,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
flagsDWORD: MSG_* flags for WSASendTo.
addrconst _SockAddr&: The destination address.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASendTo to an address without flags.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode SendToAsync(
    WSABUF* buffers,
    DWORD bufferCount,
    DWORD* bytesTransferred,
    const _SockAddr& addr,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

buffersWSABUF*: Required. The WSABUF array may be temporary; the memory it describes must stay valid until completion.
bufferCountDWORD: The number of entries in buffers.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
addrconst _SockAddr&: The destination address.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASendTo of one buffer to an address.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode SendToAsync(
    const void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    DWORD flags,
    const _SockAddr& addr,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

bufferconst void*: The data to send; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
flagsDWORD: MSG_* flags for WSASendTo.
addrconst _SockAddr&: The destination address.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Starts a WSASendTo of one buffer to an address without flags.

Syntax

template <SockAddrType _SockAddr>
WinsockErrorCode SendToAsync(
    const void* buffer,
    std::uint32_t bufferSize,
    DWORD* bytesTransferred,
    const _SockAddr& addr,
    OVERLAPPED& overlapped
) noexcept;

Template parameters

_SockAddrSockAddrType: The address structure type; its size is passed as the address length.

Parameters

bufferconst void*: The data to send; must stay valid until completion.
bufferSizestd::uint32_t: The size of buffer in bytes.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
addrconst _SockAddr&: The destination address.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

RecvMsgAsync

Starts a WSARecvMsg (raw OVERLAPPED form).

Syntax

WinsockErrorCode RecvMsgAsync(
    WSAMSG* msg,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

msgWSAMSG*: Written at completion; must stay valid until then.
bytesTransferredDWORD*: Required. Receives the bytes received on synchronous completion.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

SendMsgAsync

Starts a WSASendMsg (raw OVERLAPPED form).

Syntax

WinsockErrorCode SendMsgAsync(
    WSAMSG* msg,
    DWORD flags,
    DWORD* bytesTransferred,
    OVERLAPPED& overlapped
) noexcept;

Parameters

msgWSAMSG*: It and its data must stay valid until completion.
flagsDWORD: MSG_* flags for WSASendMsg.
bytesTransferredDWORD*: Receives the bytes sent on synchronous completion; may be nullptr.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

TransmitFileAsync

Starts a TransmitFile (raw OVERLAPPED form).

Syntax

WinsockErrorCode TransmitFileAsync(
    HANDLE file,
    DWORD bytesToWrite,
    DWORD bytesPerSend,
    TRANSMIT_FILE_BUFFERS* transmitBuffers,
    OVERLAPPED& overlapped,
    DWORD flags = 0
) noexcept;

Parameters

fileHANDLE: The open file to send; must stay open until completion. nullptr sends only transmitBuffers.
bytesToWriteDWORD: Bytes of the file to send; 0 sends the whole file from the offset in overlapped.
bytesPerSendDWORD: Size of each send; 0 lets the system choose.
transmitBuffersTRANSMIT_FILE_BUFFERS*: Optional head/tail data; must stay valid until completion.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; its Offset/OffsetHigh give the file position to start at. Must stay valid and must not be reused until the operation has completed.
flagsDWORD: TF_* flags, e.g. TF_DISCONNECT | TF_REUSE_SOCKET.Default: 0

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Remarks

See also AsyncIo::AsyncSocket::TransmitFileAsync.

TransmitPacketsAsync

Starts a TransmitPackets (raw OVERLAPPED form).

Syntax

WinsockErrorCode TransmitPacketsAsync(
    TRANSMIT_PACKETS_ELEMENT* packetArray,
    DWORD elementCount,
    DWORD transmitSize,
    OVERLAPPED& overlapped,
    DWORD flags = 0
) noexcept;

Parameters

packetArrayTRANSMIT_PACKETS_ELEMENT*: The elements (memory and/or file ranges); they and everything they reference must stay valid until completion.
elementCountDWORD: The number of entries in packetArray.
transmitSizeDWORD: Bytes per send; 0 lets the system choose.
overlappedOVERLAPPED&: The caller's OVERLAPPED for this operation; must stay valid and must not be reused until the operation has completed.
flagsDWORD: TF_* flags.Default: 0

Return value

Type: WinsockErrorCode

WinsockError::Success (completed synchronously), WinsockError::Pending (in flight) or the WSA error.

Remarks

See also AsyncIo::AsyncSocket::TransmitPacketsAsync.

GetSocketprotected

The raw SOCKET; stays owned by this object.

Syntax

SOCKET GetSocket() const noexcept;

Return value

Type: SOCKET

The socket handle, or INVALID_SOCKET if the object holds none.

Fields

AcceptExprotected

Syntax

inline static LPFN_ACCEPTEX AcceptEx = nullptr;

ConnectExprotected

Syntax

inline static LPFN_CONNECTEX ConnectEx = nullptr;

DisconnectExprotected

Syntax

inline static LPFN_DISCONNECTEX DisconnectEx = nullptr;

GetAcceptExSockaddrsprotected

Syntax

inline static LPFN_GETACCEPTEXSOCKADDRS GetAcceptExSockaddrs = nullptr;

TransmitFileprotected

Syntax

inline static LPFN_TRANSMITFILE TransmitFile = nullptr;

TransmitPacketsprotected

Syntax

inline static LPFN_TRANSMITPACKETS TransmitPackets = nullptr;

WSARecvMsgprotected

Syntax

inline static LPFN_WSARECVMSG WSARecvMsg = nullptr;

WSASendMsgprotected

Syntax

inline static LPFN_WSASENDMSG WSASendMsg = nullptr;

Generated from ThinkMeta.ConcurrentTasks.API @ 137ec1d (2026-10-17).