getIpNetworkConnectionBandwidthEstimates 函式 (netioapi.h)

發行項
03/05/2024

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	因特網通訊協定第 4 版 (IPv4) 位址系列。
AF_INET6 23	因特網通訊協定第 6 版 (IPv6) 位址系列。

[out] BandwidthEstimates

緩衝區的指標，這個緩衝區會針對介面目前連接的附件點所維護的歷程記錄頻寬估計值。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，傳回值就是下列其中一個錯誤碼。

傳回碼	Description
ERROR_FILE_NOT_FOUND	系統找不到指定的檔案。如果 InterfaceIndex 參數指定的介面索引不是本機電腦上的值，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	無效的參數已傳遞至函式。如果在 BandwidthEstimates 參數中傳遞 NULL 指標，或 AddressFamily 參數未指定為 AF_INET 或 AF_INET6，則會傳回此錯誤。
ERROR_NOT_FOUND	Element not found. 如果 InterfaceIndex 參數指定的網路介面不符合 AddressFamily 參數中指定的 IP 位址系列，就會傳回此錯誤。
其他	使用 FormatMessage 函式來取得傳回錯誤的訊息字串。

備註

GetIpNetworkConnectionBandwidthEstimates 函式是在 Windows 8 和更新版本上定義。

在輸入時， AddressFamily 參數必須初始化為 AF_INET 或 AF_INET6。除了輸入之外， InterfaceIndex 參數也必須使用指定的介面索引初始化。

您必須為 InterfaceIndex 參數設定值， (此參數的值不得設定為零) 。

輸出時，如果已指定 AddressFamily 和 InterfaceIndex 參數，則會填入 BandwidthEstimates 參數所指向的MIB_IP_NETWORK_CONNECTION_BANDWIDTH_ESTIMATES結構。

GetIpNetworkConnectionBandwidthEstimates 函式會在附件 (第一個躍點) 傳回可用頻寬的歷史估計值，以供應用程式使用。估計值旨在作為調整效能參數的指南，而應用程式應維持閾值，並區分低頻寬和高頻寬情況的行為。

因為同一網路上競爭的裝置會耗用更多頻寬，所以真正的可用頻寬會隨著時間而變更。因此，應用程式應該準備好處理可用頻寬低於 GetIpNetworkConnectionBandwidthEstimates 函式所報告歷史限制的情況。

TCP/IP 堆疊可能尚未針對特定或雙向建置指定介面的任何估計值。在此情況下，傳回的估計值會是零。應用程式應該藉由挑選合理的預設值並視需要微調，來準備處理這類案例。

Netioapi.h 頭文件會自動包含在 Iphlpapi.h 頭文件內。不應該直接使用 Netioapi.h 頭檔。

規格需求

需求	值
最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
目標平台	Windows
標頭	netioapi.h (包含 Iphlpapi.h)
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll