Winsock WSAData Structure - Windows API Reference

WSAData Structure

The WSAData structure is used by the Winsock DLL to return information to an application about the Windows Sockets implementation. An application calls the WSAStartup function to initialize the Winsock DLL. The WSAStartup function takes a pointer to a WSAData structure as an argument. The Winsock DLL copies the current Winsock implementation's version number and other details into this structure.

Structure Definition

The WSAData structure is defined as follows:

typedef struct _WSAData {
    WORD                 wVersion;
    WORD                 wHighVersion;
    char                 szDescription[WSADESCRIPTION_LEN + 1];
    char                 szSystemStatus[WSASYS_STATUS_LEN + 1];
    unsigned short       iMaxSockets;
    unsigned short       iMaxUdpHeap;
    LPWSTR               lpVendorInfo;
} WSAData, FAR * LPWSAData;

Members

Member	Description
wVersion	The version of the Winsock protocol specification that the DLL supports. This is a bitmask where the low-order byte contains the minor version number, and the high-order byte contains the major version number.
wHighVersion	The highest version of the Winsock protocol specification that the DLL supports. This is also a bitmask similar to `wVersion`. Typically, for Winsock 1.1, this will be the same as `wVersion`. For Winsock 2 and later, this can indicate a higher version than requested.
szDescription	A NULL-terminated character string that contains the supplier's description of the networking services. The maximum length is `WSADESCRIPTION_LEN` (256) characters.
szSystemStatus	A NULL-terminated character string that contains information about the Winsock implementation's status. The maximum length is `WSASYS_STATUS_LEN` (128) characters.
iMaxSockets	The maximum number of sockets that can be opened at one time.
iMaxUdpHeap	The maximum amount of memory, in bytes, that can be allocated for use by UDP receive data. A value of `0xFFFF` indicates that this parameter is not used.
lpVendorInfo	A pointer to a vendor-specific structure that contains additional information about the supplied Winsock services. This member can be `NULL`.

Important Notes

The wVersion and wHighVersion members are used to determine compatibility between the requested Winsock version and the DLL's capabilities.
The szDescription and szSystemStatus members provide diagnostic and descriptive information about the Winsock implementation.
iMaxSockets indicates the practical limit on concurrent socket usage.
The constants WSADESCRIPTION_LEN (256) and WSASYS_STATUS_LEN (128) define the maximum buffer sizes for the description and system status strings, respectively.

Example Usage

Here's a basic example of how to initialize Winsock and retrieve information into a WSAData structure:

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iostream>

// Link with Ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main() {
    WSADATA wsaData;
    int iResult;

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        std::cerr << "WSAStartup failed: " << iResult << std::endl;
        return 1;
    }

    std::cout << "Winsock initialized successfully." << std::endl;
    std::cout << "Winsock Version: " << (wsaData.wVersion >> 8) << "." << (wsaData.wVersion & 0xFF) << std::endl;
    std::cout << "Highest Supported Version: " << (wsaData.wHighVersion >> 8) << "." << (wsaData.wHighVersion & 0xFF) << std::endl;
    std::cout << "Description: " << wsaData.szDescription << std::endl;
    std::cout << "System Status: " << wsaData.szSystemStatus << std::endl;
    std::cout << "Max Sockets: " << wsaData.iMaxSockets << std::endl;
    std::cout << "Max UDP Heap: " << wsaData.iMaxUdpHeap << std::endl;

    // Clean up Winsock
    WSACleanup();

    return 0;
}

For more information, refer to the official Microsoft documentation.