PFN_WSK_RECEIVE_FROM fonction de rappel (wsk.h)
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 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 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 par l’appelant qui reçoit l’adresse de transport distante à partir de laquelle le datagramme reçu provient. La mémoire tampon doit se trouver en 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 être NULL.
[in, out] ControlLength
Pointeur vers un ULONG qui spécifie la taille de la mémoire tampon pointée par 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 égale à zéro, aucune information de contrôle n’est présente pour le datagramme. Ce pointeur est facultatif et peut être NULL. Si ce paramètre est null, le paramètre ControlInfo est ignoré.
[out, optional] ControlInfo
Pointeur vers une mémoire tampon allouée par 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. S’il n’existe aucune information de contrôle pour le datagramme reçu, le contenu de la mémoire tampon n’est pas défini. Ce pointeur est facultatif et peut être NULL. Si le paramètre ControlInfoLength est NULL, le paramètre ControlInfo doit être NULL.
[out, optional] ControlFlags
Pointeur vers une variable typée ULONG qui reçoit l’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 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é 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
WskReceiveFrom retourne l’un des codes NTSTATUS suivants :
| Retourner le code | Description |
|---|---|
|
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. |
|
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 le datagramme reçu 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. |
|
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. |
|
Une erreur s’est produite. L’IRP est terminé avec l’état d’échec. |
Remarques
Si l’application WSK a défini une adresse de transport distante fixe pour le socket de datagram, les datagrammes reçus d’une 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 datagram, ensuite, lorsque les datagrammes arrivent, 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énements WskReceiveFromEvent uniquement s’il n’y a pas d’IRPs mis en file d’attente à partir des appels en attente à la fonction WskReceiveFrom. Toutefois, une application WSK ne doit pas supposer que le sous-système WSK n’appelle pas la fonction de rappel d’événement WskReceiveFromEvent WskReceiveFromEvent pour un socket de datagramme qui a un appel en attente à la fonction WskReceiveFrom. Les conditions de concurrence existent dans lesquelles le sous-système WSK peut toujours appeler la fonction de rappel d’événement WSK WskReceiveFromEvent 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 WskReceiveFromEvent de l' application sur un socket de datagram 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 WSK_BUF pointée par le paramètre Buffer doit rester verrouillée en mémoire jusqu’à ce que l’IRP soit terminé. En outre, la variable pointée par le paramètre ControlInfoLength, la mémoire tampon pointée par le paramètre ControlInfo et la variable pointée par le paramètre ControlFlags doit également rester valide jusqu’à ce que l’IRP soit terminé. Si l’application WSK a alloué ces mémoires tampons ou variables avec l’une des fonctions ExAllocateXxx, elle ne peut pas libérer la mémoire avec la fonction ExFreeXxx jusqu’à la fin de l’IRP. 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 jusqu’à la fin de l’IRP.
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 |