Fonction WebSocketGetAction (websocket.h)

Article
08/27/2023

La fonction WebSocketGetAction retourne une action d’un appel à WebSocketSend, WebSocketReceive ou WebSocketCompleteAction.

Syntaxe

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

Paramètres

[in] hWebSocket

Type : WEB_SOCKET_HANDLE

Handle de session WebSocket retourné par un appel précédent à WebSocketCreateClientHandle ou WebSocketCreateServerHandle.

[in] eActionQueue

Type : WEB_SOCKET_ACTION_QUEUE

Énumération qui spécifie s’il faut interroger la file d’attente d’envoi, la file d’attente de réception ou les deux.

[in, out] pDataBuffers

Type : WEB_SOCKET_BUFFER*

Pointeur vers un tableau de structures WEB_SOCKET_BUFFER qui contiennent des données de mémoire tampon WebSocket.

Note N’allouez pas ou libérez pas la mémoire pour les structures WEB_SOCKET_BUFFER , car elles seront remplacées par WebSocketGetAction. La mémoire des mémoires tampons retournées par WebSocketGetAction est gérée par la bibliothèque.

[in, out] pulDataBufferCount

Type : ULONG*

En entrée, pointeur vers une valeur qui spécifie le nombre d’éléments dans pDataBuffers. En cas de sortie réussie, nombre d’éléments qui ont été retournés dans pDataBuffers.

[out] pAction

Type : WEB_SOCKET_ACTION*

En cas de sortie réussie, pointeur vers une énumération WEB_SOCKET_ACTION qui spécifie l’action renvoyée par la requête vers la file d’attente définie dans eActionQueue.

[out] pBufferType

Type : WEB_SOCKET_BUFFER_TYPE*

En cas de sortie réussie, pointez vers une énumération WEB_SOCKET_BUFFER_TYPE qui spécifie le type de données de mémoire tampon de socket web retournées dans pDataBuffers.

[out, optional] pvApplicationContext

Type : PVOID*

En cas de sortie réussie, pointeur vers un handle de contexte d’application. Le contexte retourné ici a été initialement passé à WebSocketSend ou WebSocketReceive. pvApplicationContext n’est pas défini si pAction est WEB_SOCKET_NO_ACTION ou WEB_SOCKET_SEND_TO_NETWORK_ACTION lors de l’envoi d’un pong en réponse à la réception d’un ping.

[out] pvActionContext

Type : PVOID*

En cas de sortie réussie, pointeur vers un handle de contexte d’action. Ce handle est passé dans un appel suivant WebSocketCompleteAction.

Valeur retournée

Type : HRESULT

Si la fonction réussit, elle retourne S_OK.

Si la fonction échoue, elle retourne l’un des éléments suivants ou un code d’erreur système défini dans WinError.h.

Code de retour	Description
E_INVALID_PROTOCOL_FORMAT	Le format des données de protocole n’était pas valide. Cette valeur est retournée uniquement pour les opérations de réception.
E_INVALID_PROTOCOL_OPERATION	Le protocole a effectué des opérations non valides. Cette valeur est retournée uniquement pour les opérations de réception.

Remarques

Chaque appel à WebSocketGetAction doit être associé à un appel à WebSocketCompleteAction.

Si le paramètre ulBytesTransferred de WebSocketCompleteAction est différent de la somme de toutes les longueurs de mémoire tampon pour l’action WEB_SOCKET_SEND_TO_NETWORK_ACTION ou de zéro pour l’action WEB_SOCKET_RECEIVE_FROM_NETWORK_ACTION , l’application WebSocket n’envoie ni ne reçoit toutes les données demandées.

WebSocketGetAction retourne dans pAction :

WEB_SOCKET_INDICATE_SEND_COMPLETE_ACTION une fois qu’une opération mise en file d’attente par WebSocketSend est terminée.
WEB_SOCKET_INDICATE_RECEIVE_COMPLETE_ACTION une fois qu’une opération mise en file d’attente par WebSocketReceive est terminée.

Il se peut qu’il n’y ait qu’une seule opération d’envoi et de réception en attente à la fois. L’action suivante sera retournée une fois la précédente terminée à l’aide de WebSocketCompleteAction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	websocket.h
Bibliothèque	Websocket.lib
DLL	Websocket.dll