LPFN_WSARECVMSG fonction de rappel (mswsock.h)

Article
02/29/2024

LPFN_WSARECVMSG est un type de pointeur de fonction. Vous implémentez une fonction de rappel WSARecvMsg correspondante dans votre application. Le système utilise votre fonction de rappel pour vous transmettre des données en mémoire, ou des données de fichier, via un socket connecté.

Votre fonction de rappel WSARecvMsg reçoit des données/des informations de contrôle auxiliaires avec un message, à partir de sockets connectés et non connectés.

Notes

Cette fonction est une extension spécifique à Microsoft de la spécification des sockets Windows.

Syntaxe

LPFN_WSARECVMSG LpfnWsarecvmsg;

INT LpfnWsarecvmsg(
  SOCKET s,
  LPWSAMSG lpMsg,
  LPDWORD lpdwNumberOfBytesRecvd,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
)
{...}

Paramètres

s

Type : _In_ SOCKET

Descripteur qui identifie le socket.

lpMsg

Type : _inout_ LPWSAMSG

Pointeur vers une structure WSAMSG basée sur la spécification Posix.1g pour la structure msghdr.

lpdwNumberOfBytesRecvd

Type : _Out_opt_ LPDWORD

Pointeur vers un DWORD contenant le nombre d’octets reçus par cet appel si l’opération WSARecvMsg se termine immédiatement.

Pour éviter les résultats potentiellement erronés, passez la valeur NULL pour ce paramètre si le paramètre lpOverlapped n’a pas la valeur NULL . Ce paramètre ne peut être NULL que si le paramètre lpOverlapped n’est pas NULL.

lpOverlapped

Type : _Inout_opt_ LPWSAOVERLAPPED

Pointeur vers une structure WSAOVERLAPPED . Ignoré pour les structures qui ne se chevauchent pas.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération de réception terminée. Ignoré pour les structures qui ne se chevauchent pas.

Valeur retournée

Si aucune erreur ne se produit et que l’opération de réception est terminée immédiatement, WSARecvMsg retourne zéro. Dans ce cas, la routine d’achèvement a déjà été planifiée pour être appelée une fois que le thread appelant est à l’état alertable. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError. Le code d’erreur WSA_IO_PENDING indique que l’opération qui se chevauche a été lancée avec succès et que l’achèvement sera indiqué ultérieurement.

Tout autre code d’erreur indique que l’opération n’a pas été lancée avec succès et qu’aucune indication d’achèvement ne se produit si une opération se chevauche a été demandée.

Code d'erreur	Signification
WSAECONNRESET	Pour un socket de datagramme UDP, cette erreur indique qu’une opération d’envoi précédente a entraîné un message ICMP « Port inaccessible ».
WSAEFAULT	Le paramètre lpBuffers, lpFlags, lpFrom, lpNumberOfBytesRecvd, lpFromlen, lpOverlapped ou lpCompletionRoutine n’est pas entièrement contenu dans une partie valide de l’espace d’adressage utilisateur : la mémoire tampon lpFrom était trop petite pour prendre en charge l’adresse homologue. Cette erreur est également retournée si un membre de nom de la structure WSAMSG pointée par le paramètre lpMsg était un pointeur NULL et si le membre namelen de la structure WSAMSG n’a pas été défini sur zéro. Cette erreur est également retournée si un membre Control.buf de la structure WSAMSG pointée par le paramètre lpMsg était un pointeur NULL et si le membre Control.len de la structure WSAMSG n’a pas été défini sur zéro.
WSAEINPROGRESS	Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEINTR	Un appel bloquant Windows Socket 1.1 a été annulé via WSACancelBlockingCall.
WSAEINVAL	Le socket n’a pas été lié (avec liaison, par exemple).
WSAEMSGSIZE	Le message était trop volumineux pour tenir dans la mémoire tampon spécifiée et (pour les protocoles non fiables uniquement) toute partie de fin du message qui ne correspondait pas à la mémoire tampon a été ignorée.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENETRESET	Pour un socket datagramme, cette erreur indique que la durée de vie (TTL, Time to Live) a expiré.
WSAENOTCONN	Le socket n’est pas connecté (sockets orientés connexion uniquement).
WSAETIMEDOUT	Le socket a expiré. Cette erreur est retournée si le socket avait un délai d’attente spécifié à l’aide de l’option de socket SO_RCVTIMEO et si le délai d’attente a été dépassé.
WSAEOPNOTSUPP	L’opération de socket n’est pas prise en charge. Cette erreur est retournée si le membre dwFlags de la structure WSAMSG pointée vers par le paramètre lpMsg inclut l’indicateur de contrôle MSG_PEEK sur un socket autre que le datagramme.
WSAEWOULDBLOCK	Windows NT : Sockets qui se chevauchent : il y a trop de demandes d’E/S qui se chevauchent. Sockets non superposés : le socket est marqué comme non bloquant et l’opération de réception ne peut pas être effectuée immédiatement.
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSA_IO_PENDING	Une opération qui se chevauche a été lancée avec succès et l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	L’opération qui se chevauche a été annulée en raison de la fermeture du socket.

Remarques

La fonction WSARecvMsg peut être utilisée à la place des fonctions WSARecv et WSARecvFrom pour recevoir des données et des informations de contrôle facultatives à partir de sockets connectés et non connectés. La fonction WSARecvMsg ne peut être utilisée qu’avec des datagrammes et des sockets bruts. Le descripteur de socket dans le paramètre s doit être ouvert avec le type de socket défini sur SOCK_DGRAM ou SOCK_RAW.

Note Le pointeur de fonction pour la fonction WSARecvMsg doit être obtenu au moment de l’exécution en appelant la fonction WSAIoctl avec l’opcode SIO_GET_EXTENSION_FUNCTION_POINTER spécifié. La mémoire tampon d’entrée passée à la fonction WSAIoctl doit contenir WSAID_WSARECVMSG, un identificateur global unique (GUID) dont la valeur identifie la fonction d’extension WSARecvMsg . En cas de réussite, la sortie retournée par la fonction WSAIoctl contient un pointeur vers la fonction WSARecvMsg . Le GUID WSAID_WSARECVMSG est défini dans le fichier d’en-tête Mswsock.h .

Le membre dwFlags de la structure WSAMSG pointée vers le paramètre lpMsg ne peut contenir que l’indicateur de contrôle MSG_PEEK en entrée.

Les sockets qui se chevauchent sont créés avec un appel de fonction WSASocket dont l’indicateur WSA_FLAG_OVERLAPPED est défini. Pour les sockets qui se chevauchent, la réception d’informations utilise des E/S qui se chevauchent, sauf si les paramètres lpOverlapped et lpCompletionRoutine sont NULL. Le socket est traité comme un socket non chevauchement lorsque les paramètres lpOverlapped et lpCompletionRoutine sont NULL.

Une indication d’achèvement se produit avec des sockets qui se chevauchent. Une fois que la mémoire tampon ou les mémoires tampons ont été consommées par le transport, une routine d’achèvement est déclenchée ou un objet d’événement est défini. Si l’opération ne se termine pas immédiatement, l’achèvement final status est récupéré via la routine d’achèvement ou en appelant la fonction WSAGetOverlappedResult.

Pour les sockets qui se chevauchent, WSARecvMsg est utilisé pour publier une ou plusieurs mémoires tampons dans lesquelles les données entrantes seront placées à mesure qu’elles seront disponibles, après quoi l’indication d’achèvement spécifiée par l’application (appel de la routine d’achèvement ou du paramètre d’un objet d’événement) se produit. Si l’opération ne se termine pas immédiatement, la status d’achèvement finale est récupérée via la routine d’achèvement ou la fonction WSAGetOverlappedResult.

Pour les sockets non superposés, la sémantique de blocage est identique à celle de la fonction recv standard et les paramètres lpOverlapped et lpCompletionRoutine sont ignorés. Toutes les données qui ont déjà été reçues et mises en mémoire tampon par le transport seront copiées dans les mémoires tampons utilisateur spécifiées. Dans le cas d’un socket bloquant sans qu’aucune donnée n’ait été reçue et mise en mémoire tampon par le transport, l’appel est bloqué jusqu’à ce que les données soient reçues. Windows Sockets 2 ne définit aucun mécanisme de délai de blocage standard pour cette fonction. Pour les protocoles agissant comme des protocoles de flux d’octets, la pile tente de retourner autant de données que possible sous réserve de l’espace tampon disponible et de la quantité de données reçues disponibles. Toutefois, la réception d’un seul octet est suffisante pour débloquer l’appelant. Il n’existe aucune garantie que plusieurs octets seront retournés. Pour les protocoles orientés message, un message complet est nécessaire pour débloquer l’appelant.

NoteL’option socket SO_RCVTIMEO s’applique uniquement aux sockets bloquants.

Les mémoires tampons sont remplies dans l’ordre dans lequel elles apparaissent dans le tableau pointé par le membre lpBuffers de la structure WSAMSG pointée vers le paramètre lpMsg , et les mémoires tampons sont emballées afin qu’aucun trou ne soit créé.

Si cette fonction se chevauche, il incombe au fournisseur de services Winsock de capturer cette structure WSABUF avant de revenir de cet appel. Cela permet aux applications de créer des tableaux WSABUF basés sur une pile pointés par le membre lpBuffers de la structure WSAMSG pointée vers le paramètre lpMsg .

Pour les sockets orientés message (type de socket SOCK_DGRAM ou SOCK_RAW), un message entrant est placé dans les mémoires tampons jusqu’à la taille totale des mémoires tampons, et l’indication d’achèvement se produit pour les sockets qui se chevauchent. Si le message est plus grand que les mémoires tampons, les mémoires tampons sont remplies avec la première partie du message et les données excédentaires sont perdues, et WSARecvMsg génère l’erreur WSAEMSGSIZE.

Lorsque l’option de socket IP_PKTINFO est activée sur un socket IPv4 de type SOCK_DGRAM ou SOCK_RAW, la fonction WSARecvMsg retourne des informations de paquet dans la structure WSAMSG pointée vers le paramètre lpMsg . L’un des objets de données de contrôle dans la structure WSAMSG retournée contient une structure in_pktinfo utilisée pour stocker les informations d’adresse de paquet reçues.

Pour les datagrammes reçus via IPv4, le membre De contrôle de la structure WSAMSG reçue contient une structure WSABUF qui contient une structure WSACMSGHDR . Le membre cmsg_level de cette structure WSACMSGHDR contiendrait IPPROTO_IP, le membre cmsg_type de cette structure contiendrait IP_PKTINFO et le membre cmsg_data contiendrait une structure in_pktinfo utilisée pour stocker les informations d’adresse de paquet IPv4 reçues. L’adresse IPv4 dans la structure in_pktinfo est l’adresse IPv4 à partir de laquelle le paquet a été reçu.

Lorsque l’option de socket IPV6_PKTINFO est activée sur un socket IPv6 de type SOCK_DGRAM ou SOCK_RAW, la fonction WSARecvMsg retourne des informations sur les paquets dans la structure WSAMSG pointée vers le paramètre lpMsg . L’un des objets de données de contrôle dans la structure WSAMSG retournée contient une structure in6_pktinfo utilisée pour stocker les informations d’adresse de paquet reçues.

Pour les datagrammes reçus via IPv6, le membre De contrôle de la structure WSAMSG reçue contient une structure WSABUF qui contient une structure WSACMSGHDR . Le membre cmsg_level de cette structure WSACMSGHDR contiendrait des IPPROTO_IPV6, le membre cmsg_type de cette structure contiendrait IPV6_PKTINFO et le membre cmsg_data contiendrait une structure in6_pktinfo utilisée pour stocker les informations d’adresse de paquet IPv6 reçues. L’adresse IPv6 dans la structure in6_pktinfo est l’adresse IPv6 à partir de laquelle le paquet a été reçu.

Pour un socket de datagramme à double pile, si une application nécessite que la fonction WSARecvMsg retourne les informations de paquet dans une structure WSAMSG pour les datagrammes reçus via IPv4, IP_PKTINFO option de socket doit avoir la valeur true sur le socket. Si seule l’option IPV6_PKTINFO est définie sur true sur le socket, les informations de paquet sont fournies pour les datagrammes reçus via IPv6, mais ne peuvent pas être fournies pour les datagrammes reçus via IPv4.

Notez que le fichier d’en-tête Ws2ipdef.h est automatiquement inclus dans Ws2tcpip.h et ne doit jamais être utilisé directement.

Note Toutes les E/S initiées par un thread donné sont annulées à la sortie de ce thread. Pour les sockets qui se chevauchent, les opérations asynchrones en attente peuvent échouer si le thread est fermé avant la fin des opérations. Pour plus d’informations, consultez ExitThread.

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

dwFlags

En entrée, le membre dwFlags de la structure WSAMSG pointée par le paramètre lpMsg peut être utilisé pour influencer le comportement de l’appel de fonction au-delà des options de socket spécifiées pour le socket associé. Autrement dit, la sémantique de cette fonction est déterminée par les options de socket et le membre dwFlags de la structure WSAMSG . La seule valeur d’entrée possible pour le membre dwFlags de la structure WSAMSG pointée par le paramètre lpMsg est MSG_PEEK.

Valeur	Signification
MSG_PEEK	Aperçu aux données entrantes. Les données sont copiées dans la mémoire tampon, mais ne sont pas supprimées de la file d’attente d’entrée. Cet indicateur est valide uniquement pour les sockets qui ne se chevauchent pas.

Les valeurs possibles pour le membre dwFlags sur l’entrée sont définies dans le fichier d’en-tête Winsock2.h .

À la sortie, le membre dwFlags de la structure WSAMSG pointée vers le paramètre lpMsg peut retourner une combinaison de l’une des valeurs suivantes.

Valeur	Signification
MSG_BCAST	Le datagramme a été reçu en tant que diffusion de couche de liaison ou avec une adresse IP de destination qui est une adresse de diffusion.
MSG_CTRUNC	Les données de contrôle (accessoires) ont été tronquées. Plus de données de contrôle étaient présentes que l’espace alloué au processus.
MSG_MCAST	Le datagramme a été reçu avec une adresse IP de destination qui est une adresse de multidiffusion.
MSG_TRUNC	Le datagramme a été tronqué. Plus de données étaient présentes que l’espace alloué au processus.

Sur le Microsoft Kit de développement logiciel Windows (Kit SDK Windows) (SDK) publié pour Windows Vista et versions ultérieures, la organization des fichiers d’en-tête a changé et les valeurs possibles pour le membre dwFlags sur la sortie sont définies dans le fichier d’en-tête Ws2def.h qui est automatiquement inclus par le fichier d’en-tête Winsock2.h.

Sur les versions du Kit de développement logiciel (SDK) de plateforme pour Windows Server 2003 et versions antérieures, les valeurs possibles pour le membre dwFlags sur la sortie sont définies dans le fichier d’en-tête Mswsock.h .

Note Lors de l’émission d’un appel Winsock bloquant tel que WSARecvMsg avec le paramètre lpOverlapped défini sur NULL, Winsock peut avoir besoin d’attendre qu’un événement réseau se termine. Winsock effectue une attente alertable dans cette situation, qui peut être interrompue par un appel de procédure asynchrone (APC) planifié sur le même thread. L’émission d’un autre appel Winsock bloquant à l’intérieur d’un APC qui a interrompu un appel Winsock bloquant en cours sur le même thread entraîne un comportement non défini et ne doit jamais être tenté par les clients Winsock.

E/S de sockets qui se chevauchent

Si une opération qui se chevauche se termine immédiatement, WSARecvMsg retourne la valeur zéro et le paramètre lpNumberOfBytesRecvd est mis à jour avec le nombre d’octets reçus et les bits d’indicateur indiqués par le paramètre lpFlags sont également mis à jour. Si l’opération qui se chevauche est correctement lancée et se terminera ultérieurement, WSARecvMsg retourne SOCKET_ERROR et indique le code d’erreur WSA_IO_PENDING. Dans ce cas, lpNumberOfBytesRecvd n’est pas mis à jour. Une fois l’opération chevauchée terminée, la quantité de données transférées est indiquée via le paramètre cbTransferred dans la routine d’achèvement (si spécifié), ou via le paramètre lpcbTransfer dans WSAGetOverlappedResult. Les valeurs d’indicateur sont obtenues en examinant le paramètre lpdwFlags de WSAGetOverlappedResult.

La fonction WSARecvMsg utilisant des E/S qui se chevauchent peut être appelée à partir de la routine d’achèvement d’une fonction WSARecvFrom, WSARecvMsg, WSARecvMsg, WSASend, WSASendMsg ou WSASendTo précédente. Pour un socket donné, les routines d’achèvement d’E/S ne sont pas imbriquées. Cela permet aux transmissions de données sensibles au temps de se produire entièrement dans un contexte préemptif.

Le paramètre lpOverlapped doit être valide pendant la durée de l’opération qui se chevauche. Si plusieurs opérations d’E/S sont simultanément en attente, chacune doit référencer une structure WSAOVERLAPPED distincte.

Si le paramètre lpCompletionRoutine a la valeur NULL, le paramètre hEvent de lpOverlapped est signalé lorsque l’opération qui se chevauche se termine s’il contient un handle d’objet d’événement valide. Une application peut utiliser WSAWaitForMultipleEvents ou WSAGetOverlappedResult pour attendre ou interroger l’objet d’événement.

Si lpCompletionRoutine n’a pas la valeur NULL, le paramètre hEvent est ignoré et peut être utilisé par l’application pour transmettre des informations de contexte à la routine d’achèvement. Un appelant qui passe un lpCompletionRoutine non NULL et appelle ultérieurement WSAGetOverlappedResult pour la même demande d’E/S qui se chevauche peut ne pas définir le paramètre fWait pour cet appel de WSAGetOverlappedResult sur TRUE. Dans ce cas, l’utilisation du paramètre hEvent n’est pas définie et une tentative d’attente sur le paramètre hEvent produirait des résultats imprévisibles.

La routine d’achèvement suit les mêmes règles que celles spécifiées pour les routines d’achèvement d’E/S de fichiers Windows. La routine d’achèvement n’est pas appelée tant que le thread n’est pas dans un état d’attente pouvant être alerté, comme cela peut se produire lorsque la fonction WSAWaitForMultipleEvents avec le paramètre fAlertable défini sur TRUE est appelée.

Le prototype de la routine d’achèvement est le suivant :


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags
);

CompletionRoutine est un espace réservé pour un nom de fonction défini par l’application ou défini par la bibliothèque. Le paramètre dwError spécifie la status d’achèvement pour l’opération qui se chevauche, comme indiqué par le paramètre lpOverlapped. Le paramètre cbTransferred spécifie le nombre d’octets reçus. Le paramètre dwFlags contient des informations qui sont également retournées dans le membre dwFlags de la structure WSAMSG pointée vers le paramètre lpMsg si l’opération de réception s’est terminée immédiatement. La fonction CompletionRoutine ne retourne pas de valeur.

Le retour à partir de cette fonction permet d’appeler une autre routine d’achèvement en attente pour ce socket. Lorsque vous utilisez WSAWaitForMultipleEvents, toutes les routines d’achèvement en attente sont appelées avant que l’attente du thread alertable soit satisfaite avec un code de retour de WSA_IO_COMPLETION. Les routines d’achèvement peuvent être appelées dans n’importe quel ordre, pas nécessairement dans le même ordre que les opérations qui se chevauchent. Toutefois, il est garanti que les mémoires tampons publiées soient remplies dans l’ordre dans lequel elles sont spécifiées.

Si vous utilisez des ports d’achèvement d’E/S, n’oubliez pas que l’ordre des appels effectués à WSARecvMsg est également l’ordre dans lequel les mémoires tampons sont remplies. La fonction WSARecvMsg ne doit pas être appelée simultanément sur le même socket à partir de différents threads, car elle peut entraîner un ordre de mémoire tampon imprévisible.