GetAdaptersAddresses 函式 (iphlpapi.h)
GetAdaptersAddresses函式會擷取與本機電腦上的配接器相關聯的位址。
語法
IPHLPAPI_DLL_LINKAGE ULONG GetAdaptersAddresses(
[in] ULONG Family,
[in] ULONG Flags,
[in] PVOID Reserved,
[in, out] PIP_ADAPTER_ADDRESSES AdapterAddresses,
[in, out] PULONG SizePointer
);
參數
[in] Family
要擷取之位址的位址系列。 此參數必須是下列其中一個值。
| 值 | 意義 |
|---|---|
|
傳回與已啟用 IPv4 或 IPv6 之介面卡相關聯的 IPv4 和 IPv6 位址。 |
|
只傳回與已啟用 IPv4 之介面卡相關聯的 IPv4 位址。 |
|
只傳回與已啟用 IPv6 之介面卡相關聯的 IPv6 位址。 |
[in] Flags
要擷取的網址類別型。 可能的值定義于 Iptypes.h 標頭檔中。 請注意， Iptypes.h 標頭檔會自動包含在 Iphlpapi.h中，不應直接使用。
此參數是下列值的組合。 如果此參數為零，則會傳回單播、任何播和多播 IP 位址。
[in] Reserved
目前未使用此參數，但保留供未來系統使用。 呼叫的應用程式應該傳遞此參數的 Null 。
[in, out] AdapterAddresses
緩衝區的指標，其中包含成功傳回時 IP_ADAPTER_ADDRESSES 結構的連結清單。
[in, out] SizePointer
變數的指標，指定 AdapterAddresses所指向之緩衝區的大小。
傳回值
如果函式成功，傳回值 會ERROR_SUCCESS ( 定義為與 NO_ERROR) 相同的值。
如果函式失敗，傳回值就是下列其中一個錯誤碼。
| 傳回碼 | 描述 |
|---|---|
|
位址尚未與網路端點相關聯。 DHCP 租用資訊可供使用。 |
|
SizePointer參數所指示的緩衝區大小太小，無法保存配接器資訊，或AdapterAddresses參數為Null。 SizePointer參數傳回的指向緩衝區所需的大小，以保存配接器資訊。 |
|
其中一個參數無效。 下列任一條件會傳回此錯誤： SizePointer 參數為 Null、 Address 參數未 AF_INET、 AF_INET6或 AF_UNSPEC，或所要求參數的位址資訊大於 ULONG_MAX。 |
|
記憶體資源不足，無法完成作業。 |
|
找不到所要求參數的位址。 |
|
使用 FormatMessage 取得傳回錯誤的訊息字串。 |
備註
此
GetAdaptersAddresses 函式可以擷取 IPv4 和 IPv6 位址的資訊。
位址會以AdapterAddresses參數所指向之緩衝區中IP_ADAPTER_ADDRESSES結構的連結清單傳回。 呼叫GetAdaptersAddresses函式的應用程式必須配置傳回AdapterAddresses參數所指向之IP_ADAPTER_ADDRESSES結構所需的記憶體數量。 不再需要這些傳回的結構時，應用程式應該釋放配置的記憶體。 這可以藉由呼叫 HeapAlloc 函式來配置記憶體，稍後呼叫 HeapFree 函式以釋放配置的記憶體來完成，如範例程式碼所示。 只要配置和可用函式都使用相同的函式系列，即可使用其他記憶體配置和可用函式。
GetAdaptersAddresses 只會實作為同步函式呼叫。 GetAdaptersAddresses函式需要大量的網路資源和完成時間，因為必須周遊所有低階網路介面資料表。
一個可用來判斷傳回AdapterAddresses參數所指向之IP_ADAPTER_ADDRESSES結構所需記憶體的方法，就是傳遞太小的緩衝區大小，如GetAdaptersAddresses 函式第一次呼叫 GetAdaptersAddresses函式中所指出的SizePointer參數中所述，因此函式會失敗並ERROR_BUFFER_OVERFLOW。 當傳回值 ERROR_BUFFER_OVERFLOW時， 傳回的 SizePointer 參數會指向所需的緩衝區大小，以保存配接器資訊。 請注意，如果新增或移除配接器位址，則 AdapterAddresses參數所指向之IP_ADAPTER_ADDRESSES結構所需的緩衝區大小，可以在後續呼叫 GetAdaptersAddresses函式之間變更。 不過，強烈建議您不要使用 GetAdaptersAddresses 函式的這個方法。 這個方法需要多次呼叫 GetAdaptersAddresses 函 式。
呼叫 GetAdaptersAddresses 函式的建議方法是預先配置 AdapterAddresses 參數所指向的 15KB 工作緩衝區。 在一般電腦上，這可大幅減少 GetAdaptersAddresses 函式傳回 ERROR_BUFFER_OVERFLOW的機會，這需要多次呼叫 GetAdaptersAddresses 函式。 此範例程式碼說明這個使用方法。
在Windows 10之前的版本中，此函式所傳回清單中顯示介面卡的順序可以從 [網路連線] 資料夾控制：從 [進階] 功能表中選取 [進階設定] 功能表項目。 從Windows 10開始，配接器出現在清單中的順序取決於 IPv4 或 IPv6 路由計量。
如果已設定GAA_FLAG_INCLUDE_ALL_INTERFACES，則會擷取所有 NDIS 介面卡，即使這些位址與未系結至 Family 參數中指定的位址系列相關聯也一樣。 如果未設定此旗標，則只會傳回針對 Family 參數中指定的位址系列所系結至介面卡的位址。
IP_ADAPTER_ADDRESSES 結構的大小 已在 Windows XP 上變更，Service Pack 1 (SP1) 和更新版本。 已將數個額外的成員新增至這個結構。 Windows Vista 和更新版本上也變更 了IP_ADAPTER_ADDRESSES 結構的大小。 已將此結構新增一些額外的成員。 IP_ADAPTER_ADDRESSES 結構的大小 也會在 Windows Vista 上變更，Service Pack 1 (SP1) 和更新版本，以及 Windows Server 2008 和更新版本。 此結構中新增了一個額外的成員。 AdapterAddresses參數所指向之緩衝區中結構連結清單中傳回之IP_ADAPTER_ADDRESSES結構的Length成員，應該用來判斷正在使用哪一個IP_ADAPTER_ADDRESSES結構版本。
GetIpAddrTable函式會擷取本機電腦上的介面對 IPv4 位址對應表，並在MIB_IPADDRTABLE結構中傳回這項資訊。
在針對 Windows Server 2003 和更早版本發行的 Platform Software Development Kit (SDK) 上， GetAdaptersAddresses 函式的傳回值定義為 DWORD，而不是 ULONG。
SOCKET_ADDRESS結構用於AdapterAddresses參數所指向的IP_ADAPTER_ADDRESSES結構中。 在針對 Windows Vista 和更新版本發行的 Microsoft Windows 軟體發展工具組 (SDK) 上，標頭檔的組織已變更，且SOCKET_ADDRESS結構定義在Winsock2.h標頭檔自動包含的Ws2def.h標頭檔中。 在 Windows Server 2003 和 Windows XP 發行的平臺 SDK 上， SOCKET_ADDRESS 結構會在 Winsock2.h 標頭檔中宣告。 若要使用IP_ADAPTER_ADDRESSES結構，必須在Iphlpapi.h標頭檔之前包含Winsock2.h標頭檔。
範例
此範例會擷取與系統相關聯之介面卡 的IP_ADAPTER_ADDRESSES 結構，並列印每個介面卡介面的一些成員。
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
// Link with Iphlpapi.lib
#pragma comment(lib, "IPHLPAPI.lib")
#define WORKING_BUFFER_SIZE 15000
#define MAX_TRIES 3
#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */
int __cdecl main(int argc, char **argv)
{
/* Declare and initialize variables */
DWORD dwRetVal = 0;
unsigned int i = 0;
// Set the flags to pass to GetAdaptersAddresses
ULONG flags = GAA_FLAG_INCLUDE_PREFIX;
// default to unspecified address family (both)
ULONG family = AF_UNSPEC;
LPVOID lpMsgBuf = NULL;
PIP_ADAPTER_ADDRESSES pAddresses = NULL;
ULONG outBufLen = 0;
ULONG Iterations = 0;
PIP_ADAPTER_ADDRESSES pCurrAddresses = NULL;
PIP_ADAPTER_UNICAST_ADDRESS pUnicast = NULL;
PIP_ADAPTER_ANYCAST_ADDRESS pAnycast = NULL;
PIP_ADAPTER_MULTICAST_ADDRESS pMulticast = NULL;
IP_ADAPTER_DNS_SERVER_ADDRESS *pDnServer = NULL;
IP_ADAPTER_PREFIX *pPrefix = NULL;
if (argc != 2) {
printf(" Usage: getadapteraddresses family\n");
printf(" getadapteraddresses 4 (for IPv4)\n");
printf(" getadapteraddresses 6 (for IPv6)\n");
printf(" getadapteraddresses A (for both IPv4 and IPv6)\n");
exit(1);
}
if (atoi(argv[1]) == 4)
family = AF_INET;
else if (atoi(argv[1]) == 6)
family = AF_INET6;
printf("Calling GetAdaptersAddresses function with family = ");
if (family == AF_INET)
printf("AF_INET\n");
if (family == AF_INET6)
printf("AF_INET6\n");
if (family == AF_UNSPEC)
printf("AF_UNSPEC\n\n");
// Allocate a 15 KB buffer to start with.
outBufLen = WORKING_BUFFER_SIZE;
do {
pAddresses = (IP_ADAPTER_ADDRESSES *) MALLOC(outBufLen);
if (pAddresses == NULL) {
printf
("Memory allocation failed for IP_ADAPTER_ADDRESSES struct\n");
exit(1);
}
dwRetVal =
GetAdaptersAddresses(family, flags, NULL, pAddresses, &outBufLen);
if (dwRetVal == ERROR_BUFFER_OVERFLOW) {
FREE(pAddresses);
pAddresses = NULL;
} else {
break;
}
Iterations++;
} while ((dwRetVal == ERROR_BUFFER_OVERFLOW) && (Iterations < MAX_TRIES));
if (dwRetVal == NO_ERROR) {
// If successful, output some information from the data we received
pCurrAddresses = pAddresses;
while (pCurrAddresses) {
printf("\tLength of the IP_ADAPTER_ADDRESS struct: %ld\n",
pCurrAddresses->Length);
printf("\tIfIndex (IPv4 interface): %u\n", pCurrAddresses->IfIndex);
printf("\tAdapter name: %s\n", pCurrAddresses->AdapterName);
pUnicast = pCurrAddresses->FirstUnicastAddress;
if (pUnicast != NULL) {
for (i = 0; pUnicast != NULL; i++)
pUnicast = pUnicast->Next;
printf("\tNumber of Unicast Addresses: %d\n", i);
} else
printf("\tNo Unicast Addresses\n");
pAnycast = pCurrAddresses->FirstAnycastAddress;
if (pAnycast) {
for (i = 0; pAnycast != NULL; i++)
pAnycast = pAnycast->Next;
printf("\tNumber of Anycast Addresses: %d\n", i);
} else
printf("\tNo Anycast Addresses\n");
pMulticast = pCurrAddresses->FirstMulticastAddress;
if (pMulticast) {
for (i = 0; pMulticast != NULL; i++)
pMulticast = pMulticast->Next;
printf("\tNumber of Multicast Addresses: %d\n", i);
} else
printf("\tNo Multicast Addresses\n");
pDnServer = pCurrAddresses->FirstDnsServerAddress;
if (pDnServer) {
for (i = 0; pDnServer != NULL; i++)
pDnServer = pDnServer->Next;
printf("\tNumber of DNS Server Addresses: %d\n", i);
} else
printf("\tNo DNS Server Addresses\n");
printf("\tDNS Suffix: %wS\n", pCurrAddresses->DnsSuffix);
printf("\tDescription: %wS\n", pCurrAddresses->Description);
printf("\tFriendly name: %wS\n", pCurrAddresses->FriendlyName);
if (pCurrAddresses->PhysicalAddressLength != 0) {
printf("\tPhysical address: ");
for (i = 0; i < (int) pCurrAddresses->PhysicalAddressLength;
i++) {
if (i == (pCurrAddresses->PhysicalAddressLength - 1))
printf("%.2X\n",
(int) pCurrAddresses->PhysicalAddress[i]);
else
printf("%.2X-",
(int) pCurrAddresses->PhysicalAddress[i]);
}
}
printf("\tFlags: %ld\n", pCurrAddresses->Flags);
printf("\tMtu: %lu\n", pCurrAddresses->Mtu);
printf("\tIfType: %ld\n", pCurrAddresses->IfType);
printf("\tOperStatus: %ld\n", pCurrAddresses->OperStatus);
printf("\tIpv6IfIndex (IPv6 interface): %u\n",
pCurrAddresses->Ipv6IfIndex);
printf("\tZoneIndices (hex): ");
for (i = 0; i < 16; i++)
printf("%lx ", pCurrAddresses->ZoneIndices[i]);
printf("\n");
printf("\tTransmit link speed: %I64u\n", pCurrAddresses->TransmitLinkSpeed);
printf("\tReceive link speed: %I64u\n", pCurrAddresses->ReceiveLinkSpeed);
pPrefix = pCurrAddresses->FirstPrefix;
if (pPrefix) {
for (i = 0; pPrefix != NULL; i++)
pPrefix = pPrefix->Next;
printf("\tNumber of IP Adapter Prefix entries: %d\n", i);
} else
printf("\tNumber of IP Adapter Prefix entries: 0\n");
printf("\n");
pCurrAddresses = pCurrAddresses->Next;
}
} else {
printf("Call to GetAdaptersAddresses failed with error: %d\n",
dwRetVal);
if (dwRetVal == ERROR_NO_DATA)
printf("\tNo addresses were found for the requested parameters\n");
else {
if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER |
FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
NULL, dwRetVal, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
// Default language
(LPTSTR) & lpMsgBuf, 0, NULL)) {
printf("\tError: %s", lpMsgBuf);
LocalFree(lpMsgBuf);
if (pAddresses)
FREE(pAddresses);
exit(1);
}
}
}
if (pAddresses) {
FREE(pAddresses);
}
return 0;
}
需求
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | iphlpapi.h |
| 程式庫 | Iphlpapi.lib |
| Dll | Iphlpapi.dll |