PFN_WSK_RECEIVE_FROM_EVENT fonction de rappel (wsk.h)

Article
02/27/2024

La fonction de rappel d’événement WskReceiveFromEvent avertit une application WSK qu’un ou plusieurs datagrammes ont été reçus sur un socket de datagramme.

Syntaxe

PFN_WSK_RECEIVE_FROM_EVENT PfnWskReceiveFromEvent;

NTSTATUS PfnWskReceiveFromEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATAGRAM_INDICATION DataIndication
)
{...}

Paramètres

[in, optional] SocketContext

Pointeur vers le contexte de socket pour le socket de datagramme qui a reçu les datagrammes. L’application WSK a fourni ce pointeur vers le sous-système WSK lorsqu’elle a appelé la fonction WskSocket pour créer le socket de datagramme.

[in] Flags

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

MSG_BCAST

Les datagrammes ont été reçus en tant que diffusion de la couche liaison ou avec une adresse de transport de destination qui est une adresse de diffusion.

MSG_MCAST

Les datagrammes ont été reçus avec une adresse de transport de destination qui est une adresse de multidiffusion.

WSK_FLAG_AT_DISPATCH_LEVEL

Le sous-système WSK a appelé la fonction de rappel d’événement WskReceiveFromEvent à 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 WskReceiveFromEvent à n’importe quel point IRQL <= DISPATCH_LEVEL.

[in, optional] DataIndication

Pointeur vers une liste liée de structures WSK_DATAGRAM_INDICATION qui décrivent les datagrammes reçus. 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.

Valeur retournée

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

Code de retour	Description
STATUS_SUCCESS	L’application WSK a accepté les datagrammes et récupéré tous les datagrammes de la liste liée de WSK_DATAGRAM_INDICATION structures. Le sous-système WSK peut appeler à nouveau la fonction de rappel d’événement WskReceiveFromEvent lorsque de nouveaux datagrammes sont reçus sur le socket.
STATUS_PENDING	L’application WSK a accepté les datagrammes, mais n’a pas récupéré tous les datagrammes de la liste liée de WSK_DATAGRAM_INDICATION structures. L’application WSK conserve la liste liée des structures WSK_DATAGRAM_INDICATION jusqu’à ce que tous les datagrammes aient été récupérés. Une fois que l’application WSK a récupéré tous les datagrammes, elle appelle la fonction WskRelease pour libérer la liste liée des structures WSK_DATAGRAM_INDICATION dans le sous-système WSK. Le sous-système WSK peut appeler à nouveau la fonction de rappel d’événement WskReceiveFromEvent lorsque de nouveaux datagrammes sont reçus sur le socket.
STATUS_DATA_NOT_ACCEPTED	L’application WSK n’a pas accepté les datagrammes. Si une application WSK retourne ce code status, le sous-système WSK répond différemment selon la façon dont l’application WSK a activé la fonction de rappel d’événement WskReceiveFromEvent. Si l’application WSK a activé la fonction de rappel d’événement WskReceiveFromEvent à l’aide de l’option de socket SO_WSK_EVENT_CALLBACK , le sous-système WSK disposera de la mémoire tampon de transport sous-jacente des datagrammes si possible ou si le protocole l’exige autrement. Le sous-système WSK désactive la fonction de rappel d’événement WskReceiveFromEvent et n’appelle pas à nouveau la fonction de rappel d’événement WskReceiveFromEvent tant que l’application WSK n’active pas cette fonction de rappel d’événement avec l’option de socket SO_WSK_EVENT_CALLBACK. Une fois que l’application WSK a réactivé la fonction de rappel d’événement WskReceiveFromEvent , le sous-système WSK reprend l’appel de la fonction de rappel d’événement WskReceiveFromEvent avec tous les datagrammes mis en mémoire tampon restants et lorsque de nouveaux datagrammes sont reçus sur le socket. Si l’application WSK a activé la fonction de rappel d’événement WskReceiveFromEvent à l’aide de WSK_SET_STATIC_EVENT_CALLBACKS opération de contrôle client, le sous-système WSK ne désactive pas la fonction de rappel d’événement WskReceiveFromEvent . Le sous-système WSK continue d’appeler la fonction de rappel d’événement WskReceiveFromEvent lorsque de nouveaux datagrammes sont reçus sur le socket.

Remarques

Le sous-système WSK appelle la fonction de rappel d’événement WskReceiveFromEvent d’une application WSK lorsque de nouveaux datagrammes sont reçus sur un socket de datagramme 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 Activation et désactivation des fonctions de rappel d’événements.

Si la fonction de rappel d’événement WskReceiveFromEvent d’une application WSK est activée sur un socket de datagramme et que l’application a également un appel en attente à la fonction WskReceiveFrom sur le même socket de datagramme, l’appel en attente à la fonction WskReceiveFrom est prioritaire sur la fonction de rappel d’événement WskReceiveFrom. Le sous-système WSK appelle la fonction de rappel d’événement WskReceiveFromEvent de l’application uniquement s’il n’y a pas d’irps mis en file d’attente à partir des appels en attente vers la fonction WskReceiveFrom . Toutefois, une application WSK ne doit pas supposer que le sous-système WSK n’appellera pas la fonction de rappel d’événement WskReceiveFromEvent de l’application pour un socket de datagramme qui a un appel en attente à la fonction WskReceiveFrom . Il existe des conditions de concurrence où le sous-système WSK peut toujours appeler la fonction de rappel d’événement WskReceiveFromEvent 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’appellera pas la fonction de rappel d’événement WskReceiveFromEvent de l’application sur un socket de datagramme consiste à désactiver la fonction de rappel d’événement WskReceiveFromEvent de l’application sur le socket.

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

La fonction de rappel d’événement WskReceiveFromEvent d’une application WSK ne doit pas attendre l’achèvement d’autres requêtes WSK dans le contexte de l’achèvement WSK ou des fonctions de rappel d’événements. 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.

Configuration requise

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