GetIpNetworkConnectionBandwidthEstimates, fonction (netioapi.h)

Article
03/04/2024

La fonction GetIpNetworkConnectionBandwidthEstimates récupère les estimations de bande passante historiques pour une connexion réseau sur l’interface spécifiée.

Syntaxe

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

Paramètres

[in] InterfaceIndex

Valeur d’index local pour l’interface réseau.

Cette valeur d’index peut changer lorsqu’une carte réseau est désactivée, puis activée, ou dans d’autres circonstances, et ne doit pas être considérée comme persistante.

[in] AddressFamily

Famille d’adresses. Les valeurs possibles pour la famille d’adresses sont répertoriées dans le fichier d’en-tête Ws2def.h . Notez que les valeurs de la famille d’adresses AF_ et des constantes de famille de protocole PF_ sont identiques (par exemple , AF_INET et PF_INET), de sorte que l’une ou l’autre constante peut être utilisée.

Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.

Les valeurs actuellement prises en charge sont AF_INET ou AF_INET6, qui sont les formats de famille d’adresses Internet pour IPv4 et IPv6.

Valeur	Signification
AF_INET 2	Famille d’adresses IPv4 (Internet Protocol version 4).
AF_INET6 23	Famille d’adresses IPv6 (Internet Protocol version 6).

[out] BandwidthEstimates

Pointeur vers une mémoire tampon qui retourne les estimations de bande passante historiques conservées pour le point d’attachement auquel l’interface est actuellement connectée.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_FILE_NOT_FOUND	Le système ne peut pas trouver le fichier spécifié. Cette erreur est retournée si l’index d’interface spécifié par le paramètre InterfaceIndex n’était pas une valeur sur l’ordinateur local.
ERROR_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si un pointeur NULL est passé dans le paramètre BandwidthEstimates ou si le paramètre AddressFamily n’a pas été spécifié comme AF_INET ou AF_INET6.
ERROR_NOT_FOUND	Element not found. Cette erreur est retournée si l’interface réseau spécifiée par le paramètre InterfaceIndex ne correspond pas à la famille d’adresses IP spécifiée dans le paramètre AddressFamily .
Autres	Utilisez la fonction FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Remarques

La fonction GetIpNetworkConnectionBandwidthEstimates est définie sur Windows 8 et versions ultérieures.

Lors de l’entrée, le paramètre AddressFamily doit être initialisé en AF_INET ou AF_INET6. En plus de l’entrée, le paramètre InterfaceIndex doit être initialisé avec l’index d’interface spécifié.

Une valeur doit être définie pour le paramètre InterfaceIndex (la valeur de ce paramètre ne doit pas être définie sur zéro).

Lors de la sortie, la structure MIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES pointée par le paramètre BandwidthEstimates est renseignée si les paramètres AddressFamily et InterfaceIndex ont été spécifiés.

La fonction GetIpNetworkConnectionBandwidthEstimates retourne des estimations historiques de la bande passante disponible au point de pièce jointe (premier tronçon) pour une utilisation par une application. Les estimations sont destinées à guider l’optimisation des paramètres de performances et l’application doit maintenir des seuils et différencier le comportement pour les situations de bande passante faible et élevée.

Il est possible que la bande passante réelle disponible change au fil du temps, car davantage de bande passante est consommée par les appareils concurrents sur le même réseau. Par conséquent, les applications doivent être prêtes à gérer les cas où la bande passante disponible passe en dessous des limites historiques signalées par la fonction GetIpNetworkConnectionBandwidthEstimates .

Il est possible que la pile TCP/IP n’ait pas généré d’estimations pour l’interface donnée, dans une direction particulière ou dans les deux sens. Dans ce cas, l’estimation retournée sera égale à zéro. L’application doit être prête à gérer de tels cas en choisissant des valeurs par défaut raisonnables et un réglage précis si nécessaire.

Le fichier d’en-tête Netioapi.h est automatiquement inclus par le fichier d’en-tête Iphlpapi.h . Le fichier d’en-tête Netioapi.h ne doit jamais être utilisé directement.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	netioapi.h (include Iphlpapi.h)
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll