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

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

Синтаксис

HANDLE 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 .

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

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

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

Комментарии

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

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

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

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

Буфер, указанный для этой функции, используется сокетами Windows для создания protoent структуры вместе с содержимым областей данных, на которые ссылаются члены одной и той же структуры-прототипа . Чтобы избежать ошибки 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

getprotobynumber