SetPerTcpConnectionEStats 函数 (iphlpapi.h)
SetPerTcpConnectionEStats 函数在 IPv4 TCP 连接的读/写信息中设置值。 此函数用于启用或禁用 IPv4 TCP 连接的扩展统计信息。
语法
IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
PMIB_TCPROW Row,
TCP_ESTATS_TYPE EstatsType,
PUCHAR Rw,
ULONG RwVersion,
ULONG RwSize,
ULONG Offset
);
参数
Row
指向 IPv4 TCP 连接的 MIB_TCPROW 结构的指针。
EstatsType
要设置的 TCP 扩展统计信息的类型。 此参数确定 Rw 参数中预期的数据和信息格式。
此参数可以是 Tcpestats.h 头文件中定义的 TCP_ESTATS_TYPE 枚举类型的值之一。
Rw
指向缓冲区的指针，该缓冲区包含要设置的读/写信息。 缓冲区应包含每个结构成员 的 TCP_BOOLEAN_OPTIONAL 枚举中的值，该值指定每个成员应如何更新。
RwVersion
要设置的读/写信息的版本。 对于 Windows Vista、Windows Server 2008 和 Windows 7，此参数应设置为零。
RwSize
Rw 参数指向的缓冲区的大小（以字节为单位）。
Offset
要设置的 Rw 参数指向结构中成员的偏移量（以字节为单位）。 此参数当前未使用，必须设置为零。
返回值
如果函数成功，则返回值NO_ERROR。
如果函数失败，则返回值为以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
访问被拒绝。 此错误在以下几种情况下返回：用户在本地计算机上缺少所需的管理权限，或者应用程序没有作为内置管理员 (RunAs 管理员) 在增强的 shell 中运行。 |
|
提供给请求操作的用户缓冲区无效。 如果 Row 参数为 NULL 指针且 RwSize 参数为非零值，则返回此错误。 |
|
参数不正确。 如果 Row 参数为 NULL 指针，则返回此错误。 |
|
找不到此请求的条目。 如果找不到 Row 参数中指定的 TCP 连接，则返回此错误。 |
|
不支持该请求。 如果未将 RwVersion 或 Offset 参数设置为 0，则返回此错误。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
SetPerTcpConnectionEStats 函数在 Windows Vista 及更高版本上定义。
SetPerTcpConnectionEStats 函数用于在 Row 参数中传递的 IPv4 TCP 连接上启用或禁用扩展统计信息。 默认情况下，TCP 连接的扩展统计信息处于禁用状态。 SetPerTcpConnectionEStats 函数用于在 IPv4 TCP 连接的扩展统计信息的读/写信息中设置成员的值。 要设置的结构的类型和格式由 EstatsType 参数指定。 Rw 参数包含指向所传递结构的指针。 必须指定 Rw 参数指向的结构中的所有成员。
目前支持的唯一 TCP 连接统计信息版本是版本零。 因此，传递给 SetPerTcpConnectionEStats 的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 参数当前未使用，必须设置为 0。 Rw 参数指向的可能结构都具有单个成员（TCP_ESTATS_BANDWIDTH_RW_v0 结构除外）。 当 EstatsType 参数设置为 TcpConnectionEstatsBandwidth 时，Rw 参数指向的TCP_ESTATS_BANDWIDTH_RW_v0结构必须在对 SetPerTcpConnectionEStats 函数的单个调用中将两个结构成员都设置为首选值。
如果 RwSize 参数设置为 0， 则 SetPerTcpConnectionEStats 函数将返回NO_ERROR，并且不会对扩展统计信息状态进行更改。
GetTcpTable 函数用于检索本地计算机上的 IPv4 TCP 连接表。 此函数返回包含 MIB_TCPROW 项数组的 MIB_TCPTABLE 结构。 传递给 SetPerTcpConnectionEStats 函数的 Row 参数必须是现有 IPv4 TCP 连接的条目。
在 IPv4 的 TCP 连接上启用扩展统计信息后，应用程序将调用 GetPerTcpConnectionEStats 函数来检索 TCP 连接上的扩展统计信息。
GetPerTcpConnectionEStats 函数旨在使用 TCP 诊断网络和应用程序中的性能问题。 如果基于网络的应用程序性能不佳，TCP 可以确定瓶颈在发送方、接收方还是网络本身。 如果瓶颈在网络中，TCP 可以提供有关其性质的特定信息。
有关 IPv6 连接的扩展 TCP 统计信息的信息，请参阅 GetPerTcp6ConnectionEStats 和 SetPerTcp6ConnectionEStats 函数。
SetPerTcpConnectionEStats 函数只能由以管理员组成员身份登录的用户调用。 如果 SetPerTcpConnectionEStats 由不是 Administrators 组成员的用户调用，则函数调用将失败并返回 ERROR_ACCESS_DENIED 。 此函数也可能因为 Windows Vista 和 Windows Server 2008 上的用户帐户控制 (UAC) 而失败。 如果包含此函数的应用程序由以管理员组成员身份登录（而非内置管理员）的用户执行，则此调用将失败，除非应用程序已在清单文件中标记为 requestedExecutionLevel 设置为 requireAdministrator。 如果 Windows Vista 或 Windows Server 2008 上的应用程序缺少此清单文件，则作为内置管理员以外的管理员组成员登录的用户必须在增强的 shell 中执行应用程序，因为内置管理员 (RunAs 管理员) 才能使此功能成功。
在 Windows 10 版本 1709 (Fall Creators Update) 之前的 Windows 版本中，可以使用 SetPerTcpConnectionEStats 禁用和重新启用连接上的统计信息，从而导致任何统计信息计数器重置为零。 从 Windows 10 版本 1709 (Fall Creators Update) 起，某些统计信息计数器在禁用和重新启用时不会重置。 此外，如果两个应用程序正在监视同一连接的统计信息，则一个应用程序可能会通过禁用统计信息来混淆另一个应用程序。 出于这些原因，我们建议应用程序不要禁用有关连接的统计信息。 若要检测一段时间内的更改，应保存上一次调用 GetPerTcpConnectionEStats 读取的计数器值，并从后续调用读取的计数器值中减去这些值。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | iphlpapi.h |
| Library | Iphlpapi.lib |
| DLL | Iphlpapi.dll |