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

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

Синтаксис

HANDLE 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

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

[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