getInterfaceInfo 函式 (iphlpapi.h)

發行項
08/24/2023

GetInterfaceInfo函式會取得本機系統上啟用 IPv4 的網路介面介面卡清單。

語法

IPHLPAPI_DLL_LINKAGE DWORD GetInterfaceInfo(
  [out]     PIP_INTERFACE_INFO pIfTable,
  [in, out] PULONG             dwOutBufLen
);

參數

[out] pIfTable

緩衝區的指標，指定接收配接器清單的IP_INTERFACE_INFO 結構。呼叫端必須配置這個緩衝區。

[in, out] dwOutBufLen

DWORD變數的指標，指定pIfTable參數所指向的緩衝區大小，以接收IP_INTERFACE_INFO結構。如果這個大小不足以保存 IPv4 介面資訊， GetInterfaceInfo 會以所需的大小填入此變數，並傳回 錯誤碼ERROR_INSUFFICIENT_BUFFER。

傳回值

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

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

傳回碼	描述
ERROR_INSUFFICIENT_BUFFER	接收 IPv4 配接器資訊的緩衝區太小。如果 dwOutBufLen 參數指出 pIfTable 參數指向的緩衝區太小而無法擷取 IPv4 介面資訊，則會傳回此值。所需的大小會在dwOutBufLen參數所指向的DWORD變數中傳回。
ERROR_INVALID_PARAMETER	不正確參數已傳遞至函式。如果 dwOutBufLen 參數為 Null，或 GetInterfaceInfo 無法寫入 dwOutBufLen 參數所指向的記憶體，就會傳回此錯誤。
ERROR_NO_DATA	本機系統上沒有啟用 IPv4 的網路介面卡。如果停用本機系統上的所有網路介面卡，也會傳回此值。
ERROR_NOT_SUPPORTED	本機系統上使用的作業系統不支援此函式。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

GetInterfaceInfo函式專屬於已啟用 IPv4 的網路介面卡。函式會傳回pIfTable參數指向的IP_INTERFACE_INFO結構，其中包含本機系統上已啟用 IPv4 的網路介面卡數目，以及已啟用 IPv4 之每個網路介面卡資訊的IP_ADAPTER_INDEX_MAP結構陣列。 GetInterfaceInfo所傳回的IP_INTERFACE_INFO結構至少包含一個IP_ADAPTER_INDEX_MAP結構，即使IP_INTERFACE_INFO結構的NumAdapters成員表示未啟用任何具有 IPv4 的網路介面卡也一樣。當GetInterfaceInfo所傳回之IP_INTERFACE_INFO結構的NumAdapters成員為零時，未定義IP_INTERFACE_INFO結構中所傳回之單一IP_ADAPTER_INDEX_MAP結構的成員值。

如果 呼叫 GetInterfaceInfo 函式時使用太小的緩衝區來擷取 IPv4 介面資訊， (dwOutBufLen 參數指出 pIfTable 參數所指向的緩衝區太小) ，則函式會 傳回ERROR_INSUFFICIENT_BUFFER。所需的大小會在dwOutBufLen參數所指向的DWORD變數中傳回。

使用 GetInterfaceInfo 函式的正確方式是呼叫此函式兩次。在第一次呼叫中，傳遞pIfTable參數中的Null指標，並在dwOutBufLen參數指向的變數中傳遞零。呼叫會因為ERROR_INSUFFICIENT_BUFFER而失敗，而且此緩衝區的必要大小會在dwOutBufLen參數指向的DWORD變數中傳回。接著，您可以使用 dwOutBufLen所指向的值來配置所需大小的緩衝區。然後，第二次呼叫 GetInterfaceInfo 函式時，可以使用 pIfTable 參數中傳遞的這個緩衝區指標，以及設定為此緩衝區大小的緩衝區長度。

GetAdaptersInfo和GetInterfaceInfo函式不會傳回回送介面的相關資訊。 GetIpAddrTable函式會傳回回回送介面的相關資訊。

在 Windows Vista 和更新版本上，IP_INTERFACE_INFO結構中傳回之IP_ADAPTER_INDEX_MAP結構的Name成員可能是網路介面的 Unicode 字串， (字串開頭為 '{' 字元) 。

範例

下列範例會擷取本機系統上已啟用 IPv4 的網路介面卡清單，並列印第一張網路介面卡的各種屬性。

#include <winsock2.h>
#include <ws2ipdef.h>
#include <iphlpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x)) 
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int main()
{

// Declare and initialize variables
    PIP_INTERFACE_INFO pInfo = NULL;
    ULONG ulOutBufLen = 0;

    DWORD dwRetVal = 0;
    int iReturn = 1;

    int i;

// Make an initial call to GetInterfaceInfo to get
// the necessary size in the ulOutBufLen variable
    dwRetVal = GetInterfaceInfo(NULL, &ulOutBufLen);
    if (dwRetVal == ERROR_INSUFFICIENT_BUFFER) {
        pInfo = (IP_INTERFACE_INFO *) MALLOC(ulOutBufLen);
        if (pInfo == NULL) {
            printf
                ("Unable to allocate memory needed to call GetInterfaceInfo\n");
            return 1;
        }
    }
// Make a second call to GetInterfaceInfo to get
// the actual data we need
    dwRetVal = GetInterfaceInfo(pInfo, &ulOutBufLen);
    if (dwRetVal == NO_ERROR) {
        printf("Number of Adapters: %ld\n\n", pInfo->NumAdapters);
        for (i = 0; i < pInfo->NumAdapters; i++) {
            printf("Adapter Index[%d]: %ld\n", i,
                   pInfo->Adapter[i].Index);
            printf("Adapter Name[%d]: %ws\n\n", i,
                   pInfo->Adapter[i].Name);
        }
        iReturn = 0;
    } else if (dwRetVal == ERROR_NO_DATA) {
        printf
            ("There are no network adapters with IPv4 enabled on the local system\n");
        iReturn = 0;
    } else {
        printf("GetInterfaceInfo failed with error: %d\n", dwRetVal);
        iReturn = 1;
    }

    FREE(pInfo);
    return (iReturn);
}

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	iphlpapi.h
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll