Функция WSAsyncGetProtoByNumber (winsock2.h)
Функция WSAsyncGetProtoByNumber асинхронно извлекает сведения о протоколе, соответствующие номеру протокола.
Синтаксис
HANDLE WSAAPI WSAAsyncGetProtoByNumber(
[in] HWND hWnd,
[in] u_int wMsg,
[in] int number,
[out] char *buf,
[in] int buflen
);
Параметры
[in] hWnd
Дескриптор окна, которое получит сообщение по завершении асинхронного запроса.
[in] wMsg
Сообщение, которое будет получено по завершении асинхронного запроса.
[in] number
Номер разрешаемого протокола в порядке байтов узла.
[out] buf
Указатель на область данных для получения данных-прототипов . Область данных должна быть больше, чем размер структуры-прототипа , так как область данных используется сокетами Windows для хранения структуры-прототипа и всех данных, на которые ссылаются члены структуры-прототипа . Рекомендуется использовать буфер в байтах MAXGETHOSTSTRUCT.
[in] buflen
Размер области данных для параметра buf в байтах.
Возвращаемое значение
Возвращаемое значение указывает, была ли успешно инициирована асинхронная операция. Это не означает успех или неудачу самой операции.
Если ошибка не возникает, WSAsyncGetProtoByNumber возвращает ненулевое значение типа HANDLE , которое является асинхронным дескриптором задачи для запроса (не следует путать с windows HTASK). Это значение можно использовать двумя способами. Его можно использовать для отмены операции с помощью WSACancelAsyncRequest или для сопоставления асинхронных операций и сообщений завершения путем проверки параметра сообщения wParam .
Если не удалось инициировать асинхронную операцию, WSAAsyncGetProtoByNumber возвращает нулевое значение, и конкретный номер ошибки можно получить, вызвав WSAGetLastError.
При получении сообщения в окне приложения можно задать следующие коды ошибок. Как описано выше, их можно извлечь из lParam в ответном сообщении с помощью макроса WSAGETASYNCERROR .
| Код ошибки | Значение |
|---|---|
| Произошел сбой сетевой подсистемы. | |
| Недостаточно места в буфере. | |
| Параметр buf не находится в допустимой части адресного пространства процесса. | |
| Протокол достоверного ответа не найден. | |
| Неавторизированный протокол не найден или сбой сервера. | |
| Неустранимые ошибки, база данных протоколов недоступна. | |
| Допустимое имя, без записи данных запрошенного типа. |
Во время вызова функции могут возникнуть следующие ошибки, указывающие на то, что не удалось инициировать асинхронную операцию.
| Код ошибки | Значение |
|---|---|
| WSANOTINITIALISED | Перед использованием этой функции должен произойти успешный вызов WSAStartup . |
| WSAENETDOWN | Произошел сбой сетевой подсистемы. |
| WSAEINPROGRESS | Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова. |
| WSAEWOULDBLOCK | В настоящее время асинхронную операцию невозможно запланировать из-за ограничений ресурсов или других ограничений в реализации сокетов Windows. |
Комментарии
Функция WSAsyncGetProtoByNumber является асинхронной версией getprotobynumber и используется для получения имени и номера протокола, соответствующих номеру протокола. Сокеты Windows инициируют операцию и немедленно возвращаются вызывающей стороне, передавая непрозрачный асинхронный дескриптор задачи, который приложение может использовать для идентификации операции. После завершения операции результаты (если таковые имеются) копируются в буфер, предоставленный вызывающим объектом, и сообщение отправляется в окно приложения.
После завершения асинхронной операции окно приложения, указанное параметром hWnd , получает сообщение в параметре wMsg . Параметр wParam содержит дескриптор асинхронной задачи, возвращенный исходным вызовом функции. Высокие 16 бит lParam содержат любой код ошибки. Код ошибки может быть любой ошибкой, как определено в Winsock2.h. Код ошибки, равный нулю, указывает на успешное завершение асинхронной операции.
При успешном завершении буфер, указанный в исходном вызове функции, содержит структуру-прототип . Для доступа к членам этой структуры исходный адрес буфера приводится к указателю структуры-прототипа и обращается соответствующим образом.
Если код ошибки — WSAENOBUFS, размер буфера, указанного buflen в исходном вызове, был слишком мал, чтобы содержать все полученные сведения. В этом случае низкие 16 бит lParam содержат размер буфера, необходимый для предоставления всей необходимой информации. Если приложение решит, что частичные данные неадекватны, оно может повторно вывести вызов функции WSAsyncGetProtoByNumber с буфером, достаточно большим для получения всей необходимой информации (то есть не меньше 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 | winsock2.h (включая Winsock2.h) |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |