Winsock 2 Extension Functions

This section describes the Winsock 2 extension functions, which provide advanced networking capabilities beyond the standard Winsock 2 API. These functions are crucial for building robust and high-performance network applications on Windows.

Winsock 2 extension functions allow for finer control over network protocols, enhanced error handling, and access to provider-specific features. They are typically used for tasks such as:

• Managing Quality of Service (QoS) parameters.
• Performing complex socket I/O operations.
• Interacting with specific transport protocols.
• Advanced network diagnostics and configuration.

Key Extension Functions

WSAProtocol_InfoA / WSAProtocol_InfoW

The WSAProtocol_InfoA and WSAProtocol_InfoW structures contain information about a protocol, including its name, address family, socket type, and protocol information.

int WSAAPI WSAProtocol_InfoA( __in LPSTR lpProtocolBuffer, __in LPDWORD lpdwBufferLength );

int WSAAPI WSAProtocol_InfoW( __in LPWSTR lpProtocolBuffer, __in LPDWORD lpdwBufferLength );

Parameters:

• lpProtocolBuffer: A pointer to a buffer that will receive the protocol information.
• lpdwBufferLength: A pointer to a DWORD that specifies the size of the buffer, in bytes.

Return Value: If no error occurs, WSAProtocol_InfoA or WSAProtocol_InfoW returns 0. Otherwise, an appropriate error code is returned.

WSASocketA / WSASocketW

The WSASocketA and WSASocketW functions create a socket that can be used for asynchronous operation. This is a more flexible way to create sockets compared to the standard socket function, as it allows for explicit control over socket attributes and can be associated with I/O completion ports.

SOCKET WSAAPI WSASocketA( int af, int type, int protocol, LPWSAPROTOCOL_INFOA lpProtocolInfo, GROUP g, DWORD dwFlags );

SOCKET WSAAPI WSASocketW( int af, int type, int protocol, LPWSAPROTOCOL_INFOW lpProtocolInfo, GROUP g, DWORD dwFlags );

Parameters:

• af: The address family (e.g., AF_INET for IPv4).
• type: The socket type (e.g., SOCK_STREAM for TCP, SOCK_DGRAM for UDP).
• protocol: The protocol to be used (e.g., IPPROTO_TCP, IPPROTO_UDP). If set to 0, the provider selects the appropriate protocol for the specified type.
• lpProtocolInfo: An optional pointer to a WSAPROTOCOL_INFO structure that specifies the characteristics of the socket to be created.
• g: Reserved. Must be zero.
• dwFlags: Flags that modify the behavior of the socket creation. Common flags include WSA_FLAG_OVERLAPPED for overlapped I/O.

Return Value: If no error occurs, WSASocketA or WSASocketW returns a descriptor for the newly created socket. Otherwise, it returns INVALID_SOCKET and a specific error code can be retrieved by calling WSAGetLastError.

Example Usage:

#include <winsock2.h>
#pragma comment(lib, "ws2_32.lib")

// ...

SOCKET sock = INVALID_SOCKET;
WSADATA wsaData;

if (WSAStartup(MAKEWORD(2, 2), &wsaData) != 0) {
    // Handle error
    return 1;
}

sock = WSASocketW(AF_INET, SOCK_STREAM, IPPROTO_TCP, NULL, 0, WSA_FLAG_OVERLAPPED);

if (sock == INVALID_SOCKET) {
    // Handle error
    WSACleanup();
    return 1;
}

// Use the socket for asynchronous operations
// ...

closesocket(sock);
WSACleanup();
            

WSAIoctl

The WSAIoctl function provides a mechanism to control the behavior of a socket and retrieve information about it. It supports a wide range of operations (commands) that are specific to the underlying protocol or the Winsock implementation.

int WSAAPI WSAIoctl( SOCKET s, DWORD dwIoControlCode, LPVOID lpvInBuffer, DWORD cbInBufferSize, LPVOID lpvOutBuffer, DWORD cbOutBufferSize, LPDWORD lpdwBytesReturned, LPWSAOVERLAPPED lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine );

Parameters:

• s: The descriptor of the socket on which the I/O operation is to be performed.
• dwIoControlCode: The specific I/O control code that specifies the operation to be performed.
• lpvInBuffer: A pointer to the buffer containing input data for the operation.
• cbInBufferSize: The size, in bytes, of the input buffer.
• lpvOutBuffer: A pointer to the buffer that receives output data from the operation.
• cbOutBufferSize: The size, in bytes, of the output buffer.
• lpdwBytesReturned: A pointer to a DWORD that receives the size, in bytes, of the data actually written to the output buffer.
• lpOverlapped: A pointer to a WSAOVERLAPPED structure or NULL if the operation is to be performed synchronously.
• lpCompletionRoutine: A pointer to a completion routine to be called when the operation completes.

Return Value: If the operation is performed successfully, WSAIoctl returns 0. If the operation is performed synchronously and fails, the return value is SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError. If the operation is performed asynchronously, the return value is 0 and the operation's status is conveyed via lpOverlapped and possibly lpCompletionRoutine.

WSAEnumProtocolsA / WSAEnumProtocolsW

These functions enumerate Winsock catalog entries that specify Transport Protocol Services. This allows applications to discover available protocols and their characteristics.

int WSAAPI WSAEnumProtocolsA( __in_opt LPINT lpiProtocols, __out_ecount_ecount_opt(*lpdwBufferLength) LPPROTOCOLSPEC_LENA lpProtocolBuffer, __inout LPDWORD lpdwBufferLength );

int WSAAPI WSAEnumProtocolsW( __in_opt LPINT lpiProtocols, __out_ecount_ecount_opt(*lpdwBufferLength) LPPROTOCOLSPEC_LENW lpProtocolBuffer, __inout LPDWORD lpdwBufferLength );

WSAGetQOSByName

Retrieves QoS parameters associated with a given service class. This function is crucial for applications that need to negotiate and utilize quality of service for network traffic.

int WSAAPI WSAGetQOSByName( SOCKET s, LPWSABUF lpQOSName, LPQOS lpQOS );

WSAConnectByList

Connects a socket to a service on a specified host, attempting to connect through a list of network services. This provides a way to handle service discovery and connection establishment in a more flexible manner.

int WSAAPI WSAConnectByList( SOCKET s, LPSERVICE_ADDRESS_LIST ServiceAddressList, LPINT lpErrno );

WSAGetPeerName

Retrieves the name of the remote station to which a socket is connected. This is equivalent to the standard getpeername but is part of the Winsock API.

int WSAAPI WSAGetPeerName( SOCKET s, __out_bcount(*lpNameLength) struct sockaddr *name, __inout LPINT lpNameLength );

WSAGetSockName

Retrieves the current name of the bound socket. Similar to getsockname.

int WSAAPI WSAGetSockName( SOCKET s, __out_bcount(*lpNameLength) struct sockaddr *name, __inout LPINT lpNameLength );

WSAStartup

Initializes the Winsock DLL. Every application or DLL that uses Winsock must call WSAStartup before calling any other Winsock functions.

int WSAAPI WSAStartup( WORD wVersionRequired, LPWSADATA lpWSAData );

WSACleanup

Closes all sockets for the calling process and unloads the Winsock DLL. Applications must call WSACleanup for every successful call to WSAStartup.

void WSAAPI WSACleanup( void );