Freigeben über


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.

Wert Bedeutung
AF_UNSPEC
0
Gibt sowohl IPv4- als auch IPv6-Adressen zurück, die Adaptern mit aktiviertem IPv4 oder IPv6 zugeordnet sind.
AF_INET
2
Geben Sie nur IPv4-Adressen zurück, die Adaptern mit aktiviertem IPv4 zugeordnet sind.
AF_INET6
23
Gibt nur IPv6-Adressen zurück, die Adaptern mit aktiviertem IPv6 zugeordnet sind.

[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.

Wert Bedeutung
GAA_FLAG_SKIP_UNICAST
0x0001
Geben Sie keine Unicastadressen zurück.
GAA_FLAG_SKIP_ANYCAST
0x0002
Geben Sie keine IPv6 anycast-Adressen zurück.
GAA_FLAG_SKIP_MULTICAST
0x0004
Geben Sie keine Multicastadressen zurück.
GAA_FLAG_SKIP_DNS_SERVER
0x0008
Geben Sie keine Adressen von DNS-Servern zurück.
GAA_FLAG_INCLUDE_PREFIX
0x0010
Gibt eine Liste der IP-Adresspräfixe für diesen Adapter zurück. Wenn dieses Flag festgelegt ist, werden IP-Adresspräfixe sowohl für IPv6- als auch für IPv4-Adressen zurückgegeben.

Dieses Flag wird unter Windows XP mit SP1 und höher unterstützt.

GAA_FLAG_SKIP_FRIENDLY_NAME
0x0020
Geben Sie den Anzeigenamen des Adapters nicht zurück.
GAA_FLAG_INCLUDE_WINS_INFO
0x0040
Zurückgeben von Adressen von WINS-Servern (Windows Internet Name Service).

Dieses Flag wird unter Windows Vista und höher unterstützt.

GAA_FLAG_INCLUDE_GATEWAYS
0x0080
Gibt die Adressen von Standardgateways zurück.

Dieses Flag wird unter Windows Vista und höher unterstützt.

GAA_FLAG_INCLUDE_ALL_INTERFACES
0x0100
Gibt Adressen für alle NDIS-Schnittstellen zurück.

Dieses Flag wird unter Windows Vista und höher unterstützt.

GAA_FLAG_INCLUDE_ALL_COMPARTMENTS
0x0200
Gibt Adressen in allen Routingfächern zurück.

Dieses Flag wird derzeit nicht unterstützt und für die zukünftige Verwendung reserviert.

GAA_FLAG_INCLUDE_TUNNEL_BINDINGORDER
0x0400
Geben Sie die Adapteradressen in Tunnelbindungsreihenfolge sortiert zurück. Dieses Flag wird unter Windows Vista und höher unterstützt.

[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
ERROR_ADDRESS_NOT_ASSOCIATED
Dem Netzwerkendpunkt wurde noch keine Adresse zugeordnet. DHCP-Leaseinformationen waren verfügbar.
ERROR_BUFFER_OVERFLOW
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.
ERROR_INVALID_PARAMETER
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.
ERROR_NOT_ENOUGH_MEMORY
Für den Vorgang stehen nicht genügend Arbeitsspeicherressourcen zur Verfügung.
ERROR_NO_DATA
Für die angeforderten Parameter wurden keine Adressen gefunden.
Andere
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

Weitere Informationen

GetIpAddrTable

HeapAlloc

HeapFree

Ip-Hilfsfunktionsreferenz

Startseite des IP-Hilfsprogrammes

IP_ADAPTER_ADDRESSES

MIB_IPADDRTABLE

SOCKET_ADDRESS

Windows Sockets