Structure WSAMSG (ws2def.h)

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.

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.

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;

Les membres de la structure WSACMSGHDR sont les suivants :

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

Voir aussi

IPV6_PKTINFO

IP_PKTINFO

SOCKET_ADDRESS

WSABUF

WSARecv

WSARecvFrom

LPFN_WSARECVMSG (WSARecvMsg)

WSASendMsg