Funzione GetIpNetworkConnectionBandwidthEstimates (netioapi.h)

Articolo
02/29/2024

La funzione GetIpNetworkConnectionBandwidthEstimates recupera le stime cronologiche della larghezza di banda per una connessione di rete nell'interfaccia specificata.

Sintassi

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

Parametri

[in] InterfaceIndex

Valore dell'indice locale per l'interfaccia di rete.

Questo valore di indice può cambiare quando una scheda di rete è disabilitata e quindi abilitata o in altre circostanze e non deve essere considerata persistente.

[in] AddressFamily

Famiglia di indirizzi. I valori possibili per la famiglia di indirizzi sono elencati nel file di intestazione Ws2def.h . Si noti che i valori per la famiglia di indirizzi AF_ e le costanti della famiglia di protocolli PF_ sono identiche (ad esempio, AF_INET e PF_INET), in modo che sia possibile usare entrambe le costanti.

Si noti che il file di intestazione Ws2def.h viene automaticamente incluso in Winsock2.h e non deve mai essere usato direttamente.

I valori attualmente supportati sono AF_INET o AF_INET6, ovvero i formati della famiglia di indirizzi Internet per IPv4 e IPv6.

Valore	Significato
AF_INET 2	Famiglia di indirizzi IPv4 (Internet Protocol versione 4).
AF_INET6 23	Famiglia di indirizzi IPv6 (Internet Protocol versione 6).

[out] BandwidthEstimates

Puntatore a un buffer che restituisce le stime della larghezza di banda cronologiche mantenute per il punto di allegato a cui è attualmente connessa l'interfaccia.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene NO_ERROR.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_FILE_NOT_FOUND	Non è possibile trovare il file specificato. Questo errore viene restituito se l'indice dell'interfaccia specificato dal parametro InterfaceIndex non è un valore nel computer locale.
ERROR_INVALID_PARAMETER	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se un puntatore NULL viene passato nel parametro BandwidthEstimates o se il parametro AddressFamily non è stato specificato come AF_INET o AF_INET6.
ERROR_NOT_FOUND	Element not found. Questo errore viene restituito se l'interfaccia di rete specificata dal parametro InterfaceIndex non corrisponde alla famiglia di indirizzi IP specificata nel parametro AddressFamily .
Altri	Utilizzare la funzione FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

La funzione GetIpNetworkConnectionBandwidthEstimates viene definita in Windows 8 e versioni successive.

In input, il parametro AddressFamily deve essere inizializzato in AF_INET o AF_INET6. Inoltre, all'input, il parametro InterfaceIndex deve essere inizializzato con l'indice di interfaccia specificato.

È necessario impostare un valore per il parametro InterfaceIndex (il valore di questo parametro non deve essere impostato su zero).

Nell'output, la struttura MIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES a cui punta il parametro BandwidthEstimates viene compilata se sono stati specificati i parametri AddressFamily e InterfaceIndex .

La funzione GetIpNetworkConnectionBandwidthEstimates restituisce stime cronologiche della larghezza di banda disponibile al punto di allegato (primo hop) da usare da un'applicazione. Le stime sono concepite come guida per ottimizzare i parametri delle prestazioni e l'applicazione deve mantenere le soglie e distinguere il comportamento per situazioni di larghezza di banda bassa e elevata.

È possibile che la vera larghezza di banda disponibile cambi nel tempo man mano che più larghezza di banda viene utilizzata dai dispositivi concorrenti nella stessa rete. Le applicazioni devono quindi essere preparate a gestire i casi in cui la larghezza di banda disponibile scende al di sotto dei limiti cronologici segnalati dalla funzione GetIpNetworkConnectionBandwidthEstimates .

È possibile che lo stack TCP/IP non abbia creato stime per l'interfaccia specificata, in una particolare o in entrambe le direzioni. In questo caso la stima restituita sarà zero. L'applicazione deve essere pronta a gestire tali casi selezionando impostazioni predefinite ragionevoli e ottimizzando se necessario.

Il file di intestazione Netioapi.h viene incluso automaticamente dal file di intestazione Iphlpapi.h . Il file di intestazione Netioapi.h non deve mai essere usato direttamente.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	netioapi.h (include Iphlpapi.h)
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll