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. |
This function initializes a WSADATAstructure.
int WSAStartup( WORD wVersionRequested, LPWSADATA lpWSAData );
Parameters
Return Values
Zero indicates success. To get a specific error value, call WSAGetLastError. The following table shows possible error values.
Value | Description |
---|---|
WSASYSNOTREADY | 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. |
WSAEINPROGRESS | A blocking Windows Sockets 1.1 operation is in progress. |
WSAEPROCLIM | The limit on the number of tasks supported by the Windows Sockets implementation has been reached. |
WSAEFAULT | The lpWSADatais not a valid pointer. |
An application cannot call WSAGetLastErrorto determine the error value as is normally done in Windows Sockets is WSAStartupfails. The Winsock.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.
Remarks
The WSAStartupfunction 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 to retrieve details of the specific Windows Sockets implementation. The application or DLL can only issue further Windows Sockets functions after a successfully calling WSAStartup.
To support future Windows Sockets implementations and applications that can have functionality differences from current version of Windows Sockets, a negotiation takes place in WSAStartup. The caller of WSAStartupand the Winsock.dll indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. Upon entry to WSAStartup, the Winsock.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.The Winsock.dll then assumes that the application will use wVersion.If the wVersionfield of the WSADATAstructure is unacceptable to the caller, it should call WSACleanupand either search for another Winsock.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 than the version of this specification. In such a case, the application is only guaranteed access to higher-version functionality that fits within the syntax defined in this version, such as new Ioctl codes and new behavior of existing functions. New functions, for example, may be inaccessible. To be guaranteed full access to 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 a Winsock.dll and a Windows Sockets application to support a range of Windows Sockets versions. An application can use Winsock.dll if there is any overlap in the version ranges. The following chart gives examples of how WSAStartupworks in conjunction with different application and Winsock.dll versions:
App versions | DLL versions |
wVersion
requested | wVersion |
wHigh
version | End 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.0 | 1.1 | 2.0 | 1.1 | 1.1 | use 1.1 |
Runs on | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 1.0 and later | Winsock.h |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also