Поделиться через


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

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

Синтаксис

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

Параметры

[in] hWnd

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

[in] wMsg

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

[in] name

Указатель на имя протокола, завершаемого значением NULL, для разрешения.

[out] buf

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

[out] buflen

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

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

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

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

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

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

Код ошибки Значение
WSAENETDOWN
Произошел сбой сетевой подсистемы.
WSAENOBUFS
Недостаточно места в буфере.
WSAEFAULT
Параметр name или buf не входит в допустимую часть адресного пространства процесса.
WSAHOST_NOT_FOUND
Протокол достоверного ответа не найден.
WSATRY_AGAIN
Неавторизированный протокол не найден или сбой сервера.
WSANO_RECOVERY
Неустранимые ошибки, база данных протоколов недоступна.
WSANO_DATA
Допустимое имя, без записи данных запрошенного типа.
 

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

Код ошибки Значение
WSANOTINITIALISED Перед использованием этой функции должен произойти успешный вызов WSAStartup .
WSAENETDOWN Произошел сбой сетевой подсистемы.
WSAEINPROGRESS Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEWOULDBLOCK В настоящее время асинхронную операцию невозможно запланировать из-за ограничений ресурсов или других ограничений в реализации сокетов Windows.

Комментарии

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

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

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

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

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

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header winsock.h (включая Winsock2.h)
Библиотека Ws2_32.lib
DLL Ws2_32.dll

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

WSACancelAsyncRequest

Функции Winsock

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

getprotobyname