fonction de rappel PFN_WSK_ACCEPT_EVENT (wsk.h)

Article
08/08/2023

La fonction de rappel d’événement WskAcceptEvent informe une application WSK qu’une connexion entrante sur un socket d’écoute a été acceptée.

Syntaxe

PFN_WSK_ACCEPT_EVENT PfnWskAcceptEvent;

NTSTATUS PfnWskAcceptEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_SOCKET AcceptSocket,
  [out]          PVOID *AcceptSocketContext,
  [out]          const WSK_CLIENT_CONNECTION_DISPATCH **AcceptSocketDispatch
)
{...}

Paramètres

[in, optional] SocketContext

Pointeur vers le contexte de socket pour le socket d’écoute sur lequel la connexion entrante a été acceptée. 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 d’écoute.

[in] Flags

Valeur ULONG qui contient l’indicateur suivant, ou zéro :

WSK_FLAG_AT_DISPATCH_LEVEL

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

[in] LocalAddress

Pointeur vers une mémoire tampon qui contient l’adresse de transport locale à laquelle la connexion entrante est arrivée. La mémoire tampon contient le type de structure SOCKADDR spécifique qui correspond à la famille d’adresses spécifiée par l’application WSK lors de la création du socket d’écoute.

[in] RemoteAddress

Pointeur vers une mémoire tampon qui contient l’adresse de transport distante d’où provient la connexion entrante. La mémoire tampon contient le type de structure SOCKADDR spécifique qui correspond à la famille d’adresses spécifiée par l’application WSK lors de la création du socket d’écoute.

[in, optional] AcceptSocket

Pointeur vers une structure WSK_SOCKET qui est l’objet socket pour le socket accepté. Si ce pointeur a la valeur NULL, le socket d’écoute n’est plus fonctionnel et l’application WSK doit appeler la fonction WskCloseSocket pour fermer le socket d’écoute dès que possible.

[out] AcceptSocketContext

Pointeur vers une variable qui reçoit un pointeur vers un contexte fourni par l’application WSK pour le socket accepté. Le sous-système WSK transmet ce pointeur aux fonctions de rappel d’événement du socket accepté. Les informations de contexte sont opaques pour le sous-système WSK et doivent être stockées dans la mémoire non paginée. Si l’application WSK n’active aucune fonction de rappel d’événement sur le socket accepté, l’application doit définir la variable vers laquelle pointe le paramètre AcceptSocketContext sur NULL.

[out] AcceptSocketDispatch

Pointeur vers une variable qui reçoit un pointeur vers une constante WSK_CLIENT_CONNECTION_DISPATCH structure. Cette structure est une table de répartition qui contient des pointeurs vers les fonctions de rappel d’événement pour le socket accepté. Si l’application WSK n’active pas toutes les fonctions de rappel d’événement pour le socket accepté, l’application doit définir les pointeurs de la table de distribution sur NULL pour les fonctions de rappel d’événements qu’elle n’active pas. Si l’application WSK n’active aucune fonction de rappel d’événement sur le socket accepté, elle doit définir la variable vers laquelle pointe le paramètre AcceptSocketDispatch sur NULL.

Valeur retournée

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

Code de retour	Description
STATUS_SUCCESS	L’application WSK a accepté la connexion entrante.
STATUS_REQUEST_NOT_ACCEPTED	L’application WSK a rejeté la connexion entrante. Si cette valeur est retournée, le sous-système WSK ferme le socket accepté pour le compte de l’application WSK.

Remarques

Le sous-système WSK appelle la fonction de rappel d’événement WskAcceptEvent d’une application WSK lorsqu’une connexion entrante est acceptée sur le socket d’écoute uniquement si la fonction de rappel d’événement a été précédemment activée avec l’option 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 WskAcceptEvent d’une application WSK est activée sur un socket d’écoute et que l’application a un appel en attente à la fonction WskAccept sur le même socket d’écoute, alors, lorsqu’une connexion entrante arrive, l’appel en attente à WskAcceptcept prend la priorité sur la fonction de rappel d’événement WskAcceptEvent . Le sous-système WSK appelle la fonction de rappel d’événement WskAcceptEvent de l’application uniquement s’il n’y a pas d’irps mis en file d’attente des appels en attente vers la fonction WskAccept . Toutefois, une application WSK ne doit pas supposer que le sous-système WSK n’appellera pas la fonction de rappel d’événement WskAcceptEvent de l’application pour un socket d’écoute qui a un appel en attente à la fonction WskAccept . Il existe des conditions de concurrence où le sous-système WSK peut toujours appeler la fonction de rappel d’événement WskAcceptEvent 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 WskAcceptEvent de l’application pour un socket d’écoute consiste à désactiver la fonction de rappel d’événement WskAcceptEvent de l’application sur le socket.

Lorsque le sous-système WSK appelle la fonction de rappel d’événement WskAcceptEvent d’une application WSK, toutes les fonctions de rappel d’événement sur le socket accepté sont désactivées par défaut. Si une application WSK active l’une des fonctions de rappel d’événement de socket orientée connexion sur un socket d’écoute, ces fonctions de rappel d’événement sont activées par défaut sur tous les sockets orientés connexion acceptés sur ce socket d’écoute. Pour plus d’informations sur l’activation de l’une des fonctions de rappel d’événements du socket accepté, consultez Activation et désactivation des fonctions de rappel d’événements.

Les structures SOCKADDR pointées par les paramètres LocalAddress et RemoteAddress sont valides uniquement pendant la durée de l’appel à la fonction de rappel d’événement WskAcceptEvent . Si une application WSK a besoin de ces adresses de transport ultérieurement, elle peut copier le contenu de ces structures dans ses propres structures SOCKADDR avant de retourner à partir de la fonction de rappel d’événement WskAcceptEvent , ou appeler ultérieurement les fonctions WskGetLocalAddress et WskGetRemoteAddress sur le socket accepté.

Le sous-système WSK alloue la mémoire pour la structure d’objet socket ( WSK_SOCKET) pour la connexion acceptée pour le compte de l’application WSK. Le sous-système WSK libère cette mémoire lorsque le socket est fermé.

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

La fonction de rappel d’événement WskAcceptEvent 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