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 頭檔中。

輸入上的旗標 意義
MSG_PEEK
 預覽 傳入的數據。 數據會複製到緩衝區，但不會從輸入佇列中移除。 此旗標僅適用於非重疊的套接字。
 
傳回的旗標 意義
MSG_BCAST
 數據報是以連結層廣播的形式接收，或是具有廣播位址的目的地IP位址。
MSG_MCAST
 數據報是以多播位址的目的地 IP 位址接收。
MSG_TRUNC
 數據報已截斷。 數據比進程配置的空間還多。
MSG_CTRUNC
 已截斷控件 () 數據。 控件數據比進程配置的空間還多。

備註

在 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 結構中的標頭資訊。 應用程式只會設定所需的套接字選項，並提供適當的緩衝區大小。
 

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)

另請參閱

IPV6_PKTINFO

IP_PKTINFO

SOCKET_ADDRESS

WSABUF

WSARecv

WSARecvFrom

LPFN_WSARECVMSG (WSARecvMsg)

WSASendMsg