fonction de rappel PFN_WSK_RECEIVE_EVENT (wsk.h)

Article
02/07/2025

La fonction de rappel d’événement WskReceiveEvent avertit une application WSK que les 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.
Elle 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 une 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 propre 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 appelé la fonction de rappel d’événements WskReceiveEvent à IRQL = DISPATCH_LEVEL. Si cet indicateur n’est pas défini, le sous-système WSK peut avoir appelé la fonction de rappel d’événement WskReceiveEvent à n’importe quelle

[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 est 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écrites par la liste liée de structures WSK_DATA_INDICATION.

[in, out] BytesAccepted

Pointeur vers une variable typée 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 un état autre que STATUS_SUCCESS, le sous-système WSK ignore la valeur de cette variable.

Valeur de retour

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

Retourner le code	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’appelle pas la fonction de rappel d’événements WskReceiveEvent jusqu’à ce que l’application WSK appelle 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 toutes les données mises en mémoire tampon restantes et quand 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 entraîne la reprise de l’appel du sous-système WSK fonction de rappel d’événement WskReceiveEvent sans appeler WskReceive pour recevoir des données 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 de structures WSK_DATA_INDICATION. L’application WSK conserve la liste liée des structures de WSK_DATA_INDICATION jusqu’à ce que toutes les données ont été récupérées. Une fois que l’application WSK a récupéré toutes les données qu’elle appelle la fonction WskRelease pour libérer la liste liée des structures WSK_DATA_INDICATION vers 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 le tampon de transport sous-jacent les données si possible ou si nécessaire par le protocole. Le sous-système WSK n’appelle pas la fonction de rappel d’événement WskReceiveEvent jusqu’à ce que l’application WSK appelle 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 toutes les données mises en mémoire tampon restantes et quand 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 entraîne la reprise de l’appel du sous-système WSK fonction de rappel d’événement WskReceiveEvent sans appeler WskReceive pour recevoir des données du socket.

Remarques

Le sous-système WSK appelle la fonction de rappel d’événement WSK WskReceiveEvent lorsque de nouvelles données sont reçues sur un socket orienté connexion uniquement si la fonction de rappel d’événement a été 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 Fonctions d’activation et de 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, ensuite, lorsque les données arrivent, l’appel en attente à la fonction WskReceive est prioritaire sur la fonction de rappel d’événements WskReceiveEvent. Le sous-système WSK appelle la fonction de rappel d’événements WskReceiveEvent de l’application uniquement s’il n’y a pas d’IRPs mis en file d’attente à partir des appels en attente à la fonction WskReceive. Toutefois, une application WSK ne doit pas supposer que le sous-système WSK n’appelle pas le WskReceiveEvent fonction de rappel d’événement pour un socket orienté connexion qui a un appel en attente à la fonction WskReceive. Les conditions de concurrence existent où le sous-système WSK peut toujours appeler la fonction de rappel d’événement WSK WskReceiveEvent 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énement 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.

Note

Winsock Kernel (WSK) appelle ce rappel en série. Il n’est donc 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 WSK WskReceiveEvent à IRQL <= DISPATCH_LEVEL.

La fonction de rappel d’événements WskReceiveEvent d’une application WSK ne doit pas attendre la fin d’autres requêtes WSK dans le contexte des fonctions de rappel d’événements ou de saisie semi-automatique WSK. Le rappel peut lancer d’autres requêtes 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows Vista et versions ultérieures des systèmes d’exploitation Windows.
plateforme cible	Windows
d’en-tête	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL