Windows* Sockets 2 Application Programming Interface An Interface for Transparent Network Programming Under Microsoft Windowstm revision 2 August 7, 1997
Download 1.64 Mb.
|
- Navigate this page:
- WSADATA
- WSAStartup()
- WSACleanup()
- Return Value WSAStartup()
- See Also send() , sendto() , WSACleanup()
123 WSAStartup()Description Initiate use of the WinSock DLL by a process. #include int WSAAPI WSAStartup ( IN WORD wVersionRequested, OUT LPWSADATA lpWSAData ); wVersionRequested The highest version of WinSock 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 A pointer to the WSADATA data structure that is to receive details of the WinSock implementation. Remarks This function MUST be the first WinSock function called by an application or DLL. It allows an application or DLL to specify the version of WinSock required and to retrieve details of the specific WinSock implementation. The application or DLL may only issue further WinSock functions after a successful WSAStartup() invocation. In order to support future WinSock implementations and applications which may have functionality differences from current version of WinSock, a negotiation takes place in WSAStartup(). The caller of WSAStartup() and 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 wHighVersion the highest version it supports and in wVersion the minimum of its high version and wVersionRequested. The WinSock 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 WinSock DLL or fail to initialize. Note that 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, etc. This negotiation allows both a WinSock DLL and a WinSock application to support a range of WinSock versions. An application can successfully utilize a WinSock 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 WinSock DLL versions:
The following code fragment demonstrates how an application which supports only version 2.2 of WinSock makes a WSAStartup() call: WORD wVersionRequested; WSADATA wsaData; int err;
if ( err != 0 ) { /* Tell the user that we couldn't find a useable */ /* WinSock DLL. */ return; }
/* 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 couldn't find a useable */ /* 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 WinSock calls as needed. When it has finished using the services of the WinSock DLL, the application or DLL must call WSACleanup() in order to allow the WinSock DLL to free any resources for the application. Details of the actual WinSock 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; };
wVersion The version of the WinSock specification that the WinSock DLL expects the caller to use. wHighVersion The highest version of the WinSock specification that this DLL can support (also encoded as above). Normally this will be the same as wVersion. szDescription A null-terminated ASCII string into which the WinSock DLL copies a description of the WinSock 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 WinSock DLL copies relevant status or configuration information. The WinSock 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 backwards compatibility, but should be ignored for version 2.0 and onward as no single value can be appropriate for all underlying service providers. iMaxUdpDg This value should be ignored for version 2.0 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 WinSock 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.0 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.0. This is because the architecture of WinSock has been changed in version 2.0 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 WinSock 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 Value 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 WinSock 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 WinSock support requested is not provided by this particular WinSock implementation. WSAEINPROGRESS A blocking Windows Sockets 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() Download 1.64 Mb. Share with your friends:
|