Функция 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.

Значение	Значение
AF_INET 2	Семейство адресов IPv4.
AF_INET6 23	Семейство адресов IPv6.

[out] BandwidthEstimates

Указатель на буфер, возвращающий оценки пропускной способности за прошлые периоды для точки присоединения, к которой в данный момент подключен интерфейс.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.

Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.

Код возврата	Описание
ERROR_FILE_NOT_FOUND	Системе не удается найти указанный файл. Эта ошибка возвращается, если индекс интерфейса, заданный параметром InterfaceIndex , не был значением на локальном компьютере.
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметре BandwidthEstimates передается указатель NULL или параметр AddressFamily не указан как AF_INET или AF_INET6.
ERROR_NOT_FOUND	Элемент не найден. Эта ошибка возвращается, если сетевой интерфейс, заданный параметром InterfaceIndex , не соответствует семейству IP-адресов, указанному в параметре AddressFamily .
Другое	Используйте функцию FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

При входных данных параметр AddressFamily должен быть инициализирован AF_INET или AF_INET6. В дополнение к входным данным параметр InterfaceIndex должен быть инициализирован с указанным индексом интерфейса.

Для параметра InterfaceIndex необходимо задать значение (значение этого параметра не должно быть равно нулю).

В выходных данных структура MIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES , на которую указывает параметр BandwidthEstimates , заполняется, если указаны параметры AddressFamily и InterfaceIndex .

Функция GetIpNetworkConnectionBandwidthEstimates возвращает исторические оценки доступной пропускной способности в точке вложения (первый прыжок) для использования приложением. Оценки предназначены для настройки параметров производительности, и приложение должно поддерживать пороговые значения и дифференцировать поведение в ситуациях с низкой и высокой пропускной способностью.

Возможно, что истинная доступная пропускная способность со временем изменяется, так как больше пропускной способности потребляется устройствами, конкурирующими в одной сети. Поэтому приложения должны быть готовы к обработке случаев, когда доступная пропускная способность падает ниже исторических ограничений, сообщаемых функцией GetIpNetworkConnectionBandwidthEstimates .

Возможно, стек TCP/IP не создал никаких оценок для данного интерфейса в определенном или обоих направлениях. В этом случае возвращаемая оценка будет равна нулю. Приложение должно быть готово к обработке таких случаев путем выбора разумных значений по умолчанию и точной настройки, если это необходимо.

Файл заголовка Netioapi.h автоматически включается в файл заголовка Iphlpapi.h . Файл заголовка Netioapi.h никогда не следует использовать напрямую.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 [только классические приложения]
Целевая платформа	Windows
Header	netioapi.h (включая Iphlpapi.h)
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll