WSAMSG-Struktur (ws2def.h)

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.

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.

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;

Die Elemente der WSACMSGHDR-Struktur sind wie folgt:

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

Weitere Informationen

IPV6_PKTINFO

IP_PKTINFO

SOCKET_ADDRESS

WSABUF

WSARecv

WSARecvFrom

LPFN_WSARECVMSG (WSARecvMsg)

WSASendMsg