PFN_WSK_RECEIVE_EVENT fonction de rappel (wsk.h)

Article
08/08/2023

La fonction de rappel d’événement WskReceiveEvent avertit une application WSK que des données ont été reçues sur un socket orienté connexion.

Syntaxe

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

Paramètres

[in, optional] SocketContext

Pointeur vers le contexte de socket pour le socket orienté connexion qui a reçu les données. L’application WSK a fourni ce pointeur vers le sous-système WSK de l’une des manières suivantes :

Il a appelé la fonction WskSocket pour créer le socket.
Il a appelé la fonction WskSocketConnect pour créer le socket.
Il a appelé la fonction WskAccept pour accepter le socket en tant que connexion entrante.
Sa fonction de rappel d’événement WskAcceptEvent a été appelée pour accepter le socket en tant que connexion entrante.

[in] Flags

Valeur ULONG qui contient un OR au niveau du bit d’une combinaison des indicateurs suivants :

Valeur	Signification
WSK_FLAG_RELEASE_ASAP	Les mémoires tampons de données qui contiennent les données reçues ne doivent pas être conservées par l’application WSK si possible. Si l’application WSK conserve les mémoires tampons, elle doit les libérer dès que possible en appelant la fonction WskRelease .
WSK_FLAG_ENTIRE_MESSAGE	Les mémoires tampons de données contiennent un message entier ou la dernière partie d’un message. L’interprétation de ce qui constitue un message entier est spécifique au protocole de transport. Pour TCP, cet indicateur indique que le bit push a été défini pour un ou plusieurs segments TCP qui constituent les données dans les mémoires tampons de données.
WSK_FLAG_AT_DISPATCH_LEVEL	Le sous-système WSK a appelé la fonction de rappel d’événement WskReceiveEvent à IRQL = DISPATCH_LEVEL. Si cet indicateur n’est pas défini, le sous-système WSK a peut-être appelé la fonction de rappel d’événement WskReceiveEvent à n’importe quel

[in, optional] DataIndication

Pointeur vers une liste liée de structures WSK_DATA_INDICATION qui décrivent les données reçues. Si ce paramètre a la valeur NULL, le socket n’est plus fonctionnel et l’application WSK doit appeler la fonction WskCloseSocket pour fermer le socket dès que possible.

[in] BytesIndicated

Nombre d’octets de données reçues décrite par la liste liée des structures de WSK_DATA_INDICATION .

[in, out] BytesAccepted

Pointeur vers une variable de type SIZE_T qui reçoit le nombre d’octets de données reçues acceptées par l’application WSK. Cette variable doit être définie uniquement si l’application WSK accepte une partie du nombre total d’octets de données reçues. Si l’application WSK accepte toutes les données reçues, elle n’a pas besoin de définir cette variable. Si la fonction de rappel d’événement WskReceiveEvent retourne une status autre que STATUS_SUCCESS, le sous-système WSK ignore la valeur de cette variable.

Valeur retournée

La fonction de rappel d’événement WskReceiveEvent d’une application WSK peut retourner l’un des codes NTSTATUS suivants :

Code de retour	Description
STATUS_SUCCESS	L’application WSK a accepté au moins certaines des données reçues. Si l’application WSK a accepté toutes les données reçues, le sous-système WSK peut appeler à nouveau la fonction de rappel d’événement WskReceiveEvent lorsque de nouvelles données sont reçues sur le socket. Toutefois, si l’application WSK n’a accepté qu’une partie des données reçues, le sous-système WSK n’appellera pas à nouveau la fonction de rappel d’événement WskReceiveEvent tant qu’une fois que l’application WSK a appelé la fonction WskReceive . Une fois que l’application WSK appelle la fonction WskReceive , le sous-système WSK reprend l’appel de la fonction de rappel d’événement WskReceiveEvent avec les données restantes mises en mémoire tampon et lorsque de nouvelles données sont reçues sur le socket. Une application WSK peut appeler la fonction WskReceive avec une mémoire tampon de longueur nulle, ce qui oblige le sous-système WSK à reprendre l’appel de la fonction de rappel d’événements WskReceiveEvent sans appeler WskReceive pour recevoir des données à partir du socket.
STATUS_PENDING	L’application WSK a accepté les données, mais n’a pas récupéré toutes les données contenues dans la liste liée des structures WSK_DATA_INDICATION . L’application WSK conserve la liste liée des structures WSK_DATA_INDICATION jusqu’à ce que toutes les données soient récupérées. Une fois que l’application WSK a récupéré toutes les données, elle appelle la fonction WskRelease pour libérer la liste liée des structures WSK_DATA_INDICATION dans le sous-système WSK. Le sous-système WSK peut appeler à nouveau la fonction de rappel d’événement WskReceiveEvent lorsque de nouvelles données sont reçues sur le socket.
STATUS_DATA_NOT_ACCEPTED	L’application WSK n’a pas accepté les données. Dans ce cas, le sous-système WSK aura la mémoire tampon de transport sous-jacente pour les données si possible ou si le protocole l’exige. Le sous-système WSK n’appellera plus la fonction de rappel d’événement WskReceiveEvent tant que l’application WSK n’appellera pas la fonction WskReceive . Une fois que l’application WSK appelle la fonction WskReceive , le sous-système WSK reprend l’appel de la fonction de rappel d’événement WskReceiveEvent avec les données restantes mises en mémoire tampon et lorsque de nouvelles données sont reçues sur le socket. Une application WSK peut appeler la fonction WskReceive avec une mémoire tampon de longueur nulle, ce qui oblige le sous-système WSK à reprendre l’appel de la fonction de rappel d’événements WskReceiveEvent sans appeler WskReceive pour recevoir des données à partir du socket.

Remarques

Le sous-système WSK appelle la fonction de rappel d’événement WskReceiveEvent d’une application WSK lorsque de nouvelles données sont reçues sur un socket orienté connexion uniquement si la fonction de rappel d’événements était précédemment activée avec l’option de socket SO_WSK_EVENT_CALLBACK . Pour plus d’informations sur l’activation des fonctions de rappel d’événements d’un socket, consultez Activation et désactivation des fonctions de rappel d’événements.

Si la fonction de rappel d’événement WskReceiveEvent d’une application WSK est activée sur un socket orienté connexion et que l’application a également un appel en attente à la fonction WskReceive sur le même socket orienté connexion, l’appel en attente à la fonction WskReceiveEvent est prioritaire sur la fonction de rappel d’événement WskReceiveEvent . Le sous-système WSK appelle la fonction de rappel d’événement WskReceiveEvent de l’application uniquement s’il n’y a pas d’IRP mis en file d’attente des appels en attente vers la fonction WskReceive . Toutefois, une application WSK ne doit pas supposer que le sous-système WSK n’appellera pas la fonction de rappel d’événement WskReceiveEvent de l’application pour un socket orienté connexion qui a un appel en attente à la fonction WskReceive . Il existe des conditions de course où le sous-système WSK peut toujours appeler la fonction de rappel d’événement WskReceiveEvent de l’application WSK pour le socket. La seule façon pour une application WSK de s’assurer que le sous-système WSK n’appelle pas la fonction de rappel d’événements WskReceiveEvent de l’application pour un socket orienté connexion consiste à désactiver la fonction de rappel d’événement WskReceiveEvent de l’application sur le socket.

Notes

Le noyau Winsock (WSK) appelle ce rappel en série, de sorte qu’il n’est pas toujours appelé dès que les données sont reçues.

Le sous-système WSK appelle la fonction de rappel d’événement WskReceiveEvent d’une application WSK à l’adresse IRQL <= DISPATCH_LEVEL.

La fonction de rappel d’événement WskReceiveEvent d’une application WSK ne doit pas attendre l’achèvement d’autres demandes WSK dans le contexte de l’achèvement WSK ou des fonctions de rappel d’événements. Le rappel peut lancer d’autres demandes WSK (en supposant qu’il ne passe pas trop de temps à DISPATCH_LEVEL), mais il ne doit pas attendre leur achèvement même lorsque le rappel est appelé à IRQL = PASSIVE_LEVEL.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Windows
En-tête	wsk.h (inclure Wsk.h)
IRQL	<= DISPATCH_LEVEL