PFN_WSK_ACCEPT fonction de rappel (wsk.h)

Article
08/08/2023

La fonction WskAccept accepte une connexion entrante sur un socket d’écoute.

Syntaxe

PFN_WSK_ACCEPT PfnWskAccept;

NTSTATUS PfnWskAccept(
  [in]            PWSK_SOCKET ListenSocket,
                  ULONG Flags,
  [in, optional]  PVOID AcceptSocketContext,
  [in, optional]  const WSK_CLIENT_CONNECTION_DISPATCH *AcceptSocketDispatch,
  [out, optional] PSOCKADDR LocalAddress,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PIRP Irp
)
{...}

Paramètres

[in] ListenSocket

Pointeur vers une structure de WSK_SOCKET qui spécifie l’objet socket pour le socket d’écoute ou de flux qui est vérifié pour une connexion entrante.

Flags

Ce paramètre est réservé à une utilisation système. Une application WSK doit définir ce paramètre sur zéro.

[in, optional] AcceptSocketContext

Pointeur vers un contexte fourni par l’appelant 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. Les informations de contexte 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é, elle doit définir ce pointeur sur NULL.

[in, optional] AcceptSocketDispatch

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é, elle doit définir les pointeurs de la table dispatch 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 ce pointeur sur NULL.

[out, optional] LocalAddress

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit l’adresse de transport locale à laquelle la connexion entrante est arrivée. La mémoire tampon doit se trouver dans la mémoire non paginée. La mémoire tampon doit également être suffisamment grande pour contenir 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. Ce pointeur est facultatif et peut être NULL.

[out, optional] RemoteAddress

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit l’adresse de transport distante d’où provient la connexion entrante. La mémoire tampon doit se trouver dans la mémoire non paginée. La mémoire tampon doit également être suffisamment grande pour contenir 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. Ce pointeur est facultatif et peut être NULL.

[in, out] Irp

Pointeur vers un IRP alloué à l’appelant que le sous-système WSK utilise pour effectuer l’opération d’acceptation de façon asynchrone. Pour plus d’informations sur l’utilisation des runtimes d’intégration avec les fonctions WSK, consultez Utilisation des runtimes d’intégration avec les fonctions du noyau Winsock.

Valeur retournée

WskAccept retourne l’un des codes NTSTATUS suivants :

Code de retour	Description
STATUS_SUCCESS	Une connexion entrante a été acceptée avec succès. L’IRP sera complété avec succès status.
STATUS_PENDING	L’IRP a été mis en file d’attente par le sous-système WSK, qui attend une connexion entrante sur le socket d’écoute.
STATUS_FILE_FORCED_CLOSED	Le socket n’est plus fonctionnel. L’IRP sera terminé avec l’échec status. L’application WSK doit appeler la fonction WskCloseSocket pour fermer le socket dès que possible.
Autres codes status	Une erreur est survenue. L’IRP sera terminé avec l’échec status.

Remarques

Une application WSK peut appeler la fonction WskAccept sur un socket d’écoute ou sur un socket de flux qu’elle a précédemment lié à une adresse de transport locale en appelant la fonction WskBind .

Le comportement de la fonction WskAccept dépend de l’acceptation ou non d’une connexion entrante sur le socket d’écoute :

Si une connexion entrante est déjà arrivée sur le socket d’écoute et attend d’être acceptée, la fonction WskAccept retourne STATUS_SUCCESS. Dans ce cas, l’IRP est effectué avec succès status et le champ IoStatus.Information de l’IRP contient un pointeur vers l’objet socket pour le socket accepté.
Si une connexion entrante n’attend pas d’être acceptée sur le socket d’écoute, WskAccept retourne STATUS_PENDING et le sous-système WSK met en file d’attente l’IRP jusqu’à ce qu’une connexion entrante soit reçue. Lorsqu’une connexion entrante est reçue, le sous-système WSK termine l’IRP de manière asynchrone avec succès status. Dans ce cas, le champ IoStatus.Information de l’IRP contient un pointeur vers l’objet socket pour le socket accepté.

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 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 la fonction WskAccept accepte correctement une connexion entrante, toutes les fonctions de rappel d’événements sur le socket accepté sont désactivées par défaut. 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.

Si une application WSK spécifie un pointeur non NULL dans le paramètre LocalAddress , dans le paramètre RemoteAddress ou dans les deux paramètres, et si WskAccept retourne STATUS_PENDING, les mémoires tampons pointées par ces paramètres doivent rester valides jusqu’à ce que l’IRP soit terminée. Si l’application WSK a alloué les mémoires tampons avec l’une des fonctions ExAllocateXxx , elle ne peut pas libérer la mémoire avec la fonction ExFreeXxx correspondante tant qu’une fois l’IRP terminée. Si l’application WSK a alloué les mémoires tampons sur la pile, elle ne peut pas retourner à partir de la fonction qui appelle la fonction WskAccept tant qu’une fois l’IRP terminée.

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é.

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	Universal
En-tête	wsk.h (inclure Wsk.h)
IRQL	<= DISPATCH_LEVEL