Funzione WebSocketGetAction (websocket.h)

Articolo
03/13/2024

La funzione WebSocketGetAction restituisce un'azione da una chiamata a WebSocketSend, WebSocketReceive o WebSocketCompleteAction.

Sintassi

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

Parametri

[in] hWebSocket

Tipo: WEB_SOCKET_HANDLE

Handle di sessione WebSocket restituito da una chiamata precedente a WebSocketCreateClientHandle o WebSocketCreateServerHandle.

[in] eActionQueue

Tipo: WEB_SOCKET_ACTION_QUEUE

Enumerazione che specifica se eseguire query sulla coda di invio, sulla coda di ricezione o su entrambi.

[in, out] pDataBuffers

Tipo: WEB_SOCKET_BUFFER*

Puntatore a una matrice di strutture WEB_SOCKET_BUFFER che contengono dati del buffer WebSocket.

Nota Non allocare o deallocare la memoria per le strutture WEB_SOCKET_BUFFER , perché verranno sovrascritte da WebSocketGetAction. La memoria per i buffer restituiti da WebSocketGetAction viene gestita dalla libreria.

[in, out] pulDataBufferCount

Tipo: ULONG*

In input, puntatore a un valore che specifica il numero di elementi in pDataBuffers. In caso di output riuscito, numero di elementi effettivamente restituiti in pDataBuffers.

[out] pAction

Tipo: WEB_SOCKET_ACTION*

In output riuscito, puntatore a un'enumerazione WEB_SOCKET_ACTION che specifica l'azione restituita dalla query alla coda definisce in eActionQueue.

[out] pBufferType

Tipo: WEB_SOCKET_BUFFER_TYPE*

Nell'output riuscito, puntatore a un'enumerazione WEB_SOCKET_BUFFER_TYPE che specifica il tipo di dati del buffer del socket Web restituiti in pDataBuffers.

[out, optional] pvApplicationContext

Tipo: PVOID*

In caso di output riuscito, puntatore a un handle di contesto dell'applicazione. Il contesto restituito qui è stato inizialmente passato a WebSocketSend o WebSocketReceive. pvApplicationContext non è impostato se pAction è WEB_SOCKET_NO_ACTION o WEB_SOCKET_SEND_TO_NETWORK_ACTION quando si invia un pong in risposta alla ricezione di un ping.

[out] pvActionContext

Tipo: PVOID*

In caso di output riuscito, puntatore a un handle del contesto di azione. Questo handle viene passato a una chiamata successiva WebSocketCompleteAction.

Valore restituito

Tipo: HRESULT

Se la funzione ha esito positivo, restituisce S_OK.

Se la funzione ha esito negativo, restituisce uno dei seguenti o un codice di errore di sistema definito in WinError.h.

Codice restituito	Descrizione
E_INVALID_PROTOCOL_FORMAT	I dati del protocollo non hanno formato valido. Viene restituito solo per le operazioni di ricezione.
E_INVALID_PROTOCOL_OPERATION	Il protocollo ha eseguito operazioni non valide. Viene restituito solo per le operazioni di ricezione.

Commenti

Ogni chiamata a WebSocketGetAction deve essere associata a una chiamata a WebSocketCompleteAction.

Se il parametro ulBytesTransferred di WebSocketCompleteAction è diverso dalla somma di tutte le lunghezze del buffer per l'azione WEB_SOCKET_SEND_TO_NETWORK_ACTION o è zero per l'azione WEB_SOCKET_RECEIVE_FROM_NETWORK_ACTION, l'applicazione WebSocket non invierà o riceverà tutti i dati richiesti.

WebSocketGetAction restituirà in pAction:

WEB_SOCKET_INDICATE_SEND_COMPLETE_ACTION una volta completata un'operazione accodata da WebSocketSend .
WEB_SOCKET_INDICATE_RECEIVE_COMPLETE_ACTION una volta completata un'operazione accodata da WebSocketReceive .

È possibile che venga restituita una sola operazione di invio e ricezione in sospeso, quindi l'azione successiva verrà restituita una volta completata l'operazione precedente usando WebSocketCompleteAction.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	websocket.h
Libreria	Websocket.lib
DLL	Websocket.dll