getIpNetworkConnectionBandwidthEstimates 函数 (netioapi.h)

项目
08/25/2023

GetIpNetworkConnectionBandwidthEstimates 函数检索指定接口上网络连接的历史带宽估计值。

语法

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API GetIpNetworkConnectionBandwidthEstimates(
  [in]  NET_IFINDEX                                    InterfaceIndex,
  [in]  ADDRESS_FAMILY                                 AddressFamily,
  [out] PMIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES BandwidthEstimates
);

参数

[in] InterfaceIndex

网络接口的本地索引值。

当禁用然后启用网络适配器时，或者在其他情况下，此索引值可能会更改，不应被视为永久性。

[in] AddressFamily

地址系列。 Ws2def.h 头文件中列出了地址系列的可能值。请注意，AF_地址系列和PF_协议系列常量的值 (相同，例如 ，AF_INET 和 PF_INET) ，因此可以使用任一常量。

请注意， Ws2def.h 头文件自动包含在 Winsock2.h 中，不应直接使用。

当前支持的值 是 AF_INET 或 AF_INET6，即 IPv4 和 IPv6 的 Internet 地址系列格式。

值	含义
AF_INET 2	Internet 协议版本 4 (IPv4) 地址系列。
AF_INET6 23	Internet 协议版本 6 (IPv6) 地址系列。

[out] BandwidthEstimates

指向缓冲区的指针，该缓冲区返回为接口当前连接到的附件点保留的历史带宽估计值。

返回值

如果函数成功，则返回值NO_ERROR。

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

返回代码	说明
ERROR_FILE_NOT_FOUND	系统找不到指定的文件。如果 InterfaceIndex 参数指定的接口索引不是本地计算机上的值，则返回此错误。
ERROR_INVALID_PARAMETER	向该函数传递了无效参数。如果在 BandwidthEstimates 参数中传递 NULL 指针，或者 AddressFamily 参数未指定为 AF_INET 或 AF_INET6，则返回此错误。
ERROR_NOT_FOUND	找不到元素。如果 InterfaceIndex 参数指定的网络接口与 AddressFamily 参数中指定的 IP 地址系列不匹配，则返回此错误。
其他	使用 FormatMessage 函数获取返回错误的消息字符串。

注解

GetIpNetworkConnectionBandwidthEstimates 函数在 Windows 8 及更高版本上定义。

输入时， AddressFamily 参数必须初始化为 AF_INET 或 AF_INET6。此外，在输入时，必须使用指定的接口索引初始化 InterfaceIndex 参数。

必须为 InterfaceIndex 参数设置值 (此参数的值不得设置为零) 。

在输出时，如果指定了 AddressFamily 和 InterfaceIndex 参数，则填充 BandwidthEstimates 参数指向的MIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES结构。

GetIpNetworkConnectionBandwidthEstimates 函数返回附件 (第一个跃点) 供应用程序使用的可用带宽的历史估计值。这些估计值旨在作为优化性能参数的指南，应用程序应维护阈值并区分低带宽和高带宽情况的行为。

随着在同一网络上竞争的设备消耗更多带宽，真正的可用带宽可能会随时间而改变。因此，应用程序应准备好处理可用带宽低于 GetIpNetworkConnectionBandwidthEstimates 函数报告的历史限制的情况。

TCP/IP 堆栈可能未在特定或双向方向上为给定接口生成任何估计值。在这种情况下，返回的估计值为零。应用程序应准备好通过选择合理的默认值和微调（如果需要）来处理此类情况。

Netioapi.h 头文件自动包含在 Iphlpapi.h 头文件中。永远不应直接使用 Netioapi.h 头文件。

要求

要求	值
最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	netioapi.h (包括 Iphlpapi.h)
Library	Iphlpapi.lib
DLL	Iphlpapi.dll