Функция WSAsyncGetHostByName (winsock.h)

Функция WSAsyncGetHostByName асинхронно извлекает сведения об узле, соответствующие имени узла.

Синтаксис

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

Параметры

hWnd

TBD

wMsg

TBD

name

TBD

buf

TBD

buflen

TBD

Возвращаемое значение

Возвращаемое значение указывает, была ли успешно инициирована асинхронная операция. Это не означает успешность или неудачу самой операции.

Если ошибка не возникает, WSAsyncGetHostByName возвращает ненулевое значение типа HANDLE, которое является дескриптором асинхронной задачи (не следует путать с windows HTASK) для запроса. Это значение можно использовать двумя способами. Его можно использовать для отмены операции с помощью WSACancelAsyncRequest или для сопоставления асинхронных операций и сообщений о завершении путем проверки параметра сообщения wParam .

Если асинхронная операция не может быть инициирована, WSAsyncGetHostByName возвращает нулевое значение, а конкретный номер ошибки можно получить, вызвав WSAGetLastError.

При получении сообщения в окне приложения можно задать следующие коды ошибок. Как описано выше, их можно извлечь из lParam в ответном сообщении с помощью макроса WSAGETASYNCERROR.

Во время вызова функции могут возникать следующие ошибки, которые указывают на то, что не удалось инициировать асинхронную операцию.

Комментарии

Функция WSAsyncGetHostByName является асинхронной версией gethostbyname и используется для получения сведений об имени узла и адресе, соответствующих имени узла. Сокеты Windows инициируют операцию и немедленно возвращаются вызывающей стороне, передавая обратно непрозрачный дескриптор асинхронной задачи, который приложение может использовать для идентификации операции. После завершения операции результаты (если таковые имеются) копируются в буфер, предоставленный вызывающим объектом, и сообщение отправляется в окно приложения.

После завершения асинхронной операции окно приложения, указанное параметром hWnd , получает сообщение в параметре wMsg . Параметр wParam содержит дескриптор асинхронной задачи, возвращаемый исходным вызовом функции. Высокая 16 бит lParam содержит любой код ошибки. Код ошибки может быть любой ошибкой, как определено в Winsock2.h. Нулевой код ошибки указывает на успешное завершение асинхронной операции.

При успешном завершении буфер, указанный для исходного вызова функции, содержит структуру узла . Чтобы получить доступ к элементам этой структуры, исходный адрес буфера должен быть приведен к указателю структуры размещения и обращаться соответствующим образом.

Если код ошибки — WSAENOBUFS, размер буфера, указанного buflen в исходном вызове, был слишком мал, чтобы содержать все результирующие сведения. В этом случае низкие 16 бит lParam содержат размер буфера, необходимый для предоставления всей необходимой информации. Если приложение решит, что частичные данные неадекватны, оно может повторно выполнить вызов функции WSAsyncGetHostByName с буфером, достаточно большим для получения всей требуемой информации (то есть не меньше, чем низкие 16 бит lParam).

Буфер, указанный для этой функции, используется Сокетами Windows для создания структуры размещения вместе с содержимым областей данных, на которые ссылаются члены одной и той же структуры узла . Чтобы избежать ошибки WSAENOBUFS , приложение должно предоставить буфер не менее байтов MAXGETHOSTSTRUCT (как определено в Winsock2.h).

Код ошибки и длина буфера должны быть извлечены из lParam с помощью макросов WSAGETASYNCERROR и WSAGETASYNCBUFLEN, определенных в Winsock2.h как:

#include <windows.h>

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

Использование этих макросов обеспечит максимальную переносимость исходного кода для приложения.

WSAsyncGetHostByName гарантированно разрешает строку, возвращенную при успешном вызове gethostname.

Требования

См. также раздел

WSACancelAsyncRequest

Функции Winsock

Справочник по Winsock

getaddrinfo

Gethostbyname

getnameinfo

hostent