GetAdaptersAddresses-Funktion (iphlpapi.h)
Die GetAdaptersAddresses-Funktion ruft die Adressen ab, die den Adaptern auf dem lokalen Computer zugeordnet sind.
Syntax
IPHLPAPI_DLL_LINKAGE ULONG GetAdaptersAddresses(
[in] ULONG Family,
[in] ULONG Flags,
[in] PVOID Reserved,
[in, out] PIP_ADAPTER_ADDRESSES AdapterAddresses,
[in, out] PULONG SizePointer
);
Parameter
[in] Family
Die Adressfamilie der abzurufenden Adressen. Dieser Parameter muss einen der folgenden Werte aufweisen.
[in] Flags
Der Typ der abzurufenden Adressen. Die möglichen Werte werden in der Headerdatei Iptypes.h definiert. Beachten Sie, dass die Iptypes.h-Headerdatei automatisch in Iphlpapi.h enthalten ist und nie direkt verwendet werden sollte.
Dieser Parameter ist eine Kombination der folgenden Werte. Wenn dieser Parameter null ist, werden Unicast-, Anycast- und Multicast-IP-Adressen zurückgegeben.
[in] Reserved
Dieser Parameter wird derzeit nicht verwendet, ist aber für die zukünftige Systemverwendung reserviert. Die aufrufende Anwendung sollte NULL für diesen Parameter übergeben.
[in, out] AdapterAddresses
Ein Zeiger auf einen Puffer, der eine verknüpfte Liste mit IP_ADAPTER_ADDRESSES Strukturen bei erfolgreicher Rückgabe enthält.
[in, out] SizePointer
Ein Zeiger auf eine Variable, die die Größe des Puffers angibt, auf den von AdapterAddresses verwiesen wird.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS (definiert auf den gleichen Wert wie NO_ERROR).
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
Dem Netzwerkendpunkt wurde noch keine Adresse zugeordnet. DHCP-Leaseinformationen waren verfügbar. |
|
Die vom Parameter SizePointer angegebene Puffergröße ist zu klein, um die Adapterinformationen enthalten zu können, oder der AdapterAddresses-Parameter ist NULL. Der SizePointer-Parameter hat Punkte auf die erforderliche Größe des Puffers zurückgegeben, um die Adapterinformationen zu enthalten. |
|
Einer der Parameter ist ungültig. Dieser Fehler wird für eine der folgenden Bedingungen zurückgegeben: Der SizePointer-Parameter ist NULL, der Address-Parameter ist nicht AF_INET, AF_INET6 oder AF_UNSPEC, oder die Adressinformationen für die angeforderten Parameter sind größer als ULONG_MAX. |
|
Für den Vorgang stehen nicht genügend Arbeitsspeicherressourcen zur Verfügung. |
|
Für die angeforderten Parameter wurden keine Adressen gefunden. |
|
Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
The
Die GetAdaptersAddresses-Funktion kann Informationen für IPv4- und IPv6-Adressen abrufen.
Adressen werden als verknüpfte Liste von IP_ADAPTER_ADDRESSES Strukturen im Puffer zurückgegeben, auf die der AdapterAddresses-Parameter verweist. Die Anwendung, die die GetAdaptersAddresses-Funktion aufruft , muss die Menge an Arbeitsspeicher zuordnen, die erforderlich ist, um die IP_ADAPTER_ADDRESSES Strukturen zurückzugeben, auf die vom AdapterAddresses-Parameter verwiesen wird. Wenn diese zurückgegebenen Strukturen nicht mehr erforderlich sind, sollte die Anwendung den zugewiesenen Arbeitsspeicher freigeben. Dies kann erreicht werden, indem Sie die HeapAlloc-Funktion aufrufen, um Arbeitsspeicher zuzuweisen, und später die HeapFree-Funktion aufrufen, um den zugeordneten Arbeitsspeicher freizugeben, wie im Beispielcode gezeigt. Andere Speicherzuordnungen und freie Funktionen können verwendet werden, solange die gleiche Funktionsfamilie sowohl für die Zuordnung als auch für die freie Funktion verwendet wird.
GetAdaptersAddresses wird nur als synchroner Funktionsaufruf implementiert. Die GetAdaptersAddresses-Funktion erfordert eine beträchtliche Menge an Netzwerkressourcen und Zeit, da alle Netzwerkschnittstellentabellen auf niedriger Ebene durchlaufen werden müssen.
Eine Methode, die verwendet werden kann, um den Arbeitsspeicher zu bestimmen, der für die Rückgabe der IP_ADAPTER_ADDRESSES Strukturen erforderlich ist, auf die der AdapterAddresses-Parameter verweist, besteht darin, eine zu kleine Puffergröße zu übergeben, wie im SizePointer-Parameter im ersten Aufruf der GetAdaptersAddresses-Funktion angegeben, sodass die Funktion mit ERROR_BUFFER_OVERFLOW fehlschlägt. Wenn der Rückgabewert ERROR_BUFFER_OVERFLOW ist, zeigt der sizePointer-Parameter auf die erforderliche Größe des Puffers, um die Adapterinformationen zu enthalten. Beachten Sie, dass die Puffergröße, die für die IP_ADAPTER_ADDRESSES Strukturen erforderlich ist, auf die der AdapterAddresses-Parameter verweist, zwischen nachfolgenden Aufrufen der GetAdaptersAddresses-Funktion geändert werden kann, wenn eine Adapteradresse hinzugefügt oder entfernt wird. Von dieser Methode zur Verwendung der GetAdaptersAddresses-Funktion wird jedoch dringend abgeraten. Für diese Methode muss die GetAdaptersAddresses-Funktion mehrmals aufgerufen werden.
Die empfohlene Methode zum Aufrufen der GetAdaptersAddresses-Funktion ist die Vorabzuweisung eines 15 KB-Arbeitspuffers, auf den der AdapterAddresses-Parameter verweist. Auf typischen Computern verringert dies die Wahrscheinlichkeit erheblich, dass die GetAdaptersAddresses-FunktionERROR_BUFFER_OVERFLOW zurückgibt, was den mehrfachen Aufruf der GetAdaptersAddresses-Funktion erfordern würde. Der Beispielcode veranschaulicht diese Verwendungsmethode.
In Versionen vor Windows 10 kann die Reihenfolge, in der Adapter in der von dieser Funktion zurückgegebenen Liste angezeigt werden, über den Ordner Netzwerkverbindungen gesteuert werden: Wählen Sie im Menü Erweitert das Menüelement Erweiterte Einstellungen aus. Ab Windows 10 wird die Reihenfolge, in der Adapter in der Liste angezeigt werden, durch die IPv4- oder IPv6-Routenmetrik bestimmt.
Wenn die GAA_FLAG_INCLUDE_ALL_INTERFACES festgelegt ist, werden alle NDIS-Adapter auch die Adressen abgerufen, die Adaptern zugeordnet sind, die nicht an eine im Family-Parameter angegebene Adressfamilie gebunden sind. Wenn dieses Flag nicht festgelegt ist, werden nur die Adressen zurückgegeben, die an einen Adapter gebunden sind, der für die im Family-Parameter angegebene Adressfamilie aktiviert ist.
Die Größe der IP_ADAPTER_ADDRESSES-Struktur wurde unter Windows XP mit Service Pack 1 (SP1) und höher geändert. Dieser Struktur wurden mehrere zusätzliche Member hinzugefügt. Die Größe der IP_ADAPTER_ADDRESSES-Struktur wurde auch unter Windows Vista und höher geändert. Dieser Struktur wurden eine Reihe zusätzlicher Member hinzugefügt. Die Größe der IP_ADAPTER_ADDRESSES-Struktur hat sich auch unter Windows Vista mit Service Pack 1 (SP1) und höher sowie unter Windows Server 2008 und höher geändert. Dieser Struktur wurde ein weiteres Element hinzugefügt. Der Length-Member der IP_ADAPTER_ADDRESSES-Struktur , die in der verknüpften Liste der Strukturen im Puffer zurückgegeben wird, auf die der AdapterAddresses-Parameter verweist, sollte verwendet werden, um zu bestimmen, welche Version der IP_ADAPTER_ADDRESSES-Struktur verwendet wird.
Die GetIpAddrTable-Funktion ruft die Schnittstellen-zu-IPv4-Adresszuordnungstabelle auf einem lokalen Computer ab und gibt diese Informationen in einer MIB_IPADDRTABLE-Struktur zurück.
Im Platform Software Development Kit (SDK), das für Windows Server 2003 und früher veröffentlicht wurde, wurde der Rückgabewert für die GetAdaptersAddresses-Funktion als DWORD und nicht als ULONG definiert.
Die SOCKET_ADDRESS-Struktur wird in der IP_ADAPTER_ADDRESSES-Struktur verwendet, auf die der AdapterAddresses-Parameter verweist. Im Microsoft Windows Software Development Kit (SDK), das für Windows Vista und höher veröffentlicht wurde, wurde die organization von Headerdateien geändert, und die SOCKET_ADDRESS-Struktur wird in der Ws2def.h-Headerdatei definiert, die automatisch in der Winsock2.h-Headerdatei enthalten ist. Im Platform SDK, das für Windows Server 2003 und Windows XP veröffentlicht wurde, wird die SOCKET_ADDRESS-Struktur in der Winsock2.h-Headerdatei deklariert. Um die IP_ADAPTER_ADDRESSES-Struktur verwenden zu können, muss die Winsock2.h-Headerdatei vor der Iphlpapi.h-Headerdatei eingeschlossen werden.
Beispiele
In diesem Beispiel wird die IP_ADAPTER_ADDRESSES-Struktur für die dem System zugeordneten Adapter abgerufen und einige Member für jede Adapterschnittstelle ausgegeben.
#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;
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | iphlpapi.h |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll |