WebSocketGetAction 函数 (websocket.h)

项目
03/03/2024

WebSocketGetAction 函数从调用 WebSocketSend、WebSocketReceive 或 WebSocketCompleteAction 返回操作。

语法

HRESULT WebSocketGetAction(
  [in]            WEB_SOCKET_HANDLE       hWebSocket,
  [in]            WEB_SOCKET_ACTION_QUEUE eActionQueue,
  [in, out]       WEB_SOCKET_BUFFER       *pDataBuffers,
  [in, out]       ULONG                   *pulDataBufferCount,
  [out]           WEB_SOCKET_ACTION       *pAction,
  [out]           WEB_SOCKET_BUFFER_TYPE  *pBufferType,
  [out, optional] PVOID                   *pvApplicationContext,
  [out]           PVOID                   *pvActionContext
);

参数

[in] hWebSocket

类型： WEB_SOCKET_HANDLE

以前调用 WebSocketCreateClientHandle 或 WebSocketCreateServerHandle 返回的 WebSocket 会话句柄。

[in] eActionQueue

类型： WEB_SOCKET_ACTION_QUEUE

指定是查询发送队列和/或接收队列的枚举。

[in, out] pDataBuffers

类型： WEB_SOCKET_BUFFER*

指向包含 WebSocket 缓冲区数据的 WEB_SOCKET_BUFFER 结构的数组的指针。

注意不要为 WEB_SOCKET_BUFFER 结构分配或解除分配内存，因为它们将被 WebSocketGetAction 覆盖。 WebSocketGetAction 返回的缓冲区的内存由库管理。

[in, out] pulDataBufferCount

类型： ULONG*

输入时，指针指向一个值，该值指定 pDataBuffers 中的元素数。成功输出时， pDataBuffers 中实际返回的元素数。

[out] pAction

类型： WEB_SOCKET_ACTION*

成功输出时，指向 WEB_SOCKET_ACTION 枚举的指针，该枚举指定从查询返回到队列的操作在 eActionQueue 中定义。

[out] pBufferType

类型： WEB_SOCKET_BUFFER_TYPE*

成功输出时，指向 WEB_SOCKET_BUFFER_TYPE 枚举的指针，该枚举指定 pDataBuffers 中返回的 Web 套接字缓冲区数据类型。

[out, optional] pvApplicationContext

类型： PVOID*

成功输出时，指向应用程序上下文句柄的指针。此处返回的上下文最初传递给 WebSocketSend 或 WebSocketReceive。如果在发送 pAction 以响应接收 ping 时WEB_SOCKET_NO_ACTION或WEB_SOCKET_SEND_TO_NETWORK_ACTION，则不设置 pvApplicationContext。

[out] pvActionContext

类型： PVOID*

成功输出时，指针指向操作上下文句柄。此句柄将传递到后续调用 WebSocketCompleteAction 中。

返回值

类型： HRESULT

如果函数成功，则返回 S_OK。

如果函数失败，它将返回以下代码之一或 WinError.h 中定义的系统错误代码之一。

返回代码	说明
E_INVALID_PROTOCOL_FORMAT	协议数据的格式无效。这仅针对接收操作返回。
E_INVALID_PROTOCOL_OPERATION	协议执行了无效操作。这仅针对接收操作返回。

注解

每次调用 WebSocketGetAction 必须与对 WebSocketCompleteAction 的调用配对。

如果 WebSocketCompleteAction 的 ulBytesTransferred 参数不同于WEB_SOCKET_SEND_TO_NETWORK_ACTION操作的所有缓冲区长度之和，或者对于WEB_SOCKET_RECEIVE_FROM_NETWORK_ACTION操作为零，则 WebSocket 应用程序不会发送或接收请求的所有数据。

WebSocketGetAction 将在 pAction 中返回：

WEB_SOCKET_INDICATE_SEND_COMPLETE_ACTION WebSocketSend 排队的操作完成后。
WEB_SOCKET_INDICATE_RECEIVE_COMPLETE_ACTION WebSocketReceive 排队的操作完成后。

一次可能只有一个未完成的发送和接收操作，因此使用 WebSocketCompleteAction 完成上一个操作后，将返回下一个操作。

要求

要求	值
最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	websocket.h
Library	Websocket.lib
DLL	Websocket.dll