|
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
Related Links
Software for Delphi and C++ Builder developers
Software for Visual Studio .NET developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET
More Online Helps
Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
OLE Programmer's Reference (ole.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (tapi.hlp)
Unix Manual Pages
|
