WSAMSG 結構 (ws2def.h)
WSAMSG 結構會與LPFN_WSARECVMSG (WSARecvMsg) 和 WSASendMsg 函式搭配使用，以儲存連線和未連線套接字的選擇性控制資訊，以及用來儲存訊息數據的緩衝區陣列。
語法
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;
成員
name
類型： LPSOCKADDR
儲存遠端地址相關信息 之SOCKET_ADDRESS 結構的指標。 僅搭配未連線的套接字使用。
namelen
類型： INT
pAddr 成員中所指向之SOCKET_ADDRESS結構的長度，以位元組為單位。 僅搭配未連線的套接字使用。
lpBuffers
類型： LPWSABUF
用來接收訊息數據的 WSABUF 結構的數位。 lpBuffers 成員包含多個緩衝區的功能可讓您使用散佈/收集 I/O。
dwBufferCount
類型： DWORD
lpBuffers 成員中所指向的緩衝區數目。
Control
類型： WSABUF
用來指定選擇性控件數據的 WSABUF 類型結構。 請參閱＜備註＞。
dwFlags
類型： DWORD
一或多個控件旗標，指定為值的邏輯 OR 。 輸入上 dwFlags 成員的可能值定義在 Winsock2.h 頭檔中。 輸出上 dwFlags 成員的可能值定義在 Wins2def.h 頭文件自動包含的 Ws2def.h 頭檔中。
| 輸入上的旗標 | 意義 |
|---|---|
|
預覽 傳入的數據。 數據會複製到緩衝區，但不會從輸入佇列中移除。 此旗標僅適用於非重疊的套接字。 |
| 傳回的旗標 | 意義 |
|---|---|
|
數據報是以連結層廣播的形式接收，或是具有廣播位址的目的地IP位址。 |
|
數據報是以多播位址的目的地 IP 位址接收。 |
|
數據報已截斷。 數據比進程配置的空間還多。 |
|
已截斷控件 () 數據。 控件數據比進程配置的空間還多。 |
備註
在 Microsoft Windows 軟體開發套件 (SDK) 中，Windows Vista 上要使用的此結構版本是以 dwBufferCount 和 dwFlags 成員的數據類型定義為 ULONG。 如果目標平臺是 Windows Vista 且更新版本 (NTDDI_VERSION >= NTDDI_LONGHORN、_WIN32_WINNT = 0x0600>或 WINVER >= 0x0600) ，則 dwBufferCount 和dwFlags 成員的數據類型為 ULONG 時。
Windows Server 2003 和 Windows XP： 編譯應用程式時， dwBufferCount 和 dwFlags 成員的 數據類型是 DWORD。
在針對 Windows Vista 和更新版本發行的 Windows SDK 上，WSAMSG 結構定義於 Ws2def.h 頭檔中。 請注意，Ws2def.h 頭文件會自動包含在 Winsock2.h 中，不應直接使用
如果在傳輸期間截斷數據報或控件數據，則與 WSAMSG 結構關聯的函式會傳回SOCKET_ERROR，而 對 WSAGetLastError 函式的呼叫會傳回 WSAEMSGSIZE。 應用程式可藉由檢查MSG_TRUNC和/或MSG_CTRUNC旗標來判斷截斷的內容。
使用控件成員
下表摘要說明 IPv4 和 IPv6 控制項成員中 可用的各種控件資料用法。
| 通訊協定 | cmsg_level | cmsg_type | Description |
|---|---|---|---|
| IPv4 | IPPROTO_IP | IP_ORIGINAL_ARRIVAL_IF | 接收接收數據報套接字封包的原始 IPv4 抵達介面。 當 Teredo、6to4 或 ISATAP 通道用於 IPv4 NAT 周遊時，防火牆會使用此控制數據。 WSAMSG 結構中的 cmsg_data[] 成員是 ULONG，其中包含 Ifdef.h 頭文件中定義的IF_INDEX。 如需詳細資訊，請參閱 IP_ORIGINAL_ARRIVAL_IF 套接字選項的 IPPROTO_IP 套接字 選項。 Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援 IP_ORIGINAL_ARRIVAL_IF cmsg_type 。 |
| IPv4 | IPPROTO_IP | IP_PKTINFO | 指定/接收 IPv4 套接字的封包資訊。 如需詳細資訊，請參閱 IP_PKTINFO 套接字選項。 |
| IPv4 | IPPROTO_IP | IP_ECN | 指定/接收 [服務類型] (TOS) IPv4 標頭欄位中的 ECN 代碼點。 如需詳細資訊，請參閱 WSASetRecvIPEcn。 |
| IPv6 | IPPROTO_IPV6 | IPV6_DSTOPTS | 指定/接收目的地選項。 |
| IPv6 | IPPROTO_IPV6 | IPV6_HOPLIMIT | 指定/接收躍點限制。 如需詳細資訊，請參閱 IPV6_HOPLIMIT 套接字選項IPPROTO_IPV6套接字選項。 |
| IPv6 | IPPROTO_IPV6 | IPV6_HOPOPTS | 指定/接收逐一躍點選項。 |
| IPv6 | IPPROTO_IPV6 | IPV6_NEXTHOP | 指定下一個躍點位址。 |
| IPv6 | IPPROTO_IPV6 | IPV6_PKTINFO | 指定/接收 IPv6 套接字的封包資訊。 如需詳細資訊，請參閱 IPV6_PKTINFO 套接字選項。 |
| IPv6 | IPPROTO_IPV6 | IPV6_RTHDR | 指定/接收路由標頭。 |
| IPv6 | IPPROTO_IPV6 | IPV6_ECN | 指定/接收流量類別 IPv6 標頭欄位中的 ECN 程式代碼點。 如需詳細資訊，請參閱 WSASetRecvIPEcn。 |
控件數據是由一或多個控件數據對象所組成，每個物件都是以 WSACMSGHDR 結構開頭，定義如下。
struct wsacmsghdr {
UINT cmsg_len;
INT cmsg_level;
INT cmsg_type;
/* followed by UCHAR cmsg_data[] */
} WSACMSGHDR;
WSACMSGHDR 結構的成員如下所示：
| 詞彙 | 描述 |
|---|---|
| cmsg_len | 從 WSACMSGHDR 開頭到數據結尾的數據位元組數目， (排除數據) 之後的填補位元組。 |
| cmsg_level | 產生控制資訊的通訊協定。 |
| cmsg_type | 通訊協定特定的控制信息類型。 |
下列宏可用來巡覽數據物件：
#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);
傳回第一個控件數據物件的指標。 如果 WSAMSG 結構中沒有控件數據，例如當 Control 成員是 NULL 指標時，會傳回 NULL 指標。
#define LPCMSGHDR *WSA_CMSG_NXTHDR(LPWSAMSG msg, LPWSACMSGHDR cmsg);
傳回下一個控件數據物件的指標，如果沒有其他數據物件，則傳回 NULL 。 如果 pcmsg 參數為 NULL，則會傳回第一個控件數據物件的指標。
#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);
傳回數據 (稱為 cmsg_data 成員之第一個字節的指標，但結構中並未定義) 。
#define UINT WSA_CMSG_SPACE(UINT length);
根據數據量，傳回控件數據物件的總大小。 用來配置正確的緩衝區空間數量。 包含對齊邊框間距。
#define UINT WSA_CMSG_LEN(UINT length);
傳回指定數據量 cmsg_len 中的值。 包含對齊邊框間距。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
| 標頭 | ws2def.h (包含 Winsock2.h) |