The Windows Sockets WSAAsyncGetHostByName function gets host information corresponding to a hostnameasynchronous version.
HANDLE WSAAsyncGetHostByName (
[in] The handle of the window which should receive a message when the
asynchronous request completes.
[in] The message to be received when the asynchronous request completes.
[in] A pointer to the null terminated name of the host.
[out] A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure.
This is because the data area supplied is used by Windows Sockets to contain not
only a hostent structure but any and all of the data which is referenced by
members of the hostent structure. It is recommended that you supply a buffer of
[in] The size of data area buf above.
This function is an asynchronous version of gethostbyname, and is used to retrieve host name and address information corresponding to a
hostname. Windows Sockets initiates the operation and returns to the caller
immediately, passing back an opaque "asynchronous task handle" 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 is complete the application's window hWnd receives message wMsg. The wParam argument 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 supplied 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.
Note that if the error code is WSAENOBUFS, it indicates that the size of the
buffer specified by buflen in the original call was too small to contain all the resultant 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 error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
The use of these macros will maximize the portability of the source code for
WSAAsyncGetHostByName is guaranteed to resolve the string returned by a successful call to gethostname.
The return value specifies whether or not the asynchronous operation was
successfully initiated. Note that it does not imply success or failure of the
If the operation was successfully initiated, WSAAsyncGetHostByName returns a nonzero value of type HANDLE which 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. It can also be used to match up asynchronous operations and completion
messages, by examining the wParam message argument.
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 buffer supplied 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 noted above, the
application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined
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.
| HWND hWnd,
| unsigned int wMsg,
| const char FAR * name,
| char FAR * buf,
| int buflen
The following errors can occur at the time of the function call, and indicate
that the asynchronous operation could not be initiated.
||The network subsystem has failed.
||Insufficient buffer space is available.
||name or buf is not in a valid part of the process address space.
||Authoritative Answer Host not found.
||Non-Authoritative Host not found, or SERVERFAIL.
||Nonrecoverable errors, FORMERR, REFUSED, NOTIMP.
||Valid name, no data record of requested type.
gethostbyname, hostent, WSACancelAsyncRequest
||A successful WSAStartup must occur before using this function.
||The network subsystem has failed.
||A blocking Windows Sockets 1.1 call is in progress, or the service provider is
still processing a callback function.
||The asynchronous operation cannot be scheduled at this time due to resource or
other constraints within the Windows Sockets implementation.
Programming books recommended by Amazon.com
More programming books on Amazon.com
Share this page
|Last news from Greatis Software|
||.Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More »
|Recommended software for developers|
||Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More »
||Form Designer .Net
||Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More »
||Print Suite .Net
||Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More »
||Gradient Controls .Net
||Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More »
||iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More »
All the contacts and projects
Dmitry Vasiliev (just.dmitry)
Software for Visual Studio .NET developers
Software for Delphi and C++ Builder developers
Software for Visual Basic 6 developers
More Online Helps
Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages