WSAAsyncGetProtoByNumber 函数 (winsock.h)

WSAAsyncGetProtoByNumber 函数以异步方式检索与协议号对应的协议信息。

语法

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 参数的数据区域的大小(以字节为单位)。

返回值

返回值指定异步操作是否已成功启动。 它并不表示操作本身的成功或失败。

如果未发生错误, WSAAsyncGetProtoByNumber 将返回 HANDLE 类型的非零值,该值是请求的异步任务句柄, (不会与 Windows HTASK) 混淆。 可以通过两种方式使用此值。 它可用于使用 WSACancelAsyncRequest 取消操作,也可以通过检查 wParam message 参数来匹配异步操作和完成消息。

如果无法启动异步操作, WSAAsyncGetProtoByNumber 将返回零值,并且可以通过调用 WSAGetLastError 来检索特定的错误号。

当应用程序窗口收到消息时,可以设置以下错误代码。 如上所述,可以使用 WSAGETASYNCERROR 宏从回复消息中的 lParam 中提取它们。

错误代码 含义
WSAENETDOWN
网络子系统发生故障。
WSAENOBUFS
可用缓冲区空间不足。
WSAEFAULT
buf 参数不在进程地址空间的有效部分。
WSAHOST_NOT_FOUND
找不到权威应答协议。
WSATRY_AGAIN
找不到非授权协议,或服务器故障。
WSANO_RECOVERY
不可恢复的错误,协议数据库不可访问。
WSANO_DATA
有效名称,没有请求类型的数据记录。
 

函数调用时可能会出现以下错误,并指示无法启动异步操作。

错误代码 含义
WSANOTINITIALIZED 在使用此函数之前,必须成功调用 WSAStartup
WSAENETDOWN 网络子系统发生故障。
WSAEINPROGRESS 阻止 Windows 套接字 1.1 调用正在进行,或者服务提供商仍在处理回调函数。
WSAEWOULDBLOCK 由于 Windows 套接字实现中的资源或其他约束,此时无法计划异步操作。

注解

WSAAsyncGetProtoByNumber 函数是 getprotobynumber 的异步版本,用于检索与协议号对应的协议名称和编号。 Windows 套接字启动操作并立即返回到调用方,并传回应用程序可用于标识操作的不透明异步任务句柄。 操作完成后,结果 (是否将任何) 复制到调用方提供的缓冲区中,并将消息发送到应用程序的窗口。

异步操作完成后, hWnd 参数指示的应用程序窗口在 wMsg 参数中接收消息。 wParam 参数包含原始函数调用返回的异步任务句柄。 lParam 的高 16 位包含任何错误代码。 错误代码可以是 Winsock2.h 中定义的任何错误。 错误代码为零表示异步操作成功完成。

成功完成后,指定给原始函数调用的缓冲区将包含 原始 结构。 若要访问此结构的成员,原始缓冲区地址将强制转换为 原始 结构指针,并根据需要进行访问。

如果错误代码为 WSAENOBUFS,则原始调用中 buflen 指定的缓冲区大小太小,无法包含所有生成的信息。 在这种情况下,低 16 位 lParam 包含提供所有必要信息所需的缓冲区大小。 如果应用程序确定部分数据不足,则可以使用足够大的缓冲区重新发出 WSAAsyncGetProtoByNumber 函数调用,以接收所有所需信息 (,即不小于 lParam) 的低 16 位。

Windows 套接字使用为此函数指定的缓冲区来构造 原结构以及同一 原结构的成员引用的数据区域的内容。 为了避免上面提到的 WSAENOBUFS 错误,应用程序应提供至少 MAXGETHOSTSTRUCT 字节 (的缓冲区,如 Winsock2.h) 中定义。

应使用 Winsock2.h 中定义的宏 WSAGETASYNCERRORWSAGETASYNCBUFLENlParam 中提取错误代码和缓冲区长度:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

使用这些宏将最大程度地提高应用程序的源代码的可移植性。

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 winsock.h (包括 Winsock2.h)
Library Ws2_32.lib
DLL Ws2_32.dll

另请参阅

WSACancelAsyncRequest

Winsock 函数

Winsock 参考

getprotobynumber