WebSocketGetAction function (websocket.h)

Article
10/13/2021

The WebSocketGetAction function returns an action from a call to WebSocketSend, WebSocketReceive or WebSocketCompleteAction.

Syntax

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
);

Parameters

[in] hWebSocket

Type: WEB_SOCKET_HANDLE

WebSocket session handle returned by a previous call to WebSocketCreateClientHandle or WebSocketCreateServerHandle.

[in] eActionQueue

Type: WEB_SOCKET_ACTION_QUEUE

Enumeration that specifies whether to query the send queue, the receive queue, or both.

[in, out] pDataBuffers

Type: WEB_SOCKET_BUFFER*

Pointer to an array of WEB_SOCKET_BUFFER structures that contain WebSocket buffer data.

Note Do not allocate or deallocate memory for WEB_SOCKET_BUFFER structures, because they will be overwritten by WebSocketGetAction. The memory for buffers returned by WebSocketGetAction are managed by the library.

[in, out] pulDataBufferCount

Type: ULONG*

On input, pointer to a value that specifies the number of elements in pDataBuffers. On successful output, number of elements that were actually returned in pDataBuffers.

[out] pAction

Type: WEB_SOCKET_ACTION*

On successful output, pointer to a WEB_SOCKET_ACTION enumeration that specifies the action returned from the query to the queue defines in eActionQueue.

[out] pBufferType

Type: WEB_SOCKET_BUFFER_TYPE*

On successful output, pointer to a WEB_SOCKET_BUFFER_TYPE enumeration that specifies the type of Web Socket buffer data returned in pDataBuffers.

[out, optional] pvApplicationContext

Type: PVOID*

On successful output, pointer to an application context handle. The context returned here was initially passed to WebSocketSend or WebSocketReceive. pvApplicationContext is not set if pAction is WEB_SOCKET_NO_ACTION or WEB_SOCKET_SEND_TO_NETWORK_ACTION when sending a pong in response to receiving a ping.

[out] pvActionContext

Type: PVOID*

On successful output, pointer to an action context handle. This handle is passed into a subsequent call WebSocketCompleteAction.

Return value

Type: HRESULT

If the function succeeds, it returns S_OK.

If the function fails, it returns one of the following or a system error code defined in WinError.h.

Return code	Description
E_INVALID_PROTOCOL_FORMAT	Protocol data had invalid format. This is only returned for receive operations.
E_INVALID_PROTOCOL_OPERATION	Protocol performed invalid operations. This is only returned for receive operations.

Remarks

Each call to WebSocketGetAction must be paired with a call to WebSocketCompleteAction.

If the ulBytesTransferred parameter of WebSocketCompleteAction is different than the sum of all buffer lengths for the WEB_SOCKET_SEND_TO_NETWORK_ACTION action or is zero for the WEB_SOCKET_RECEIVE_FROM_NETWORK_ACTION action, the WebSocket application will not send or receive all of the data requested.

WebSocketGetAction will return in pAction:

WEB_SOCKET_INDICATE_SEND_COMPLETE_ACTION once an operation queued by WebSocketSend is completed.
WEB_SOCKET_INDICATE_RECEIVE_COMPLETE_ACTION once an operation queued by WebSocketReceive is completed.

There may be only one outstanding send and receive operation at a time, so the next action will be returned once the previous one has been completed using WebSocketCompleteAction.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	websocket.h
Library	Websocket.lib
DLL	Websocket.dll