PFN_WSK_RECEIVE fonction de rappel (wsk.h)

Article
02/27/2024

La fonction WskReceive reçoit des données via un socket orienté connexion ou flux à partir d’une adresse de transport distante.

Syntaxe

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

Paramètres

[in] Socket

Pointeur vers une structure WSK_SOCKET qui spécifie l’objet socket pour le socket à partir duquel recevoir les données.

[in] Buffer

Pointeur vers une structure WSK_BUF initialisée qui décrit la mémoire tampon de données qui reçoit les données du socket.

[in] Flags

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

WSK_FLAG_WAITALL

Attendez que la mémoire tampon de données soit complètement remplie. Si cet indicateur est spécifié, l’IRP spécifié dans le paramètre Irp n’est pas terminé tant que l’un des événements suivants ne se produit pas :

La mémoire tampon de données décrite par la structure WSK_BUF pointée par le paramètre Buffer est entièrement remplie.
La connexion est correctement déconnectée par l’expéditeur distant.
La connexion est interrompue par l’application WSK ou par l’expéditeur distant.
L’IRP spécifié est annulé.

Cet indicateur est pris en charge par le protocole de transport TCP/IP Microsoft. Cet indicateur peut ne pas être pris en charge par d’autres protocoles de transport.

WSK_FLAG_DRAIN

Attendez que le socket soit déconnecté, en ignorant toutes les données reçues sur le socket. Si cet indicateur est spécifié, l’IRP spécifié n’est pas terminé tant que l’un des événements suivants ne se produit pas :

La connexion est correctement déconnectée par l’expéditeur distant.
La connexion est interrompue par l’application WSK ou par l’expéditeur distant.
L’IRP spécifié est annulé.

Toutes les données reçues sont ignorées par le sous-système WSK. Aucune donnée reçue n’est copiée dans la mémoire tampon de données. Le paramètre Buffer est toujours requis lorsque cet indicateur est spécifié, mais la longueur de la mémoire tampon décrite par la structure WSK_BUF doit être égale à zéro.

Cet indicateur est pris en charge par le protocole de transport TCP/IP Microsoft. Cet indicateur peut ne pas être pris en charge par d’autres protocoles de transport.

Les indicateurs WSK_FLAG_WAITALL et WSK_FLAG_DRAIN s’excluent mutuellement. Une application WSK ne doit pas spécifier ces deux indicateurs en même temps.

[in, out] Irp

Pointeur vers un IRP alloué à l’appelant que le sous-système WSK utilise pour terminer l’opération de réception de manière asynchrone. Pour plus d’informations sur l’utilisation des irps avec des fonctions WSK, consultez Utilisation des irps avec les fonctions du noyau Winsock.

Valeur retournée

WskReceive retourne l’un des codes NTSTATUS suivants :

Code de retour	Description
STATUS_SUCCESS	Les données ont été reçues avec succès à partir du socket. Le IRP sera terminé avec succès status. Le champ IoStatus.Information de l’IRP contient le nombre d’octets reçus.
STATUS_PENDING	Le sous-système WSK n’a pas pu recevoir les données du socket immédiatement. Le sous-système WSK termine l’IRP une fois qu’il a reçu les données du socket. Le status de l’opération de réception sera retourné dans le champ IoStatus.Status de l’IRP. Si l’opération réussit, le champ IoStatus.Information de l’IRP contiendra le nombre d’octets reçus.
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.
STATUS_NOT_SUPPORTED	Un indicateur spécifié n’est pas pris en charge par le transport réseau sous-jacent.
Autres codes status	Une erreur est survenue. L’IRP sera terminé avec l’échec status.

Remarques

Une application WSK peut appeler la fonction WskReceive uniquement sur un socket orienté connexion ou de flux qui a été précédemment connecté à une adresse de transport distante. Un socket orienté connexion est connecté à une adresse de transport distante par l’une des méthodes suivantes :

L’application WSK connecte le socket en appelant la fonction WskConnect .
L’application WSK crée, lie et connecte le socket en appelant la fonction WskSocketConnect .
Le sous-système WSK connecte le socket lorsque l’application WSK accepte une demande de connexion entrante sur un socket d’écoute.

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.

Une application WSK peut appeler la fonction WskReceive avec une longueur nulle spécifiée dans le membre Length de la structure WSK_BUF vers laquelle pointe le paramètre Buffer . La spécification d’une longueur nulle dans ce membre est utile dans les situations suivantes :

Lors de la réactivation de la fonction de rappel d’événement WskReceiveEvent pour un socket après que la fonction de rappel d’événement WskReceiveEvent a précédemment retournée STATUS_DATA_NOT_ACCEPTED
Lors de la spécification de l’indicateur WSK_FLAG_DRAIN pour ignorer toutes les données supplémentaires reçues sur le socket

Si la fonction WskReceive retourne STATUS_PENDING, la chaîne MDL décrite dans la structure WSK_BUF pointée par le paramètre Buffer doit rester verrouillée dans la mémoire jusqu’à ce que l’IRP soit terminée.

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