WSAAsyncGetHostByName function (winsock.h)

The WSAAsyncGetHostByName function asynchronously retrieves host information that corresponds to a host name.

Syntax

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

Parameters

hWnd

TBD

wMsg

TBD

name

TBD

buf

TBD

buflen

TBD

Return value

The return value specifies whether or not 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. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest, or it can be used to match up asynchronous operations and completion messages by examining the wParam message parameter.

If the asynchronous operation could not be initiated, WSAAsyncGetHostByName returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

The following error codes can be set when an application window receives a message. As described above, they can be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

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

Remarks

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

When the asynchronous operation has completed, the application window indicated by the hWnd parameter receives 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. The error code can be any error as defined in Winsock2.h. An error code of zero indicates successful completion of the asynchronous operation.

On successful completion, the buffer specified to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed 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 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, no smaller than the low 16 bits of lParam).

The buffer specified to 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 should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in Winsock2.h as:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

WSAAsyncGetHostByName is guaranteed to resolve the string returned by a successful call to gethostname.

Requirements

See also

WSACancelAsyncRequest

Winsock Functions

Winsock Reference

getaddrinfo

gethostbyname

getnameinfo

hostent