Structure WSAMSG (ws2def.h)

Article
03/13/2024

La structure WSAMSG est utilisée avec les fonctions LPFN_WSARECVMSG (WSARecvMsg) et WSASendMsg pour stocker des informations d’adresse et de contrôle facultatives sur les sockets connectés et non connectés, ainsi qu’un tableau de mémoires tampons utilisées pour stocker les données de message.

Syntaxe

typedef struct _WSAMSG {
  LPSOCKADDR name;
  INT        namelen;
  LPWSABUF   lpBuffers;
#if ...
  ULONG      dwBufferCount;
#else
  DWORD      dwBufferCount;
#endif
  WSABUF     Control;
#if ...
  ULONG      dwFlags;
#else
  DWORD      dwFlags;
#endif
} WSAMSG, *PWSAMSG, *LPWSAMSG;

Membres

name

Type : LPSOCKADDR

Pointeur vers une structure SOCKET_ADDRESS qui stocke des informations sur l’adresse distante. Utilisé uniquement avec des sockets non connectés.

namelen

Type : INT

Longueur, en octets, de la structure SOCKET_ADDRESS pointée vers le membre pAddr . Utilisé uniquement avec des sockets non connectés.

lpBuffers

Type : LPWSABUF

Tableau de structures WSABUF utilisées pour recevoir les données de message. La capacité du membre lpBuffers à contenir plusieurs mémoires tampons permet d’utiliser des E/S de diffusion/collecte.

dwBufferCount

Type : DWORD

Nombre de mémoires tampons pointées vers le membre lpBuffers .

Control

Type : WSABUF

Structure de type WSABUF utilisée pour spécifier des données de contrôle facultatives. Consultez la section Notes.

dwFlags

Type : DWORD

Un ou plusieurs indicateurs de contrôle, spécifiés en tant que OR logique des valeurs. Les valeurs possibles pour le membre dwFlags sur l’entrée sont définies dans le fichier d’en-tête Winsock2.h. 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.

Indicateurs sur l’entrée	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.

Indicateur retourné	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_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.
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.

Remarques

Dans microsoft Kit de développement logiciel Windows (Kit SDK Windows) (SDK), la version de cette structure à utiliser sur Windows Vista est définie avec le type de données des membres dwBufferCount et dwFlags en tant que ULONG. Lors de la compilation d’une application si la plateforme cible est Windows Vista et versions ultérieures (NTDDI_VERSION >= NTDDI_LONGHORN, _WIN32_WINNT >= 0x0600 ou WINVER >= 0x0600), le type de données pour les membres dwBufferCount et dwFlags est un ULONG.

Windows Server 2003 et Windows XP : Lors de la compilation d’une application, le type de données des membres dwBufferCount et dwFlags est un DWORD.

Sur le SDK Windows publié pour Windows Vista et versions ultérieures, la structure WSAMSG est définie dans le fichier d’en-tête Ws2def.h. Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement

Si les données de datagramme ou de contrôle sont tronquées pendant la transmission, la fonction utilisée en association avec la structure WSAMSG retourne SOCKET_ERROR et un appel à la fonction WSAGetLastError renvoie WSAEMSGSIZE. Il appartient à l’application de déterminer ce qui a été tronqué en vérifiant les indicateurs MSG_TRUNC et/ou MSG_CTRUNC.

Utilisation du membre de contrôle

Le tableau suivant récapitule les différentes utilisations des données de contrôle disponibles dans le membre Control pour IPv4 et IPv6.

Protocol	cmsg_level	cmsg_type	Description
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Reçoit l’interface d’arrivée IPv4 d’origine où le paquet a été reçu pour les sockets de datagramme. Ces données de contrôle sont utilisées par les pare-feu lorsqu’un tunnel Teredo, 6to4 ou ISATAP est utilisé pour la traversée NAT IPv4. Le membre cmsg_data[] de la structure WSAMSG est un ULONG qui contient les IF_INDEX définis dans le fichier d’en-tête Ifdef.h. Pour plus d’informations, consultez options de socket IPPROTO_IP pour l’option socket IP_ORIGINAL_ARRIVAL_IF. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Le cmsg_type IP_ORIGINAL_ARRIVAL_IF n’est pas pris en charge.
IPv4	IPPROTO_IP	IP_PKTINFO	Spécifie/reçoit les informations de paquet pour un socket IPv4. Pour plus d’informations, consultez l’option socket IP_PKTINFO .
IPv4	IPPROTO_IP	IP_ECN	Spécifie/reçoit le point de code ECN dans le champ d’en-tête IPv4 type de service (TOS). Pour plus d’informations, consultez WSASetRecvIPEcn.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Spécifie/reçoit les options de destination.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Spécifie/reçoit la limite de tronçon. Pour plus d’informations, consultez options de socket IPPROTO_IPV6 pour l’option de socket IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Spécifie/reçoit les options de tronçon par tronçon.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Spécifie l’adresse du tronçon suivant.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Spécifie/reçoit les informations de paquet pour un socket IPv6. Pour plus d’informations, consultez l’option de socket IPV6_PKTINFO .
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Spécifie/reçoit l’en-tête de routage.
IPv6	IPPROTO_IPV6	IPV6_ECN	Spécifie/reçoit le point de code ECN dans le champ d’en-tête IPv6 de la classe de trafic. Pour plus d’informations, consultez WSASetRecvIPEcn.

Les données de contrôle sont constituées d’un ou plusieurs objets de données de contrôle, chacun commençant par une structure WSACMSGHDR , définie comme suit.

struct wsacmsghdr {
  UINT        cmsg_len;
  INT         cmsg_level;
  INT         cmsg_type;
  /* followed by UCHAR cmsg_data[] */
} WSACMSGHDR;

Note Le transport, et non l’application, remplit les informations d’en-tête dans la structure WSACMSGHDR . L’application définit simplement les options de socket nécessaires et fournit la taille de mémoire tampon adéquate.

Les membres de la structure WSACMSGHDR sont les suivants :

Terme	Description
cmsg_len	Nombre d’octets de données commençant du début de WSACMSGHDR à la fin des données (à l’exception des octets de remplissage qui peuvent suivre les données).
cmsg_level	Protocole à l’origine des informations de contrôle.
cmsg_type	Type d’informations de contrôle spécifique au protocole.

Les macros suivantes sont utilisées pour parcourir les objets de données :


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

Retourne un pointeur vers le premier objet de données de contrôle. Retourne un pointeur NULL s’il n’existe aucune donnée de contrôle dans la structure WSAMSG , par exemple lorsque le membre Control est un pointeur NULL .


#define LPCMSGHDR *WSA_CMSG_NXTHDR(LPWSAMSG msg, LPWSACMSGHDR cmsg);

Retourne un pointeur vers l’objet de données de contrôle suivant, ou NULL s’il n’y a plus d’objets de données. Si le paramètre pcmsg a la valeur NULL, un pointeur vers le premier objet de données de contrôle est retourné.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

Retourne un pointeur vers le premier octet de données (appelé membre cmsg_data , bien qu’il ne soit pas défini dans la structure).


#define UINT WSA_CMSG_SPACE(UINT length);

Retourne la taille totale d’un objet de données de contrôle, en fonction de la quantité de données. Utilisé pour allouer la quantité correcte d’espace de mémoire tampon. Inclut le remplissage d’alignement.


#define UINT WSA_CMSG_LEN(UINT length);

Retourne la valeur dans cmsg_len en fonction de la quantité de données. Inclut le remplissage d’alignement.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
En-tête	ws2def.h (inclure Winsock2.h)