GetPerTcpConnectionEStats 函数 (iphlpapi.h)

项目
08/24/2023

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 枚举类型的值之一。

值	含义
TcpConnectionEstatsSynOpts	此值请求 TCP 连接的 SYN 交换信息。此枚举值仅提供只读静态信息。如果 Ros 参数不为 NULL 且函数成功，则 Ros 参数指向的缓冲区应包含 TCP_ESTATS_SYN_OPTS_ROS_v0 结构。
TcpConnectionEstatsData	此值请求 TCP 连接的扩展数据传输信息。此枚举值只能使用只读动态信息和读/写信息。如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_DATA_RW_v0 结构。如果为此 TCP 连接启用了扩展数据传输信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_DATA_ROD_v0 结构。
TcpConnectionEstatsSndCong	此值请求 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 结构。
TcpConnectionEstatsPath	此值请求 TCP 连接的扩展路径度量信息。此枚举值只能使用只读动态信息和读/写信息。如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_PATH_RW_v0 结构。如果为此 TCP 连接启用了扩展路径度量信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_PATH_ROD_v0 结构。
TcpConnectionEstatsSendBuff	此值请求 TCP 连接的扩展输出队列信息。此枚举值只能使用只读动态信息和读/写信息。如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_SEND_BUFF_RW_v0 结构。如果为此 TCP 连接启用了扩展输出队列信息，则 Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_SEND_BUFF_ROD_v0 结构。
TcpConnectionEstatsRec	此值请求 TCP 连接的扩展本地接收器信息。此枚举值只能使用只读动态信息和读/写信息。如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_REC_RW_v0 结构。如果为此 TCP 连接启用了扩展的本地接收器信息， Rod 参数不为 NULL，并且函数成功，则 Rod 参数指向的缓冲区应包含 TCP_ESTATS_REC_ROD_v0 结构。
TcpConnectionEstatsObsRec	此值请求 TCP 连接的扩展远程接收方信息。此枚举值只能使用只读动态信息和读/写信息。如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_OBS_REC_RW_v0 结构。如果为此 TCP 连接启用了扩展远程接收器信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_OBS_REC_ROD_v0 结构。
TcpConnectionEstatsBandwidth	此值请求带宽上的 TCP 连接的带宽估计统计信息。此枚举值只能使用只读动态信息和读/写信息。如果 Rw 参数不为 NULL 且函数成功，则 Rw 参数指向的缓冲区应包含 TCP_ESTATS_BANDWIDTH_RW_v0 结构。如果为此 TCP 连接启用了带宽估计统计信息， Rod 参数不为 NULL，并且函数成功， Rod 参数指向的缓冲区应包含 TCP_ESTATS_BANDWIDTH_ROD_v0 结构。
TcpConnectionEstatsFineRtt	此值请求 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。

如果函数失败，则返回值为以下错误代码之一。

返回代码	说明
ERROR_INSUFFICIENT_BUFFER	传递给函数的缓冲区太小。如果 Rw、 Ros 或 Rod 参数指向的缓冲区不够大，无法接收数据，则返回此错误。如果 Rw、Ros 或 Rod 参数指向的给定缓冲区之一为 NULL，但在关联的 RwSize、RosSize 或 RodSize 中指定了长度，则也会返回此错误。此错误值在 Windows Vista 和 Windows Server 2008 上返回。
ERROR_INVALID_PARAMETER	参数不正确。如果 Row 参数为 NULL 指针，则返回此错误。
ERROR_INVALID_USER_BUFFER	提供给请求操作的用户缓冲区无效。如果 Rw、Ros 或 Rod 参数指向的给定缓冲区之一为 NULL，但在关联的 RwSize、RosSize 或 RodSize 中指定了长度，则返回此错误。因此，如果满足以下任一条件，则返回此错误： Row 参数为 NULL 指针，RwSize 参数为非零值。 Ros 参数为 NULL 指针，RosSize 参数为非零值。 Rod 参数为 NULL 指针，RodSize 参数为非零值。此错误值在 Windows 7 和 Windows Server 2008 R2 上返回。
ERROR_NOT_FOUND	找不到此请求的条目。如果找不到 Row 参数中指定的 TCP 连接，则返回此错误。
ERROR_NOT_SUPPORTED	不支持该请求。如果 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