WebSocketGetAction 函式 (websocket.h)

發行項
03/09/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。當傳送 pong 以回應接收 Ping 時，不會設定 pvApplicationContextWEB_SOCKET_NO_ACTION或WEB_SOCKET_SEND_TO_NETWORK_ACTION。

[out] pvActionContext

類型： PVOID*

成功輸出時，指向動作內容句柄的指標。此句柄會傳遞至後續呼叫 WebSocketCompleteAction。

傳回值

類型： HRESULT

如果函式成功，它會傳回 S_OK。

如果函式失敗，它會傳回下列其中一個或 WinError.h 中定義的系統錯誤碼。

傳回碼	Description
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
程式庫	Websocket.lib
Dll	Websocket.dll