GetPerTcpConnectionEStats 函数 (iphlpapi.h)
GetPerTcpConnectionEStats 函数检索 IPv4 TCP 连接的扩展统计信息。
语法
IPHLPAPI_DLL_LINKAGE ULONG GetPerTcpConnectionEStats(
PMIB_TCPROW Row,
TCP_ESTATS_TYPE EstatsType,
[out] PUCHAR Rw,
ULONG RwVersion,
ULONG RwSize,
[out] PUCHAR Ros,
ULONG RosVersion,
ULONG RosSize,
[out] PUCHAR Rod,
ULONG RodVersion,
ULONG RodSize
);
parameters
Row
指向 IPv4 TCP 连接的 MIB_TCPROW 结构的指针。
EstatsType
请求的 TCP 扩展统计信息的类型。 如果调用成功，此参数确定 在 Rw、 Rod 和 Ros 参数中返回的信息的数据和格式。
此参数可以是 Tcpestats.h 头文件中定义的 TCP_ESTATS_TYPE 枚举类型的值之一。
| 值 | 含义 |
|---|---|
|
此值请求 TCP 连接的 SYN 交换信息。
此枚举值仅提供只读静态信息。 如果 Ros 参数不为 NULL 且函数成功， 则 Ros 参数指向的缓冲区应包含 TCP_ESTATS_SYN_OPTS_ROS_v0 结构。 |
|
此值请求 TCP 连接的扩展数据传输信息。
此枚举值只能使用只读动态信息和读/写信息。 如果 Rw 参数不为 NULL 且函数成功， 则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_DATA_RW_v0 结构。 如果为此 TCP 连接启用了扩展数据传输信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_DATA_ROD_v0 结构。 |
|
此值请求 TCP 连接的发送方拥塞。
) (只读静态、只读动态和读/写信息的所有三种类型的信息都可用于此枚举值。 如果 Rw 参数不为 NULL 且函数成功， 则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_SND_CONG_RW_v0 结构。 如果 Ros 参数不为 NULL 且函数成功， 则 Ros 参数指向的缓冲区应包含 TCP_ESTATS_SND_CONG_ROS_v0 结构。 如果为此 TCP 连接启用了发送方拥塞信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_SND_CONG_ROD_v0 结构。 |
|
此值请求 TCP 连接的扩展路径度量信息。
此枚举值只能使用只读动态信息和读/写信息。 如果 Rw 参数不为 NULL 且函数成功， 则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_PATH_RW_v0 结构。 如果为此 TCP 连接启用了扩展路径度量信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_PATH_ROD_v0 结构。 |
|
此值请求 TCP 连接的扩展输出队列信息。
此枚举值只能使用只读动态信息和读/写信息。 如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_SEND_BUFF_RW_v0 结构。 如果为此 TCP 连接启用了扩展输出队列信息，则 Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_SEND_BUFF_ROD_v0 结构。 |
|
此值请求 TCP 连接的扩展本地接收器信息。
此枚举值只能使用只读动态信息和读/写信息。 如果 Rw 参数不为 NULL 且函数成功， 则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_REC_RW_v0 结构。 如果为此 TCP 连接启用了扩展的本地接收器信息， Rod 参数不为 NULL，并且函数成功， 则 Rod 参数指向的缓冲区应包含 TCP_ESTATS_REC_ROD_v0 结构。 |
|
此值请求 TCP 连接的扩展远程接收方信息。
此枚举值只能使用只读动态信息和读/写信息。 如果 Rw 参数不为 NULL 且函数成功， 则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_OBS_REC_RW_v0 结构。 如果为此 TCP 连接启用了扩展远程接收器信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_OBS_REC_ROD_v0 结构。 |
|
此值请求带宽上的 TCP 连接的带宽估计统计信息。
此枚举值只能使用只读动态信息和读/写信息。 如果 Rw 参数不为 NULL 且函数成功， 则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_BANDWIDTH_RW_v0 结构。 如果为此 TCP 连接启用了带宽估计统计信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_BANDWIDTH_ROD_v0 结构。 |
|
此值请求 TCP 连接的精细往返时间 (RTT) 估计统计信息。
此枚举值只能使用只读动态信息和读/写信息。 如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_FINE_RTT_RW_v0 结构。 如果为此 TCP 连接启用了细粒度 RTT 估计统计信息， Rod 参数不为 NULL，并且函数成功， 则 Rod 参数指向的缓冲区应包含 TCP_ESTATS_FINE_RTT_ROD_v0 结构。 |
[out] Rw
指向用于接收读/写信息的缓冲区的指针。 如果应用程序不想检索 TCP 连接的读/写信息，此参数可能是 NULL 指针。
RwVersion
请求的读/写信息的版本。 当前支持的值为 0 的版本。
RwSize
Rw 参数指向的缓冲区的大小（以字节为单位）。
[out] Ros
指向用于接收只读静态信息的缓冲区的指针。 如果应用程序不想检索 TCP 连接的只读静态信息，此参数可能是 NULL 指针。
RosVersion
请求的只读静态信息的版本。 当前支持的值为 0 的版本。
RosSize
Ros 参数指向的缓冲区的大小（以字节为单位）。
[out] Rod
指向用于接收只读动态信息的缓冲区的指针。 如果应用程序不想检索 TCP 连接的只读动态信息，此参数可能是 NULL 指针。
RodVersion
请求的只读动态信息的版本。 当前支持的值为 0 的版本。
RodSize
Rod 参数指向的缓冲区的大小（以字节为单位）。
返回值
如果函数成功，则返回值NO_ERROR。
如果函数失败，则返回值为以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
传递给函数的缓冲区太小。 如果 Rw、 Ros 或 Rod 参数指向的缓冲区不够大，无法接收数据，则返回此错误。 如果 Rw、Ros 或 Rod 参数指向的给定缓冲区之一为 NULL，但在关联的 RwSize、RosSize 或 RodSize 中指定了长度，则也会返回此错误。
此错误值在 Windows Vista 和 Windows Server 2008 上返回。 |
|
参数不正确。 如果 Row 参数为 NULL 指针，则返回此错误。 |
|
提供给请求操作的用户缓冲区无效。 如果 Rw、Ros 或 Rod 参数指向的给定缓冲区之一为 NULL，但在关联的 RwSize、RosSize 或 RodSize 中指定了长度，则返回此错误。 因此，如果满足以下任一条件，则返回此错误：
此错误值在 Windows 7 和 Windows Server 2008 R2 上返回。 |
|
找不到此请求的条目。 如果找不到 Row 参数中指定的 TCP 连接，则返回此错误。 |
|
不支持该请求。 如果 RwVersion、 RosVersion 或 RodVersion 参数未设置为零，则返回此错误。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
GetPerTcpConnectionEStats 函数在 Windows Vista 及更高版本上定义。
GetPerTcpConnectionEStats 函数旨在使用 TCP 诊断网络和应用程序中的性能问题。 如果基于网络的应用程序性能不佳，TCP 可以确定瓶颈是在发送方、接收方还是网络本身。 如果瓶颈在网络中，TCP 可以提供有关其性质的特定信息。
GetPerTcpConnectionEStats 函数检索 Row 参数中传递的 IPv4 TCP 连接的扩展统计信息。 检索的扩展统计信息的类型在 EstatsType 参数中指定。 以前必须通过调用 SetPerTcpConnectionEStats 函数为所有TCP_ESTATS_TYPE值启用此 TCP 连接的扩展统计信息，除非在 EstatsType 参数中传递 TcpConnectionEstatsSynOpts。
GetTcpTable 函数用于检索本地计算机上的 IPv4 TCP 连接表。 此函数返回包含 MIB_TCPROW 项数组的 MIB_TCPTABLE 结构。 传递给 GetPerTcpConnectionEStats 函数的 Row 参数必须是现有 IPv4 TCP 连接的条目。
当前支持的唯一 TCP 连接统计信息版本为版本零。 因此，传递给 GetPerTcpConnectionEStats 的RwVersion、RosVersion 和 RodVersion 参数应设置为 0。
有关 IPv6 连接的扩展 TCP 统计信息的信息，请参阅 GetPerTcp6ConnectionEStats 和 SetPerTcp6ConnectionEStats 函数。
SetPerTcpConnectionEStats 函数只能由以 Administrators 组成员身份登录的用户调用。 如果 SetPerTcpConnectionEStats 由不是 Administrators 组成员的用户调用，则函数调用将失败并返回 ERROR_ACCESS_DENIED 。 此函数也可能因为 Windows Vista 及更高版本上的用户帐户控制 (UAC) 而失败。 如果包含此函数的应用程序由以管理员组成员身份登录（而不是内置管理员）的用户执行，则此调用将失败，除非应用程序已在清单文件中标记为 requestedExecutionLevel 设置为 requireAdministrator。 如果应用程序缺少此清单文件，则作为管理员组成员（而不是内置管理员）登录的用户必须在增强的 shell 中执行应用程序，因为内置管理员 (RunAs 管理员) 此函数才能成功。
GetPerTcpConnectionEStats 的调用方应在返回的 Rw 结构中检查 EnableCollection 字段，如果不是 TRUE，则调用方应忽略 Ros 和 Rod 结构中的数据。 如果 EnableCollection 设置为 FALSE，则 Ros 和 Rod 中返回的数据未定义。 例如，发生这种情况的一个条件是，使用 GetPerTcpConnectionEStats 检索 IPv4 TCP 连接的扩展统计信息，并且之前调用 SetPerTcpConnectionEStats 来启用扩展统计信息。 如果 SetPerTcpConnectionEStats 调用失败，则对 GetPerTcpConnectionEStats 的 后续调用将返回无意义的随机数据，而不是扩展的 TCP 统计信息。 可以通过以管理员和普通用户身份运行以下示例来观察该示例。
示例
有关代码示例，请参阅 GetPerTcp6ConnectionEStats 函数主题中的示例部分。
要求
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | iphlpapi.h |
| Library | Iphlpapi.lib |
| DLL | Iphlpapi.dll |