Функция WSAsyncGetServByName (winsock2.h)

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

Синтаксис

HANDLE WSAAPI WSAAsyncGetServByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [in]  const char *proto,
  [out] char       *buf,
  [in]  int        buflen
);

Параметры

[in] hWnd

Дескриптор окна, которое должно получать сообщение после завершения асинхронного запроса.

[in] wMsg

Сообщение, которое будет получено по завершении асинхронного запроса.

[in] name

Указатель на имя службы, завершаемое null.

[in] proto

Указатель на имя протокола. Это может быть значение NULL. В этом случае WSAsyncGetServByName выполнит поиск первой записи службы, для которой s_name или один из s_aliases соответствует заданному имени. В противном случае WSAsyncGetServByName соответствует имени и proto.

[out] buf

Указатель на область данных для получения данных. Область данных должна быть больше, чем размер обслуживающей структуры, так как область данных используется сокетами Windows для размещения обслуживающей структуры и всех данных, на которые ссылаются члены структуры обслуживания . Рекомендуется использовать буфер в байтах MAXGETHOSTSTRUCT.

[in] buflen

Размер области данных для параметра buf в байтах.

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

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

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

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

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

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

Комментарии

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

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

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

Если код ошибки — WSAENOBUFS, размер буфера, указанного buflen в исходном вызове, был слишком мал, чтобы содержать все полученные сведения. В этом случае низкие 16 бит lParam содержат размер буфера, необходимый для предоставления всей необходимой информации. Если приложение решит, что частичные данные недостаточны, оно может повторно отправить вызов функции WSAsyncGetServByName с буфером, достаточно большим для получения всех нужных сведений (т. е. не меньше низких 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)

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

Требования

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

WSACancelAsyncRequest

Функции Winsock

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

getservbyname