PFN_WSK_RECEIVE_FROM fonction de rappel (wsk.h)

Article
03/01/2024

La fonction WskReceiveFrom reçoit un datagramme et toutes les informations de contrôle associées à partir d’une adresse de transport distante.

Syntaxe

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

Paramètres

[in] Socket

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

[in] Buffer

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

Flags

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

[out, optional] RemoteAddress

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit l’adresse de transport distante d’où provient le datagramme reçu. 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 de datagramme. Ce pointeur est facultatif et peut avoir la valeur NULL.

[in, out] ControlLength

Pointeur vers un ULONG qui spécifie la taille de la mémoire tampon vers laquelle pointe le paramètre ControlInfo . Une fois l’opération de réception terminée, la variable reçoit la taille des informations de contrôle associées au datagramme reçu. Si la valeur retournée est zéro, aucune information de contrôle n’est présente pour le datagramme. Ce pointeur est facultatif et peut avoir la valeur NULL. Si ce paramètre a la valeur NULL, le paramètre ControlInfo est ignoré.

[out, optional] ControlInfo

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit les informations de contrôle associées au datagramme reçu. Les données d’informations de contrôle associées à un datagramme sont constituées d’un ou plusieurs objets de données de contrôle, chacun commençant par une structure CMSGHDR . Si aucune information de contrôle n’est présente pour le datagramme reçu, le contenu de la mémoire tampon n’est pas défini. Ce pointeur est facultatif et peut avoir la valeur NULL. Si le paramètre ControlInfoLength a la valeur NULL, le paramètre ControlInfo doit avoir la valeur NULL.

[out, optional] ControlFlags

Pointeur vers une variable de type ULONG qui reçoit le or au niveau du bit d’une combinaison des indicateurs suivants :

MSG_BCAST

Le datagramme a été reçu en tant que diffusion de couche de liaison ou avec une adresse de transport de destination qui est une adresse de diffusion.

MSG_MCAST

Le datagramme a été reçu avec une adresse de transport de destination qui est une adresse de multidiffusion.

MSG_TRUNC

Le datagramme a été tronqué, car la taille du datagramme était supérieure à la taille de la mémoire tampon spécifiée par le paramètre Buffer .

MSG_CTRUNC

Les données d’informations de contrôle ont été tronquées, car le nombre d’octets d’informations de contrôle était supérieur à la taille de la mémoire tampon spécifiée par le paramètre ControlInfo .

Ce paramètre est facultatif et peut être NULL.

[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

WskReceiveFrom 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 le datagramme du socket immédiatement. Le sous-système WSK termine l’IRP une fois qu’il a reçu le datagramme 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.
Autres codes status	Une erreur est survenue. L’IRP sera terminé avec l’échec status.

Remarques

Si l’application WSK a défini une adresse de transport distante fixe pour le socket de datagramme, les datagrammes reçus de toute autre adresse de transport distante sont ignorés par le sous-système WSK. Pour plus d’informations sur la définition de l’adresse de transport distante pour un socket de datagramme, consultez SIO_WSK_SET_REMOTE_ADDRESS.

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 WskReceiveFromEvent . 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’IRP mis en file d’attente à partir d’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 course 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.

Si la fonction WskReceiveFrom retourne STATUS_PENDING, la chaîne MDL décrite dans la structure de WSK_BUF pointée par le paramètre Buffer doit rester verrouillée dans la mémoire jusqu’à ce que l’IRP soit terminé. En outre, la variable vers laquelle pointe le paramètre ControlInfoLength , la mémoire tampon vers laquelle pointe le paramètre ControlInfo et la variable vers laquelle pointe le paramètre ControlFlags doivent également rester valides jusqu’à ce que l’IRP soit terminé. Si l’application WSK a alloué ces mémoires tampons ou variables à 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é. Si l’application WSK a alloué ces mémoires tampons ou variables sur la pile, elle ne peut pas retourner à partir de la fonction qui appelle la fonction WskReceiveFrom tant qu’une fois l’IRP 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