getInterfaceInfo 函式 (iphlpapi.h)
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。
如果函式失敗，傳回值就是下列其中一個錯誤碼。
| 傳回碼 | 描述 |
|---|---|
|
接收 IPv4 配接器資訊的緩衝區太小。 如果 dwOutBufLen 參數指出 pIfTable 參數指向的緩衝區太小而無法擷取 IPv4 介面資訊，則會傳回此值。 所需的大小會在dwOutBufLen參數所指向的DWORD變數中傳回。 |
|
不正確參數已傳遞至 函式。 如果 dwOutBufLen 參數為 Null，或 GetInterfaceInfo 無法寫入 dwOutBufLen 參數所指向的記憶體，就會傳回此錯誤。 |
|
本機系統上沒有啟用 IPv4 的網路介面卡。 如果停用本機系統上的所有網路介面卡，也會傳回此值。 |
|
本機系統上使用的作業系統不支援此函式。 |
|
使用 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 |