WINSOCK API REFERENCE - MICROSOFT

Home

API File Search
Filedialogs
The FILES statement
The FILES statement in action
Open Source Editor for WinXP
Spotlight on John Fisher
Using Winsock
Winsock API Reference


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


WSAData

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.


WSACleanup

The Windows Sockets WSACleanup function terminates use of the Windows Sockets DLL.

int WSACleanup (void);

Remarks

An application or DLL is required to perform a successful WSAStartup call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application or DLL must call WSACleanup to deregister itself from a Windows Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL. Any pending blocking or asynchronous calls issued by any thread in this process are canceled without posting any notification messages, or signaling any event objects. Any pending overlapped send and receive operations (WSASend/WSASendTo/WSARecv/WSARecvFrom with an overlapped socket) issued by any thread in this process are also canceled without setting the event object or invoking the completion routine, if specified. In this case, the pending overlapped operations fail with the error status WSA_OPERATION_ABORTED. Any sockets open when WSACleanup is called are reset and automatically deallocated as if closesocket was called; sockets which have been closed with closesocket but which still have pending data to be sent may be affectedthe pending data may be lost if the Windows Sockets DLL is unloaded from memory as the application exits. To insure that all pending data is sent an application should use shutdown to close the connection, then wait until the close completes before calling closesocket and WSACleanup. All resources and internal state, such as queued un-posted messages, must be deallocated so as to be available to the next user.

There must be a call to WSACleanup for every successful call to WSAStartup made by a task. Only the final WSACleanup for that task does the actual cleanup; the preceding calls simply decrement an internal reference count in the Windows Sockets DLL.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Comments

Attempting to call WSACleanup from within a blocking hook and then failing to check the return code is a common Windows Sockets programming error. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with WSACancelBlockingCall then issue the WSACleanup call once control has been returned to the application. In a multithreaded environment, WSACleanup terminates Windows Sockets operations for all threads.

Error Codes

WSANOTINITIALISED A successful WSAStartup must occur before using this function.
WSAENETDOWN The network subsystem has failed.
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.


gethostbyname

The Windows Sockets gethostbyname function gets host information corresponding to a hostname.

struct hostent FAR * gethostbyname (const char FAR * name ); Parameters

name

[out] A pointer to the null terminated name of the host.

Remarks

gethostbyname returns a pointer to a hostent structure. The contents of this structure correspond to the hostname name.

The pointer which is returned points to a structure which is allocated by Windows Sockets. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets function calls.

gethostbyname does not resolve IP address strings passed to it. Such a request is treated exactly as if an unknown host name were passed. An application with an IP address string to resolve should use inet_addr to convert the string to an IP address, then gethostbyaddr to obtain the hostent structure.

gethostbyname will resolve the string returned by a successful call to gethostname.

Return Values

If no error occurs, gethostbyname returns a pointer to the hostent structure described above. Otherwise, it returns a NULL pointer and a specific error number can be retrieved by calling WSAGetLastError.


This structure is allocated by Windows Sockets. An application should never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information that it needs before issuing any other Windows Sockets API calls.

struct hostent {
     char FAR * h_name;
     char FAR * FAR * h_aliases;
     short h_addrtype;
     short h_length;
     char FAR * FAR * h_addr_list;
     };
     

Members

h_name

Official name of the host (PC).If using the DNS or similar resolution system, it is the Fully Qualified Domain Name (FQDN) that caused the server to return a reply. If using a local "hosts" file, it is the first entry after the IP address.

h_aliases

A NULL-terminated array of alternate names.

h_addrtype

The type of address being returned.

h_length

The length, in bytes, of each address.

h_addr_list

A NULL-terminated list of addresses for the host. Addresses are returned in network byte order.The macro h_addr is defined to be h_addr_list[0] for compatibility with older software.

Error Codes

WSANOTINITIALISED A successful WSAStartup must occur before using this function.
WSAENETDOWN The network subsystem has failed.
WSAHOST_NOT_FOUND Authoritative Answer Host not found.
WSATRY_AGAIN Non-Authoritative Host not found, or server failure.
WSANO_RECOVERY Nonrecoverable error occurred.
WSANO_DATA Valid name, no data record of requested type.
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT The name argument is not a valid part of the user address space.
WSAEINTR The (blocking) call was canceled through WSACancelBlockingCall.


inet_ntoa

The Windows Sockets inet_ntoa function converts a network address into a string in dotted format.

char FAR * inet_ntoa (struct in_addr in ); Parameters

in

[in] A structure which represents an Internet host address.

Remarks

This function takes an Internet address structure specified by the in parameter. It returns an ASCII string representing the address in ".'' notation as "a.b.c.d''. Note that the string returned by inet_ntoa resides in memory which is allocated by Windows Sockets. The application should not make any assumptions about the way in which the memory is allocated. The data is guaranteed to be valid until the next Windows Sockets function call within the same thread, but no longer.

Return Values

If no error occurs, inet_ntoa returns a char pointer to a static buffer containing the text address in standard ".'' notation.
Otherwise, it returns NULL. The data should be copied before another Windows Sockets call is made.


RtlMoveMemory

RtlMoveMemory moves memory either forward or backward, aligned or unaligned, in 4-byte blocks, followed by any remaining bytes.

VOID 
     RtlMoveMemory(
     IN VOID UNALIGNED *Destination,
     IN CONST VOID UNALIGNED *Source,
     IN SIZE_T Length
     );
   

Parameters

Destination
Points to the destination of the move.

Source
Points to the memory to be copied.

Length
Specifies the number of bytes to be copied.


Comments

The (Source + Length) can overlap the Destination range passed in to RtlMoveMemory.

Callers of RtlMoveMemory can be running at any IRQL if both memory blocks are resident. Otherwise, the caller must be running at IRQL < DISPATCH_LEVEL.

Home

API File Search
Filedialogs
The FILES statement
The FILES statement in action
Open Source Editor for WinXP
Spotlight on John Fisher
Using Winsock
Winsock API Reference