WinAPI Reference
WinAPI Programmer's References
Win32
Win32 Multimedia
OLE
Pen API
Sockets 2
Telephony API (TAPI)

Websites for programmers
Delphi Tips&Tricks
Unix Manual Pages
MegaDetailed.Net

Software for programmers
Delphi components
.Net components

Free Components For Delphi and C++ Builder

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. 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
  • 0
    1. 1
    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


    Programming books recommended by Amazon.com

    More programming books on Amazon.com