<!--Content type: PSDK_1. Transform: psdk2mtps.xslt.-->
<!---->
The WSAStartup function initiates use of WS2_32.DLL by a process.
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.
- lpWSAData
- [out] Pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.
Return Values
The
WSAStartup function returns zero if successful. Otherwise, it returns one of the error codes listed in the following.
An application cannot call
WSAGetLastError to determine the error code as is normally done in Windows Sockets if
WSAStartup fails. The WS2_32.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.
| Error code |
Meaning |
| 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. |
| WSAEINPROGRESS |
A blocking Windows Sockets 1.1 operation is in progress. |
| WSAEPROCLIM |
Limit on the number of tasks supported by the Windows Sockets implementation has been reached. |
| WSAEFAULT |
The lpWSAData is not a valid pointer. |
Remarks
The WSAStartup 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.
In order 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
WSAStartup and the WS2_32.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 WS2_32.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
wHighVersion the highest version it supports and in
wVersion the minimum of its high version and
wVersionRequested. The WS2_32.DLL then assumes that the application will use
wVersion If the
wVersion parameter of the
WSADATA structure is unacceptable to the caller, it should call
WSACleanup and either search for another WS2_32.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 Ioctl codes 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 a WS2_32.DLL and a Windows Sockets application to support a range of Windows Sockets versions. An application can use WS2_32.DLL if there is any overlap in the version ranges. The following table shows how WSAStartup works with different applications and WS2_32.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 |
--- |
--- |
WSAVERNOTSUPPORTED |
| 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 |
| 2.0 |
2.0 |
2.0 |
2.0 |
2.0 |
use 2.0 |
Example Code
The following code fragment demonstrates how an application that supports only version 2.2 of Windows Sockets makes a WSAStartup call:
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 greater */
/* 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. */
Example Code
Once an application or DLL has made a successful
WSAStartup call, it can proceed to make other Windows Sockets calls as needed. When it has finished using the services of the WS2_32.DLL, the application or DLL must call
WSACleanup to allow the WS2_32.DLL to free any resources for the application.
Details of the actual Windows Sockets implementation are described in the
WSADATA structure.
An application or DLL can call WSAStartup more than once if it needs to obtain the WSADATA structure information more than once. On each such call the application can specify any version number supported by the DLL.
An application must call one WSACleanup call for every successful WSAStartup call to allow third-party DLLs to make use of a WS2_32.DLL on behalf of an application. This means, for example, that if an application calls WSAStartup three times, it must call WSACleanup three times. The first two calls to WSACleanup do nothing except decrement an internal counter; the final WSACleanup call for the task does all necessary resource deallocation for the task.
Requirements
| Client |
Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95. |
| Server |
Requires Windows Server "Longhorn", Windows Server 2003, Windows 2000 Server, or Windows NT Server. |
| Header |
Declared in Winsock2.h.
|
| Library |
Use Ws2_32.lib.
|
| DLL |
Requires Ws2_32.dll. |
See Also
發表時間：2006-07-27 15:23:52
IP:61.222.xxx.xxx 未訂閱
Copy Code