PFN_WSK_RECEIVE fonction de rappel (wsk.h)

Article
02/07/2025

La fonction WskReceive reçoit des données via un socket orienté connexion ou de 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 de 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 une or au niveau du bit d’une combinaison des indicateurs suivants :

WSK_FLAG_WAITALL

Attendez que la mémoire tampon de données soit entièrement 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 de tampon est entièrement remplie.
La connexion est correctement déconnectée par l’expéditeur distant.
La connexion est abandonnée 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 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 abandonnée 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 tampon est toujours nécessaire 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é par 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 d’IRPs avec des fonctions WSK, consultez Utilisation d’IRPs avec winsock Kernel Functions.

Valeur de retour

WskReceive retourne l’un des codes NTSTATUS suivants :

Retourner le code	Description
STATUS_SUCCESS	Les données ont été correctement reçues du socket. L’IRP sera terminé avec l’état de réussite. Le champ IoStatus.Information du protocole 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 après avoir reçu les données du socket. L’état de l’opération de réception est retourné dans le champ IoStatus.Status de l’IRP. Si l’opération réussit, le champ IoStatus.Information du protocole IRP contient le nombre d’octets reçus.
STATUS_FILE_FORCED_CLOSED	Le socket n’est plus fonctionnel. L’IRP est terminé avec l’état d’échec. 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 d’état	Une erreur s’est produite. L’IRP est terminé avec l’état d’échec.

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

Une application WSK peut appeler la fonction WskReceive avec une longueur nulle spécifiée dans le membre Length de la structure WSK_BUF pointée par 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 la fonction de rappel d’événement WskReceiveEvent précédemment retournée STATUS_DATA_NOT_ACCEPTED
Lors de la spécification de l’indicateur WSK_FLAG_DRAIN pour ignorer 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 en mémoire tant que l’IRP n’est pas terminé.

Exigences

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