GetIpNetworkConnectionBandwidthEstimates function (netioapi.h)
The GetIpNetworkConnectionBandwidthEstimates function retrieves historical bandwidth estimates for a network connection on the specified interface.
Syntax
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API GetIpNetworkConnectionBandwidthEstimates(
[in] NET_IFINDEX InterfaceIndex,
[in] ADDRESS_FAMILY AddressFamily,
[out] PMIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES BandwidthEstimates
);
Parameters
[in] InterfaceIndex
The local index value for the network interface.
This index value may change when a network adapter is disabled and then enabled, or under other circumstances, and should not be considered persistent.
[in] AddressFamily
The address family. Possible values for the address family are listed in the Ws2def.h header file. Note that the values for the AF_ address family and PF_ protocol family constants are identical (for example, AF_INET and PF_INET), so either constant can be used.
Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.
The values currently supported are AF_INET or AF_INET6, which are the Internet address family formats for IPv4 and IPv6.
| Value | Meaning |
|---|---|
|
The Internet Protocol version 4 (IPv4) address family. |
|
The Internet Protocol version 6 (IPv6) address family. |
[out] BandwidthEstimates
A pointer to a buffer that returns the historical bandwidth estimates maintained for the point of attachment to which the interface is currently connected.
Return value
If the function succeeds, the return value is NO_ERROR.
If the function fails, the return value is one of the following error codes.
| Return code | Description |
|---|---|
|
The system cannot find the file specified. This error is returned if the interface index specified by the InterfaceIndex parameter was not a value on the local machine. |
|
An invalid parameter was passed to the function. This error is returned if a NULL pointer is passed in the BandwidthEstimates parameter or the AddressFamily parameter was not specified as AF_INET or AF_INET6. |
|
Element not found. This error is returned if the network interface specified by the InterfaceIndex parameter does not match the IP address family specified in the AddressFamily parameter. |
|
Use the FormatMessage function to obtain the message string for the returned error. |
Remarks
The GetIpNetworkConnectionBandwidthEstimates function is defined on Windows 8 and later.
On input, the AddressFamily parameter must be initialized to either AF_INET or AF_INET6. In addition on input, the InterfaceIndex parameter must be initialized with the specified interface index.
A value must be set for the InterfaceIndex parameter (the value of this parameter must not be set to zero).
On output, the MIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES structure pointed to by the BandwidthEstimates parameter is filled in if the AddressFamily and InterfaceIndex parameters were specified.
The GetIpNetworkConnectionBandwidthEstimates function returns historical estimates of available bandwidth at the point of attachment (the first hop) for use by an application. The estimates are intended as a guide to tune performance parameters and the application should maintain thresholds and differentiate behavior for low and high bandwidth situations.
It is possible that the true available bandwidth changes over time as more bandwidth is consumed by devices competing on the same network. So applications should be prepared to handle cases where the available bandwidth drops below historical limits reported by the GetIpNetworkConnectionBandwidthEstimates function.
It is possible that the TCP/IP stack has not built up any estimates for the given interface, in a particular or both directions. In this case the estimate returned will be zero. The application should be prepared to handle such cases by picking reasonable defaults and fine tuning if required.
The Netioapi.h header file is automatically included by the Iphlpapi.h header file. The Netioapi.h header file should never be used directly.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 [desktop apps only] |
| Minimum supported server | Windows Server 2012 [desktop apps only] |
| Target Platform | Windows |
| Header | netioapi.h (include Iphlpapi.h) |
| Library | Iphlpapi.lib |
| DLL | Iphlpapi.dll |