Função WebSocketGetAction (websocket.h)

Artigo
08/27/2023

A função WebSocketGetAction retorna uma ação de uma chamada para WebSocketSend, WebSocketReceive ou WebSocketCompleteAction.

Sintaxe

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

Parâmetros

[in] hWebSocket

Tipo: WEB_SOCKET_HANDLE

Identificador de sessão WebSocket retornado por uma chamada anterior para WebSocketCreateClientHandle ou WebSocketCreateServerHandle.

[in] eActionQueue

Tipo: WEB_SOCKET_ACTION_QUEUE

Enumeração que especifica se a fila de envio, a fila de recebimento ou ambas devem ser consultadas.

[in, out] pDataBuffers

Tipo: WEB_SOCKET_BUFFER*

Ponteiro para uma matriz de estruturas de WEB_SOCKET_BUFFER que contêm dados de buffer WebSocket.

Nota Não aloque nem desaloque a memória para estruturas de WEB_SOCKET_BUFFER , pois elas serão substituídas por WebSocketGetAction. A memória para buffers retornados por WebSocketGetAction é gerenciada pela biblioteca.

[in, out] pulDataBufferCount

Tipo: ULONG*

Na entrada, ponteiro para um valor que especifica o número de elementos em pDataBuffers. Na saída bem-sucedida, o número de elementos que foram realmente retornados em pDataBuffers.

[out] pAction

Tipo: WEB_SOCKET_ACTION*

Na saída bem-sucedida, o ponteiro para uma enumeração WEB_SOCKET_ACTION que especifica a ação retornada da consulta para a fila definida em eActionQueue.

[out] pBufferType

Tipo: WEB_SOCKET_BUFFER_TYPE*

Na saída bem-sucedida, ponteiro para uma enumeração WEB_SOCKET_BUFFER_TYPE que especifica o tipo de dados de buffer de Soquete Web retornados em pDataBuffers.

[out, optional] pvApplicationContext

Tipo: PVOID*

Na saída bem-sucedida, ponteiro para um identificador de contexto do aplicativo. O contexto retornado aqui foi inicialmente passado para WebSocketSend ou WebSocketReceive. pvApplicationContext não será definido se pAction for WEB_SOCKET_NO_ACTION ou WEB_SOCKET_SEND_TO_NETWORK_ACTION ao enviar um pong em resposta ao recebimento de um ping.

[out] pvActionContext

Tipo: PVOID*

Na saída bem-sucedida, ponteiro para um identificador de contexto de ação. Esse identificador é passado para uma chamada subsequente WebSocketCompleteAction.

Retornar valor

Tipo: HRESULT

Se a função for bem-sucedida, ela retornará S_OK.

Se a função falhar, ela retornará um dos seguintes ou um código de erro do sistema definido em WinError.h.

Código de retorno	Descrição
E_INVALID_PROTOCOL_FORMAT	Os dados do protocolo tinham formato inválido. Isso só é retornado para operações de recebimento.
E_INVALID_PROTOCOL_OPERATION	O protocolo executou operações inválidas. Isso só é retornado para operações de recebimento.

Comentários

Cada chamada para WebSocketGetAction deve ser emparelhada com uma chamada para WebSocketCompleteAction.

Se o parâmetro ulBytesTransferred de WebSocketCompleteAction for diferente da soma de todos os comprimentos de buffer para a ação WEB_SOCKET_SEND_TO_NETWORK_ACTION ou for zero para a ação WEB_SOCKET_RECEIVE_FROM_NETWORK_ACTION , o aplicativo WebSocket não enviará nem receberá todos os dados solicitados.

WebSocketGetAction retornará no pAction:

WEB_SOCKET_INDICATE_SEND_COMPLETE_ACTION depois que uma operação enfileirada por WebSocketSend for concluída.
WEB_SOCKET_INDICATE_RECEIVE_COMPLETE_ACTION depois que uma operação enfileirada por WebSocketReceive for concluída.

Pode haver apenas uma operação de envio e recebimento pendente por vez, portanto, a próxima ação será retornada depois que a anterior tiver sido concluída usando WebSocketCompleteAction.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	websocket.h
Biblioteca	Websocket.lib
DLL	Websocket.dll