WSAStartup
The Windows Sockets
WSAStartup function initiates use of the Windows Sockets DLL by a process.
int WSAStartup (
WORD wVersionRequested,
|
|
LPWSADATA lpWSAData
|
|
);
|
|
Parameters
wVersionRequested
[in] The 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] A pointer to the
WSADATA data structure that is to receive details of the Windows Sockets
implementation.
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 to retrieve details of the specific Windows Sockets implementation. The
application or DLL may only issue further Windows Sockets functions after a
successful
WSAStartup invocation.
In order to support future Windows Sockets implementations and applications
which may have functionality differences from current version of Windows Sockets,
a negotiation takes place in
WSAStartup. The caller of
WSAStartup and the Windows Sockets 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 Windows Sockets 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 Windows Sockets DLL then assumes that the application will use
wVersion. If the
wVersion field of the
WSADATA structure is unacceptable to the caller, it should call
WSACleanup and either search for another Windows Sockets DLL or fail to initialize.
This negotiation allows both a Windows Sockets DLL and a Windows Sockets
application to support a range of Windows Sockets versions. An application can
successfully utilize a Windows Sockets DLL if there is any overlap in the version
ranges. The following chart gives examples of how
WSAStartup works in conjunction with different application and Windows Sockets DLL
versions:
App versions
| DLL Versions
| wVersion
Requested
| wVersion
| wHigh
Version
| End Result
|
- 1
| - 1
| - 1
| - 1
| - 1
| use 1.1
|
- 0 1.1
| - 0
| - 1
| - 0
| - 0
| use 1.0
|
- 0
| - 0 1.1
| - 0
| - 0
| - 1
| use 1.0
|
- 1
| - 0 1.1
| - 1
| - 1
| - 1
| use 1.1
|
- 1
| - 0
| - 1
| - 0
| - 0
| Application fails
|
- 0
| - 1
| - 0
| ---
| ---
| WSAVERNOT
SUPPORTED
|
- 0 1.1
| - 0 1.1
| - 1
| - 1
| - 1
| use 1.1
|
- 1 2.0
| - 1
| 0
| - 1
| - 1
| use 1.1
|
2.0
| 2.0
| 2.0
| 2.0
| 2.0
| use 2.0
|
The following code fragment demonstrates how an application which supports
only version 2 of Windows Sockets makes a
WSAStartup call:
WORD wVersionRequested;
WSADATA wsaData;
int err;
wVersionRequested = MAKEWORD( 2, 0 );
err = WSAStartup( wVersionRequested, &wsaData );
if ( err != 0 ) {
/* Tell the user that we couldn't find a usable */
/* WinSock DLL. */
return;
}
/* Confirm that the WinSock DLL supports 2.0.*/
/* Note that if the DLL supports versions greater */
/* than 2.0 in addition to 2.0, it will still return */
/* 2.0 in wVersion since that is the version we */
/* requested. */
if ( LOBYTE( wsaData.wVersion ) != 2 ||
HIBYTE( wsaData.wVersion ) != 0 ) {
/* Tell the user that we couldn't find a usable */
/* WinSock DLL. */
WSACleanup( );
return;
}
/* The WinSock DLL is acceptable. Proceed. */
Once an application or DLL has made a successful
WSAStartup call, it may proceed to make other Windows Sockets calls as needed. When it
has finished using the services of the Windows Sockets DLL, the application or
DLL must call
WSACleanup in order to allow the Windows Sockets DLL to free any resources for the
application.
Details of the actual Windows Sockets implementation are described in the
WSAData structure defined as follows:
struct WSAData {
WORD wVersion;
WORD wHighVersion;
char
szDescription[WSADESCRIPTION_LEN+1];
char szSystemStatus[WSASYSSTATUS_LEN+1];
unsigned short iMaxSockets;
unsigned short iMaxUdpDg;
char FAR * lpVendorInfo;
};
The members of this structure are:
Parameters
wVersion
The version of the Windows Sockets specification that the Windows Sockets DLL
expects the caller to use.
wHighVersion
The highest version of the Windows Sockets specification that this DLL can
support (also encoded as above). Normally this will be the same as
wVersion.
sz
A null-terminated ASCII string into which the Windows Sockets DLL copies a
description of the Windows Sockets implementation. The text (up to 256 characters
in length) may contain any characters except control and formatting characters:
the most likely use that an application will put this to is to display it
(possibly truncated) in a status message.
szSystemStatus
A null-terminated ASCII string into which the Windows Sockets DLL copies
relevant status or configuration information. The Windows Sockets DLL should use
this field only if the information might be useful to the user or support staff:
it should not be considered as an extension of the
szDescription field.
iMaxSockets
This field is retained for backward compatibility, but should be ignored for
version 2 and later as no single value can be appropriate for all underlying
service providers.
iMaxUdpDg
This value should be ignored for version 2 and onward. It is retained for
compatibility with Windows Sockets specification 1.1, but should not be used when
developing new applications. For the actual maximum message size specific to a
particular Windows Sockets service provider and socket type, applications should
use
getsockopt to retrieve the value of option SO_MAX_MSG_SIZE after a socket has been
created.
lpVendorInfo
This value should be ignored for version 2 and onward. It is retained for
compatibility with Windows Sockets specification 1.1. Applications needing to
access vendor-specific configuration information should use
getsockopt to retrieve the value of option PVD_CONFIG. The definition of this value (if
utilized) is beyond the scope of this specification.
Note that an application should ignore the
iMaxsockets,
iMaxUdpDg, and
lpVendorInfo fields in WSAData if the value in
wVersion after a successful call to
WSAStartup is at least 2. This is because the architecture of Windows Sockets has been
changed in version 2 to support multiple providers, and WSAData no longer
applies to a single vendor's stack. Two new socket options are introduced to supply
provider-specific information: SO_MAX_MSG_SIZE (replaces the
iMaxUdpDg element) and PVD_CONFIG (allows any other provider-specific configuration to
occur).
An application or DLL may call
WSAStartup more than once if it needs to obtain the WSAData structure information more
than once. On each such call the application may specify any version number
supported by the DLL.
There must be one
WSACleanup call corresponding to every successful
WSAStartup call to allow third-party DLLs to make use of a Windows Sockets 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.
Return Values
WSAStartup returns zero if successful. Otherwise, it returns one of the error codes
listed below. Note that the normal mechanism whereby the application calls
WSAGetLastError to determine the error code cannot be used, since the Windows Sockets DLL may
not have established the client data area where the "last error" information
is stored.
Error Codes
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.
|
See Also
send,
sendto,
WSACleanup
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database
