WSAMSG-Struktur (ws2def.h)

Artikel
03/04/2024

Die WSAMSG-Struktur wird mit den Funktionen LPFN_WSARECVMSG (WSARecvMsg) und WSASendMsg verwendet, um Adress- und optionale Steuerinformationen zu verbundenen und nicht verbundenen Sockets sowie ein Array von Puffern zu speichern, die zum Speichern von Nachrichtendaten verwendet werden.

Syntax

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;

Member

name

Typ: LPSOCKADDR

Ein Zeiger auf eine SOCKET_ADDRESS Struktur, in der Informationen zur Remoteadresse gespeichert werden. Wird nur mit nicht verbundenen Sockets verwendet.

namelen

Typ: INT

Die Länge der SOCKET_ADDRESS Struktur, auf die im pAddr-Element verwiesen wird, in Bytes. Wird nur mit nicht verbundenen Sockets verwendet.

lpBuffers

Typ: LPWSABUF

Ein Array von WSABUF-Strukturen , die zum Empfangen der Nachrichtendaten verwendet werden. Die Fähigkeit des lpBuffers-Members , mehrere Puffer zu enthalten, ermöglicht die Verwendung von Scatter/Gather-E/A.

dwBufferCount

Art: DWORD

Die Anzahl der Puffer, auf die im lpBuffers-Member verwiesen wird .

Control

Typ: WSABUF

Eine Struktur vom WSABUF-Typ , die zum Angeben optionaler Steuerungsdaten verwendet wird. Siehe Hinweise.

dwFlags

Art: DWORD

Ein oder mehrere Steuerelementflags, die als logisches OR von Werten angegeben sind. Die möglichen Werte für dwFlags-Member bei der Eingabe sind in der Winsock2.h-Headerdatei definiert. Die möglichen Werte für dwFlags-Member bei der Ausgabe werden in der Ws2def.h-Headerdatei definiert, die automatisch in der Winsock2.h-Headerdatei enthalten ist.

Flags für Eingaben	Bedeutung
MSG_PEEK	Peek an den eingehenden Daten. Die Daten werden in den Puffer kopiert, aber nicht aus der Eingabewarteschlange entfernt. Dieses Flag ist nur für nicht überlappende Sockets gültig.

Flag zurückgegeben	Bedeutung
MSG_BCAST	Das Datagramm wurde als Broadcast auf Linkebene oder mit einer Ziel-IP-Adresse empfangen, bei der es sich um eine Broadcastadresse handelt.
MSG_MCAST	Das Datagramm wurde mit einer Ziel-IP-Adresse empfangen, bei der es sich um eine Multicastadresse handelt.
MSG_TRUNC	Das Datagramm wurde abgeschnitten. Es waren mehr Daten vorhanden, als dem Prozess zugewiesen wurde.
MSG_CTRUNC	Die Steuerelementdaten (Hilfsdaten) wurden abgeschnitten. Es waren mehr Steuerungsdaten vorhanden, als dem Prozess zugewiesen wurde.

Hinweise

Im Microsoft Windows Software Development Kit (SDK) wird die Version dieser Struktur für die Verwendung unter Windows Vista mit dem Datentyp für die Elemente dwBufferCount und dwFlags als ULONG definiert. Wenn eine Anwendung kompiliert wird, wenn die Zielplattform Windows Vista und höher ist (NTDDI_VERSION >= NTDDI_LONGHORN, _WIN32_WINNT >= 0x0600 oder WINVER >= 0x0600), ist der Datentyp für die Elemente dwBufferCount und dwFlags ein ULONG.

Windows Server 2003 und Windows XP: Beim Kompilieren einer Anwendung ist der Datentyp für die Elemente dwBufferCount und dwFlags ein DWORD.

Auf der für Windows Vista und höher veröffentlichten Windows SDK wird die WSAMSG-Struktur in der Ws2def.h-Headerdatei definiert. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Winsock2.h enthalten ist und niemals direkt verwendet werden sollte.

Wenn die Datagramm- oder Steuerelementdaten während der Übertragung abgeschnitten werden, gibt die in Verbindung mit der WSAMSG-Struktur verwendete Funktion SOCKET_ERROR zurück, und ein Aufruf der WSAGetLastError-Funktion gibt WSAEMSGSIZE zurück. Es liegt an der Anwendung, zu bestimmen, was abgeschnitten wurde, indem auf MSG_TRUNC und/oder MSG_CTRUNC Flags überprüft wird.

Verwendung des Steuerelementmembers

In der folgenden Tabelle sind die verschiedenen Verwendungen von Steuerungsdaten zusammengefasst, die für die Verwendung im Control-Member für IPv4 und IPv6 verfügbar sind.

Protocol	cmsg_level	cmsg_type	BESCHREIBUNG
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Empfängt die ursprüngliche IPv4-Eingangsschnittstelle, über die das Paket für Datagrammsockets empfangen wurde. Diese Steuerungsdaten werden von Firewalls verwendet, wenn ein Teredo-, 6-zu-4- oder ISATAP-Tunnel für den IPv4-NAT-Durchlauf verwendet wird. Das cmsg_data[]-Element in der WSAMSG-Struktur ist ein ULONG-Element , das die in der Headerdatei Ifdef.h definierte IF_INDEX enthält. Weitere Informationen finden Sie unter IPPROTO_IP Socketoptionen für die Socketoption IP_ORIGINAL_ARRIVAL_IF. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Die IP_ORIGINAL_ARRIVAL_IF cmsg_type wird nicht unterstützt.
IPv4	IPPROTO_IP	IP_PKTINFO	Gibt Paketinformationen für einen IPv4-Socket an/empfängt diese. Weitere Informationen finden Sie unter IP_PKTINFO Socketoption.
IPv4	IPPROTO_IP	IP_ECN	Gibt den ECN-Codepunkt im IPv4-Headerfeld "Diensttyp( TOS)" an. Weitere Informationen finden Sie unter WSASetRecvIPEcn.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Gibt Zieloptionen an/empfängt sie.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Gibt das Hoplimit an/empfängt. Weitere Informationen finden Sie unter IPPROTO_IPV6 Socketoptionen für die Socketoption IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Gibt Optionen für Hop-by-Hop an/empfängt sie.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Gibt die Adresse des nächsten Hops an.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Gibt Paketinformationen für einen IPv6-Socket an/empfängt sie. Weitere Informationen finden Sie unter IPV6_PKTINFO Socketoption.
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Gibt den Routingheader an/empfängt.
IPv6	IPPROTO_IPV6	IPV6_ECN	Gibt den ECN-Codepunkt im IPv6-Headerfeld der Datenverkehrsklasse an. Weitere Informationen finden Sie unter WSASetRecvIPEcn.

Steuerelementdaten bestehen aus einem oder mehreren Steuerelementdatenobjekten, die jeweils mit einer WSACMSGHDR-Struktur beginnen, die wie folgt definiert ist.

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

Hinweis Der Transport, nicht die Anwendung, füllt die Headerinformationen in der WSACMSGHDR-Struktur aus. Die Anwendung legt einfach die erforderlichen Socketoptionen fest und stellt die geeignete Puffergröße bereit.

Die Elemente der WSACMSGHDR-Struktur sind wie folgt:

Begriff	BESCHREIBUNG
cmsg_len	Die Anzahl der Bytes der Daten, die vom Anfang des WSACMSGHDR bis zum Ende der Daten beginnen (mit Ausnahme der Auffüllung von Bytes, die auf Daten folgen können).
cmsg_level	Das Protokoll, aus dem die Steuerelementinformationen stammen.
cmsg_type	Der protokollspezifische Typ von Steuerelementinformationen.

Die folgenden Makros werden verwendet, um in den Datenobjekten zu navigieren:


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

Gibt einen Zeiger auf das erste Steuerelementdatenobjekt zurück. Gibt einen NULL-Zeiger zurück, wenn keine Steuerelementdaten in der WSAMSG-Struktur vorhanden sind, z. B. wenn der Control-Member ein NULL-Zeiger ist.


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

Gibt einen Zeiger auf das nächste Steuerelementdatenobjekt oder NULL zurück, wenn keine Datenobjekte mehr vorhanden sind. Wenn der pcmsg-ParameterNULL ist, wird ein Zeiger auf das erste Steuerelementdatenobjekt zurückgegeben.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

Gibt einen Zeiger auf das erste Byte von Daten zurück (der als cmsg_data-Member bezeichnet wird, obwohl er in der -Struktur nicht definiert ist).


#define UINT WSA_CMSG_SPACE(UINT length);

Gibt die Gesamtgröße eines Steuerelementdatenobjekts unter Berücksichtigung der Datenmenge zurück. Wird verwendet, um die richtige Menge an Pufferspeicherplatz zuzuweisen. Enthält einen Ausrichtungsabstand.


#define UINT WSA_CMSG_LEN(UINT length);

Gibt den Wert in cmsg_len unter Berücksichtigung der Datenmenge zurück. Enthält einen Ausrichtungsabstand.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Kopfzeile	ws2def.h (Winsock2.h einschließen)