Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function initiates use of ws2.dll by a process.

Syntax 

int WSAStartup(
  WORD 
wVersionRequested,
  LPWSADATA 
lpWSAData
);

Parameters

wVersionRequested

[in] Highest version of Windows Sockets support that the caller can use. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

You can also specify WINSOCK_VERSION as the value of this parameter. WINSOCK_VERSION is a macro that is defined in winsock2.h.

lpWSAData

[out] Pointer to the WSADATAstructure that is to receive details of the Windows Sockets implementation.

Return Value

If no error occurs, this function returns zero. If an error occurs, it returns one of the error codes listed in the following table.

An application cannot call WSAGetLastErrorto determine the error code as is typically done in Windows Sockets if WSAStartupfails. ws2.dll will not have been loaded in the case of a failure so the client data area where the last error information is stored could not be established.

The following table shows a list of possible error codes.

Error code Description

WSASYSNOTREADY

Indicates that the underlying network subsystem is not ready for network communication.

WSAVERNOTSUPPORTED

The version of Windows Sockets support requested is not provided by this particular Windows Sockets implementation.

WSAEPROCLIM

A limit on the number of tasks supported by the Windows Sockets implementation has been reached.

WSAEFAULT

The lpWSADataparameter is not a valid pointer.

Remarks

This function must be the first Windows Sockets function called by an application or DLL. It allows an application or DLL to specify the version of Windows Sockets required and retrieve details of the specific Windows Sockets implementation. The application or DLL can only issue further Windows Sockets functions after successfully calling WSAStartup.

To support future Windows Sockets implementations and applications that can have functionality differences from the current version of Windows Sockets, a negotiation takes place in WSAStartup. The caller of WSAStartupand ws2.dll indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. On entry to WSAStartup, ws2.dll examines the version requested by the application. If this version is equal to or higher than the lowest version supported by the DLL, the call succeeds and the DLL returns in wHighVersionthe highest version it supports and in wVersionthe minimum of its high version and wVersionRequested. ws2.dll then assumes that the application will use wVersion. If the wVersionparameter of the WSADATAstructure is unacceptable to the caller, it should call WSACleanupand either search for another ws2.dll or fail to initialize.

It is legal and possible for an application written to this version of the specification to successfully negotiate a higher version number version. In that case, the application is only guaranteed access to higher version functionality that fits within the syntax defined in this version, such as new Ioctlcodes and new behavior of existing functions. New functions may be inaccessible. To get full access to the new syntax of a future version, the application must fully conform to that future version, such as compiling against a new header file, linking to a new library, or other special cases.

This negotiation allows both ws2.dll and a Windows Sockets application to support a range of Windows Sockets versions. An application can use ws2.dll if there is any overlap in the version ranges. The following table shows how WSAStartupworks with different applications and ws2.dll versions.

Application version DLL version wVersionrequested wVersion wHighversion Result

1.1

1.1

1.1

1.1

1.1

use 1.1

1.0 1.1

1.0

1.1

1.0

1.0

use 1.0

1.0

1.0 1.1

1.0

1.0

1.1

use 1.0

1.1

1.0 1.1

1.1

1.1

1.1

use 1.1

1.1

1.0

1.1

1.0

1.0

Application fails

1.0

1.1

1.0

---

---

WSAVERNOT SUPPORTED

1.0 1.1

1.0 1.1

1.1

1.1

1.1

use 1.1

1.1 2.2

1.1

2.2

1.1

1.1

use 1.1

2.2

2.2

2.2

2.2

2.2

use 2.2

Example

The following code sample demonstrates how an application that supports only Winsock 2.2 makes a WSAStartupcall.
Copy Code 
WORD wVersionRequested;
WSADATA wsaData;
int err;
 
wVersionRequested = MAKEWORD( 2, 2 );
 
err = WSAStartup( wVersionRequested, &wsaData );
if ( err != 0 ) {
	/* Tell the user that we could not find a usable */
	/* WinSock DLL.								*/
	return;
}
 
/* Confirm that the WinSock DLL supports 2.2.*/
/* Note that if the DLL supports versions later	*/
/* than 2.2 in addition to 2.2, it will still return */
/* 2.2 in wVersion since that is the version we	*/
/* requested.										*/
 
if ( LOBYTE( wsaData.wVersion ) != 2 ||
		HIBYTE( wsaData.wVersion ) != 2 ) {
	/* Tell the user that we could not find a usable */
	/* WinSock DLL.								*/
	WSACleanup( );
	return; 
}
 
/* The WinSock DLL is acceptable. Proceed. */

Once an application or DLL has made a successful WSAStartupcall, it can proceed to make other Windows Sockets calls as needed. When it has finished using the services of ws2.dll, the application or DLL must call WSACleanupto allow ws2.dll to free any resources for the application.

Details of the actual Windows Sockets implementation are described in the WSADATAstructure.

An application or DLL can call WSAStartupmore than once if it needs to obtain the WSADATAstructure information more than once. On each such call the application can specify any version number supported by the DLL.

An application must make one WSACleanupcall for every successful WSAStartupcall to allow third-party DLLs to make use of ws2.dll on behalf of an application. This means, for example, that if an application calls WSAStartupthree times, it must call WSACleanupthree times. The first two calls to WSACleanupdo nothing except decrement an internal counter; the final WSACleanupcall for the task does all necessary resource de-allocation for the task.

Requirements

Header winsock2.h
Library Ws2.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also