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 成员的可能值在 Winsock2.h 头文件自动包含的 Ws2def.h 头文件中定义。

输入上的标志 含义
MSG_PEEK
 ：速览传入数据。 数据将复制到缓冲区中，但不会从输入队列中删除。 此标志仅对非重叠套接字有效。
 
返回的标志 含义
MSG_BCAST
 数据报是作为链接层广播接收的，或者接收了作为广播地址的目标 IP 地址。
MSG_MCAST
 接收数据报的目标 IP 地址是多播地址。
MSG_TRUNC
 数据报已被截断。 存在的数据多于进程为其分配的空间。
MSG_CTRUNC
 控件 (辅助) 数据被截断。 存在的控制数据多于进程为其分配的空间。

注解

在 Microsoft Windows 软件开发工具包 (Windows SDK) (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 的 Control 成员中的控件数据的各种用途。

协议 cmsg_level cmsg_type 说明
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