Função GetIpNetworkConnectionBandwidthEstimates (netioapi.h)

Artigo
08/25/2023

A função GetIpNetworkConnectionBandwidthEstimates recupera estimativas históricas de largura de banda para uma conexão de rede na interface especificada.

Sintaxe

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

Parâmetros

[in] InterfaceIndex

O valor do índice local para o adaptador de rede.

Esse valor de índice pode ser alterado quando um adaptador de rede é desabilitado e, em seguida, habilitado ou em outras circunstâncias, e não deve ser considerado persistente.

[in] AddressFamily

A família de endereços. Os valores possíveis para a família de endereços são listados no arquivo de cabeçalho Ws2def.h . Observe que os valores para a família de endereços AF_ e PF_ constantes da família de protocolos são idênticos (por exemplo, AF_INET e PF_INET), portanto, qualquer constante pode ser usada.

Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente no Winsock2.h e nunca deve ser usado diretamente.

Os valores com suporte no momento são AF_INET ou AF_INET6, que são os formatos de família de endereços da Internet para IPv4 e IPv6.

Valor	Significado
AF_INET 2	A família de endereços IPv4 (Protocolo de Internet versão 4).
AF_INET6 23	A família de endereços IPv6 (Internet Protocol versão 6).

[out] BandwidthEstimates

Um ponteiro para um buffer que retorna as estimativas de largura de banda históricas mantidas para o ponto de anexo ao qual a interface está conectada no momento.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos códigos de erro a seguir.

Código de retorno	Descrição
ERROR_FILE_NOT_FOUND	O sistema não pode encontrar o arquivo especificado. Esse erro será retornado se o índice de interface especificado pelo parâmetro InterfaceIndex não for um valor no computador local.
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se um ponteiro NULL for passado no parâmetro BandwidthEstimates ou o parâmetro AddressFamily não tiver sido especificado como AF_INET ou AF_INET6.
ERROR_NOT_FOUND	Elemento não encontrado. Esse erro será retornado se o adaptador de rede especificado pelo parâmetro InterfaceIndex não corresponder à família de endereços IP especificada no parâmetro AddressFamily .
Outros	Use a função FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função GetIpNetworkConnectionBandwidthEstimates é definida em Windows 8 e posterior.

Na entrada, o parâmetro AddressFamily deve ser inicializado para AF_INET ou AF_INET6. Além da entrada, o parâmetro InterfaceIndex deve ser inicializado com o índice de interface especificado.

Um valor deve ser definido para o parâmetro InterfaceIndex (o valor desse parâmetro não deve ser definido como zero).

Na saída, a estrutura MIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES apontada pelo parâmetro BandwidthEstimates será preenchida se os parâmetros AddressFamily e InterfaceIndex forem especificados.

A função GetIpNetworkConnectionBandwidthEstimates retorna estimativas históricas de largura de banda disponível no ponto de anexo (o primeiro salto) para uso por um aplicativo. As estimativas são destinadas como um guia para ajustar parâmetros de desempenho e o aplicativo deve manter limites e diferenciar o comportamento para situações de baixa e alta largura de banda.

É possível que a verdadeira largura de banda disponível mude ao longo do tempo à medida que mais largura de banda é consumida por dispositivos que competem na mesma rede. Portanto, os aplicativos devem estar preparados para lidar com casos em que a largura de banda disponível fique abaixo dos limites históricos relatados pela função GetIpNetworkConnectionBandwidthEstimates .

É possível que a pilha TCP/IP não tenha criado nenhuma estimativa para a interface fornecida, em uma direção específica ou em ambas as direções. Nesse caso, a estimativa retornada será zero. O aplicativo deve estar preparado para lidar com esses casos escolhendo padrões razoáveis e ajuste fino, se necessário.

O arquivo de cabeçalho Netioapi.h é incluído automaticamente pelo arquivo de cabeçalho Iphlpapi.h . O arquivo de cabeçalho Netioapi.h nunca deve ser usado diretamente.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	netioapi.h (inclua Iphlpapi.h)
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll