MSDN Documentation / Windows / Networking / Winsock / WsaStartup

WSAStartup Function

Initializes the Windows Sockets API.

Syntax


int WSAStartup(
  WORD                  wVersionRequested,
  LPWSADATA             lpWSAData
);

Parameters

Parameter Description
wVersionRequested The version of the Windows Sockets API that the calling application requires. This parameter is the high-order byte specifying the minor version number and the low-order byte specifying the major version number.

For example, to request version 2.2, set this parameter to MAKEWORD(2, 2).
lpWSAData A pointer to the WSADATA structure that receives details about the Windows Sockets implementation.

Return Value

Value Description
0 The function was successful.
WSASOCKET_ERROR An operating system error occurred. To get extended error information, call WSAGetLastError.

Possible extended error codes are:

  • WSAEINPROGRESS: A blocking Winsock 1.1 call is in progress, or the service provider is still processing a callback function.
  • WSAENETDOWN: The network subsystem has failed.
  • WSAEINVAL: The version number requested in wVersionRequested is not supported by the Winsock DLL.
  • WSAENOTSOCK: A Windows Sockets implementation is not found, or the given handle is not a socket.

Remarks

The WSAStartup function must be the first Winsock function called by any application or DLL that uses the Windows Sockets API. It is used to initialize the Winsock DLL and specify the version of the Winsock API that the application will use.

The application requests a specific version of the Winsock API by setting the wVersionRequested parameter. The Winsock DLL then checks if it can support a version that is at least as high as the requested version. If the DLL can support the requested version, it returns success and fills the supplied WSADATA structure with information about the Winsock implementation.

  • The calling application can use any Winsock version number from 1.1 up to the highest version supported by the Winsock DLL.
  • The wVersionRequested parameter is constructed using the MAKEWORD macro. For example, MAKEWORD(2, 2) requests Winsock version 2.2.
  • An application can check the Winsock version implemented by the DLL by examining the wVersion member of the WSADATA structure after a successful call to WSAStartup.
  • If the requested version is not supported, the application should call WSACleanup and then exit.
  • Multiple applications can call WSAStartup. The Winsock DLL keeps track of the number of applications that have called it. Each call to WSAStartup must be matched by a corresponding call to WSACleanup. The DLL is not unloaded until the reference count reaches zero.
  • For applications that need to support older Winsock versions, Winsock 2 provides backward compatibility. An application requesting version 1.1 will be satisfied if the Winsock DLL supports version 2.0 or higher.

See Also

WSACleanup Cleans up the Winsock DLL.
WSADATA Structure containing Winsock implementation details.
Winsock Functions Reference to all available Winsock functions.