GetAdaptersInfo 函式 (iphlpapi.h)
GetAdaptersInfo函式會擷取本機電腦的配接器資訊。
在 Windows XP 和更新版本上： 使用 GetAdaptersAddresses 函式，而不是 GetAdaptersInfo。
語法
IPHLPAPI_DLL_LINKAGE ULONG GetAdaptersInfo(
[out] PIP_ADAPTER_INFO AdapterInfo,
[in, out] PULONG SizePointer
);
參數
[out] AdapterInfo
接收 IP_ADAPTER_INFO 結構連結清單之緩衝區的指標。
[in, out] SizePointer
ULONG變數的指標，指定pAdapterInfo參數指向的緩衝區大小。 如果這個大小不足以保存配接器資訊， GetAdaptersInfo 會以所需的大小填入此變數，並傳回 錯誤碼ERROR_BUFFER_OVERFLOW。
傳回值
如果函式成功，傳回值 會ERROR_SUCCESS (定義為 與NO_ERROR) 相同的值。
如果函式失敗，傳回值就是下列其中一個錯誤碼。
| 傳回碼 | 描述 |
|---|---|
|
接收配接器資訊的緩衝區太小。 如果 pOutBufLen 參數所指示的緩衝區大小太小而無法保存配接器資訊，或 pAdapterInfo 參數是 Null 指標，則會傳回這個值。 傳回此錯誤碼時， pOutBufLen 參數會指向所需的緩衝區大小。 |
|
已擷取不正確配接器資訊。 |
|
其中一個參數無效。 如果 pOutBufLen 參數是 Null 指標，或者呼叫進程沒有 pOutBufLen 所指向之記憶體的讀取/寫入存取權，或呼叫進程沒有 pAdapterInfo 參數所指向之記憶體的寫入權限，就會傳回此錯誤。 |
|
本機電腦沒有配接器資訊。 |
|
本機電腦上執行的作業系統不支援 GetAdaptersInfo 函式。 |
|
如果函式失敗，請使用 FormatMessage 取得傳回錯誤的訊息字串。 |
備註
GetAdaptersInfo函式只能擷取 IPv4 位址的資訊。
在Windows 10之前的版本中，此函式所傳回清單中顯示介面卡的順序可以從 [網路連線] 資料夾控制：從 [進階] 功能表中選取 [進階設定] 功能表項目。 從 Windows 10 開始，不會指定順序。
GetAdaptersInfo和GetInterfaceInfo函式不會傳回 IPv4 回送介面的相關資訊。 GetIpAddrTable函式會傳回回回送介面的相關資訊。
在 Windows XP 和更新版本上：GetAdaptersInfo所傳回的配接器清單包含單向介面卡。 若要產生可同時傳送和接收資料的配接器清單，請呼叫 GetUniDirectionalAdapterInfo，並從 GetAdaptersInfo傳回的清單中排除傳回的配接器。
範例
此範例會擷取配接器資訊，並列印每個介面卡的各種屬性。
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.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 __cdecl main()
{
/* Declare and initialize variables */
// It is possible for an adapter to have multiple
// IPv4 addresses, gateways, and secondary WINS servers
// assigned to the adapter.
//
// Note that this sample code only prints out the
// first entry for the IP address/mask, and gateway, and
// the primary and secondary WINS server for each adapter.
PIP_ADAPTER_INFO pAdapterInfo;
PIP_ADAPTER_INFO pAdapter = NULL;
DWORD dwRetVal = 0;
UINT i;
/* variables used to print DHCP time info */
struct tm newtime;
char buffer[32];
errno_t error;
ULONG ulOutBufLen = sizeof (IP_ADAPTER_INFO);
pAdapterInfo = (IP_ADAPTER_INFO *) MALLOC(sizeof (IP_ADAPTER_INFO));
if (pAdapterInfo == NULL) {
printf("Error allocating memory needed to call GetAdaptersinfo\n");
return 1;
}
// Make an initial call to GetAdaptersInfo to get
// the necessary size into the ulOutBufLen variable
if (GetAdaptersInfo(pAdapterInfo, &ulOutBufLen) == ERROR_BUFFER_OVERFLOW) {
FREE(pAdapterInfo);
pAdapterInfo = (IP_ADAPTER_INFO *) MALLOC(ulOutBufLen);
if (pAdapterInfo == NULL) {
printf("Error allocating memory needed to call GetAdaptersinfo\n");
return 1;
}
}
if ((dwRetVal = GetAdaptersInfo(pAdapterInfo, &ulOutBufLen)) == NO_ERROR) {
pAdapter = pAdapterInfo;
while (pAdapter) {
printf("\tComboIndex: \t%d\n", pAdapter->ComboIndex);
printf("\tAdapter Name: \t%s\n", pAdapter->AdapterName);
printf("\tAdapter Desc: \t%s\n", pAdapter->Description);
printf("\tAdapter Addr: \t");
for (i = 0; i < pAdapter->AddressLength; i++) {
if (i == (pAdapter->AddressLength - 1))
printf("%.2X\n", (int) pAdapter->Address[i]);
else
printf("%.2X-", (int) pAdapter->Address[i]);
}
printf("\tIndex: \t%d\n", pAdapter->Index);
printf("\tType: \t");
switch (pAdapter->Type) {
case MIB_IF_TYPE_OTHER:
printf("Other\n");
break;
case MIB_IF_TYPE_ETHERNET:
printf("Ethernet\n");
break;
case MIB_IF_TYPE_TOKENRING:
printf("Token Ring\n");
break;
case MIB_IF_TYPE_FDDI:
printf("FDDI\n");
break;
case MIB_IF_TYPE_PPP:
printf("PPP\n");
break;
case MIB_IF_TYPE_LOOPBACK:
printf("Loopback\n");
break;
case MIB_IF_TYPE_SLIP:
printf("Slip\n");
break;
default:
printf("Unknown type %ld\n", pAdapter->Type);
break;
}
printf("\tIP Address: \t%s\n",
pAdapter->IpAddressList.IpAddress.String);
printf("\tIP Mask: \t%s\n", pAdapter->IpAddressList.IpMask.String);
printf("\tGateway: \t%s\n", pAdapter->GatewayList.IpAddress.String);
printf("\t***\n");
if (pAdapter->DhcpEnabled) {
printf("\tDHCP Enabled: Yes\n");
printf("\t DHCP Server: \t%s\n",
pAdapter->DhcpServer.IpAddress.String);
printf("\t Lease Obtained: ");
/* Display local time */
error = _localtime32_s(&newtime, (__time32_t*) &pAdapter->LeaseObtained);
if (error)
printf("Invalid Argument to _localtime32_s\n");
else {
// Convert to an ASCII representation
error = asctime_s(buffer, 32, &newtime);
if (error)
printf("Invalid Argument to asctime_s\n");
else
/* asctime_s returns the string terminated by \n\0 */
printf("%s", buffer);
}
printf("\t Lease Expires: ");
error = _localtime32_s(&newtime, (__time32_t*) &pAdapter->LeaseExpires);
if (error)
printf("Invalid Argument to _localtime32_s\n");
else {
// Convert to an ASCII representation
error = asctime_s(buffer, 32, &newtime);
if (error)
printf("Invalid Argument to asctime_s\n");
else
/* asctime_s returns the string terminated by \n\0 */
printf("%s", buffer);
}
} else
printf("\tDHCP Enabled: No\n");
if (pAdapter->HaveWins) {
printf("\tHave Wins: Yes\n");
printf("\t Primary Wins Server: %s\n",
pAdapter->PrimaryWinsServer.IpAddress.String);
printf("\t Secondary Wins Server: %s\n",
pAdapter->SecondaryWinsServer.IpAddress.String);
} else
printf("\tHave Wins: No\n");
pAdapter = pAdapter->Next;
printf("\n");
}
} else {
printf("GetAdaptersInfo failed with error: %d\n", dwRetVal);
}
if (pAdapterInfo)
FREE(pAdapterInfo);
return 0;
}
需求
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | iphlpapi.h |
| 程式庫 | Iphlpapi.lib |
| Dll | Iphlpapi.dll |