WSAAsyncGetHostByName (Compact 2013)

  • Article

3/26/2014

Deprecated.

This function asynchronously retrieves information about a host that corresponds to a host name.

Syntax

HANDLE WSAAsyncGetHostByName(  _In_   HWND hWnd  _In_   unsigned int wMsg,  _In_   const char *name,  _Out_  char *buf,  _In_   int buflen);

Parameters

  • hWnd
    [in] Handle of the window that receives a message when the asynchronous request completes.
  • wMsg
    [in] Message to be received when the asynchronous request completes.
  • *name
    [in] Pointer to the null-terminated name of the host.
  • *buf
    [out] Pointer to the data area that receives the hostent data. The data area must be larger than the size of a hostent structure because the specified data area is used by Windows Sockets to contain a hostent structure and all of the data referenced by members of the hostent structure. We recommend a buffer of MAXGETHOSTSTRUCT bytes.
  • *buflen
    [in] Pointer to the size of the data for the buf parameter, in bytes.

Return Value

The return value specifies whether the asynchronous operation was successfully initiated. It does not imply success or failure of the operation itself.

If no error occurs, WSAAsyncGetHostByName returns a nonzero value of type HANDLE that is the asynchronous task handle, not to be confused with a Windows HTASK, for the request. You can use this value in two ways. You can use it to cancel the operation by using WSACancelAsyncRequest, or you can use it to match up asynchronous operations and completion messages by examining the wParam message parameter.

If the asynchronous operation was not initiated, WSAAsyncGetHostByName returns a 0 (zero) value. You can retrieve a specific error number by calling WSAGetLastError.

Exceptions

The following error codes can occur when an application window receives a message. As described above, you can extract an error code from the lParam parameter in the reply message by using the WSAGETASYNCERROR macro.

Error Code

Meaning

WSAENETDOWN

The network subsystem has failed.

WSAENOBUFS

Insufficient buffer space is available.

WSAEFAULT

The name or buf parameter is not in a valid part of the process address space.

WSAHOST_NOT_FOUND

Authoritative answer host not found.

WSATRY_AGAIN

A nonauthoritative host not found, or SERVERFAIL.

WSANO_RECOVERY

Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.

WSANO_DATA

Valid name, no data record of requested type.

The following errors can occur at the time of the function call and indicate that the asynchronous operation could not be initiated.

Error Code

Meaning

WSANOTINITIALISED

A successful WSAStartup call must finish before you can use 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.

WSAEWOULDBLOCK

The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

Remarks

The WSAAsyncGetHostByName function is an asynchronous version of gethostbyname (deprecated) and is used to retrieve host name and address information. WSAAsyncGetHostByName is guaranteed to resolve the string returned by a successful call to gethostname. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque asynchronous task handle that the application can use to identify the operation. When the operation is complete, the results, if any, are copied into the buffer provided by the caller and a message is sent to the application's window.

To use the IPv6 protocol, the recommended function is getaddrinfo.

When the asynchronous operation finishes, the application window indicated by the hWnd parameter receives a message in the wMsg parameter. The wParam parameter contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. An error code can be any error that is defined in Winsock2.h. An error code of 0 (zero) in the high 16 bits of lParam indicates successful completion of the asynchronous operation.

On successful completion, the buffer specified by the original function call contains a hostent structure. To access the elements of this structure, cast the original buffer address to a hostent structure pointer and access as appropriate.

If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all the resulting information. In this case, the low 16 bits of lParam contain the size of the buffer required to supply all the requisite information. If the application decides that the partial data is inadequate, it can reissue the WSAAsyncGetHostByName function call with a buffer large enough to receive all the desired information; that is, a buffer no smaller than the low 16 bits of lParam.

The buffer specified by this function is used by Windows Sockets to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error, the application must provide a buffer of at least MAXGETHOSTSTRUCT bytes as defined in Winsock2.h.

The error code and buffer length are extracted from the lParam parameter by using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in Winsock2.h, as follows:

#include <windows.h>
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

See Also

Reference

Windows-Specific Extension Functions
getaddrinfo
gethostname
WSAGetLastError
WSACancelAsyncRequest
WSAAsyncGetHostByName