WebSocketGetAction function
The WebSocketGetAction function returns an action from a call to WebSocketSend, WebSocketReceive or WebSocketCompleteAction.
Syntax
HRESULT WINAPI WebSocketGetAction( _In_ WEB_SOCKET_HANDLE hWebSocket, _In_ WEB_SOCKET_ACTION_QUEUE eActionQueue, _Inout_ WEB_SOCKET_BUFFER *pDataBuffers, _Inout_ ULONG *pulDataBufferCount, _Out_ WEB_SOCKET_ACTION *pAction, _Out_ WEB_SOCKET_BUFFER_TYPE *pBufferType, _Out_opt_ PVOID *pvApplicationContext, _Out_ PVOID *pvActionContext );
Parameters
- hWebSocket [in]
-
Type: WEB_SOCKET_HANDLE
WebSocket session handle returned by a previous call to WebSocketCreateClientHandle or WebSocketCreateServerHandle.
- eActionQueue [in]
-
Type: WEB_SOCKET_ACTION_QUEUE
Enumeration that specifies whether to query the send queue, the receive queue, or both.
- pDataBuffers [in, out]
-
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. - pulDataBufferCount [in, out]
-
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.
- pAction [out]
-
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.
- pBufferType [out]
-
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.
- pvApplicationContext [out, optional]
-
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.
- pvActionContext [out]
-
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 |
|---|---|
|
Protocol data had invalid format. This is only returned for receive operations. |
|
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
|
Minimum supported client | Windows 8 [desktop apps only] |
|---|---|
|
Minimum supported server | Windows Server 2012 [desktop apps only] |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- WebSocketCompleteAction
- WebSocketSend
- WebSocketReceive
- WEB_SOCKET_ACTION
- WEB_SOCKET_ACTION_QUEUE
- WEB_SOCKET_BUFFER_TYPE