SetPerTcp6ConnectionEStats 函数 (iphlpapi.h)
SetPerTcp6ConnectionEStats 函数在 IPv6 TCP 连接的读/写信息中设置值。 此函数用于启用或禁用 IPv6 TCP 连接的扩展统计信息。
语法
IPHLPAPI_DLL_LINKAGE ULONG SetPerTcp6ConnectionEStats(
PMIB_TCP6ROW Row,
TCP_ESTATS_TYPE EstatsType,
PUCHAR Rw,
ULONG RwVersion,
ULONG RwSize,
ULONG Offset
);
参数
Row
指向 IPv6 TCP 连接的 MIB_TCP6ROW 结构的指针。
EstatsType
要设置的 TCP 扩展统计信息的类型。 此参数确定 Rw 参数中预期的数据和信息格式。
此参数可以是 Tcpestats.h 头文件中定义的 TCP_ESTATS_TYPE 枚举类型的值之一。
| 值 | 含义 |
|---|---|
|
此值指定 TCP 连接的扩展数据传输信息。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_DATA_RW_v0 结构。 |
|
此值指定 TCP 连接的发送方拥塞。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_SND_CONG_RW_v0 结构。 |
|
此值指定 TCP 连接的扩展路径度量信息。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_PATH_RW_v0 结构。 |
|
此值指定 TCP 连接的扩展输出队列信息。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_SEND_BUFF_RW_v0 结构。 |
|
此值指定 TCP 连接的扩展本地接收器信息。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_REC_RW_v0 结构。 |
|
此值指定 TCP 连接的扩展远程接收器信息。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_OBS_REC_RW_v0 结构。 |
|
此值指定带宽上的 TCP 连接的带宽估计统计信息。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_BANDWIDTH_RW_v0 结构。 |
|
此值指定 TCP 连接的精细往返时间 (RTT) 估计统计信息。
指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_FINE_RTT_RW_v0 结构。 |
Rw
指向缓冲区的指针，该缓冲区包含要设置的读/写信息。 缓冲区应包含每个结构成员 的 TCP_BOOLEAN_OPTIONAL 枚举中的值，该值指定每个成员应如何更新。
RwVersion
要设置的读/写信息的版本。 对于 Windows Vista、Windows Server 2008 和 Windows 7，此参数应设置为零。
RwSize
Rw 参数指向的缓冲区的大小（以字节为单位）。
Offset
要设置的 Rw 参数指向结构中成员的偏移量（以字节为单位）。 此参数当前未使用，必须设置为零。
返回值
如果函数成功，则返回值NO_ERROR。
如果函数失败，则返回值为以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
访问被拒绝。 此错误在以下几种情况下返回：用户在本地计算机上缺少所需的管理权限，或者应用程序没有作为内置管理员 (RunAs 管理员) 在增强的 shell 中运行。 |
|
参数不正确。 如果 Row 参数为 NULL 指针，则返回此错误。 |
|
提供给请求操作的用户缓冲区无效。 如果 Row 参数为 NULL 指针且 RwSize 参数为非零值，则返回此错误。 |
|
找不到此请求的条目。 如果找不到 Row 参数中指定的 TCP 连接，则返回此错误。 |
|
不支持该请求。 如果未将 RwVersion 或 Offset 参数设置为 0，则返回此错误。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
SetPerTcp6ConnectionEStats 函数是在 Windows Vista 及更高版本上定义的。
SetPerTcp6ConnectionEStats 函数用于为 Row 参数中传递的 IPv6 TCP 连接启用或禁用扩展统计信息。 默认情况下，TCP 连接的扩展统计信息处于禁用状态。
SetPerTcp6ConnectionEStats 函数用于在 IPv6 TCP 连接的扩展统计信息的读/写信息中设置成员的值。 要设置的结构的类型和格式由 EstatsType 参数指定。 Rw 参数包含指向所传递结构的指针。 要在此结构中设置的成员由 Offset 参数指定。 必须指定 Rw 参数指向的结构中的所有成员。
目前支持的唯一 TCP 连接统计信息版本是版本零。 因此，传递给 SetPerTcp6ConnectionEStats 的RwVersion 参数应设置为 0。
传递此函数的 Rw 参数指向的结构取决于 在 EstatsType 参数中传递的枚举值。 下表指示应为每个可能的 EstatsType 参数类型在 Rw 参数中传递的结构类型。
| EstatsType | Rw 指向的结构 |
|---|---|
| TcpConnectionEstatsData | TCP_ESTATS_DATA_RW_v0 |
| TcpConnectionEstatsSndCong | TCP_ESTATS_SND_CONG_RW_v0 |
| TcpConnectionEstatsPath | TCP_ESTATS_PATH_RW_v0 |
| TcpConnectionEstatsSendBuff | TCP_ESTATS_SEND_BUFF_RW_v0 |
| TcpConnectionEstatsRec | TCP_ESTATS_REC_RW_v0 |
| TcpConnectionEstatsObsRec | TCP_ESTATS_OBS_REC_RW_v0 |
| TcpConnectionEstatsBandwidth | TCP_ESTATS_BANDWIDTH_RW_v0 |
| TcpConnectionEstatsFineRtt | TCP_ESTATS_FINE_RTT_RW_v0 |
Offset 参数当前未使用。 Rw 参数指向的可能结构都具有单个成员，TCP_ESTATS_BANDWIDTH_RW_v0 结构除外。 当 EstatsType 参数设置为 TcpConnectionEstatsBandwidth 时，Rw 参数指向的 TCP_ESTATS_BANDWIDTH_RW_v0 结构必须在对 SetPerTcp6ConnectionEStats 函数的单个调用中同时将两个结构成员都设置为首选值。
如果 RwSize 参数设置为 0， 则 SetPerTcp6ConnectionEStats 函数将返回NO_ERROR且不会更改扩展统计信息状态。
GetTcp6Table 函数用于检索本地计算机上的 IPv6 TCP 连接表。 此函数返回包含 MIB_TCP6ROW 项数组的 MIB_TCP6TABLE 结构。 传递给 SetPerTcp6ConnectionEStats 函数的 Row 参数必须是现有 IPv6 TCP 连接的条目。
在 IPv6 的 TCP 连接上启用扩展统计信息后，应用程序将调用 GetPerTcp6ConnectionEStats 函数来检索 TCP 连接上的扩展统计信息。
GetPerTcp6ConnectionEStats 函数旨在使用 TCP 诊断网络和应用程序中的性能问题。 如果基于网络的应用程序性能不佳，TCP 可以确定瓶颈是在发送方、接收方还是网络本身。 如果瓶颈在网络中，TCP 可以提供有关其性质的特定信息。
有关 IPv4 连接上的扩展 TCP 统计信息的信息，请参阅 GetPerTcpConnectionEStats 和 SetPerTcpConnectionEStats 函数。
SetPerTcp6ConnectionEStats 函数只能由以 Administrators 组成员身份登录的用户调用。 如果 SetPerTcp6ConnectionEStats 由不是 Administrators 组成员的用户调用，则函数调用将失败并返回 ERROR_ACCESS_DENIED 。 此函数也可能因为 Windows Vista 和 Windows Server 2008 上的用户帐户控制 (UAC) 而失败。 如果包含此函数的应用程序由以管理员组成员身份登录（而不是内置管理员）的用户执行，则此调用将失败，除非应用程序已在清单文件中标记为 requestedExecutionLevel 设置为 requireAdministrator。 如果 Windows Vista 或 Windows Server 2008 上的应用程序缺少此清单文件，则作为管理员组成员（而不是内置管理员）登录的用户必须在增强的 shell 中执行应用程序，因为内置管理员 (RunAs 管理员) 才能使此功能成功。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | iphlpapi.h |
| Library | Iphlpapi.lib |
| DLL | Iphlpapi.dll |