Partager via


GetAdaptersAddresses, fonction (iphlpapi.h)

La fonction GetAdaptersAddresses récupère les adresses associées aux cartes sur l’ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE ULONG GetAdaptersAddresses(
  [in]      ULONG                 Family,
  [in]      ULONG                 Flags,
  [in]      PVOID                 Reserved,
  [in, out] PIP_ADAPTER_ADDRESSES AdapterAddresses,
  [in, out] PULONG                SizePointer
);

Paramètres

[in] Family

Famille d’adresses des adresses à récupérer. Ce paramètre peut prendre les valeurs suivantes.

Valeur Signification
AF_UNSPEC
0
Retourne les adresses IPv4 et IPv6 associées aux cartes avec IPv4 ou IPv6 activées.
AF_INET
2
Retourne uniquement les adresses IPv4 associées aux adaptateurs avec IPv4 activé.
AF_INET6
23
Retourne uniquement les adresses IPv6 associées aux cartes avec IPv6 activées.

[in] Flags

Type d’adresses à récupérer. Les valeurs possibles sont définies dans le fichier d’en-tête Iptypes.h . Notez que le fichier d’en-tête Iptypes.h est automatiquement inclus dans Iphlpapi.h et ne doit jamais être utilisé directement.

Ce paramètre est une combinaison des valeurs suivantes. Si ce paramètre est égal à zéro, les adresses IP unicast, anycast et multidiffusion sont retournées.

Valeur Signification
GAA_FLAG_SKIP_UNICAST
0x0001
Ne retournez pas d’adresses unicast.
GAA_FLAG_SKIP_ANYCAST
0x0002
Ne retournez pas d’adresses de diffusion IPv6.
GAA_FLAG_SKIP_MULTICAST
0x0004
Ne retournez pas d’adresses de multidiffusion.
GAA_FLAG_SKIP_DNS_SERVER
0x0008
Ne retournez pas d’adresses de serveurs DNS.
GAA_FLAG_INCLUDE_PREFIX
0x0010
Retourne une liste de préfixes d’adresse IP sur cette carte. Lorsque cet indicateur est défini, les préfixes d’adresse IP sont retournés pour les adresses IPv6 et IPv4.

Cet indicateur est pris en charge sur Windows XP avec SP1 et versions ultérieures.

GAA_FLAG_SKIP_FRIENDLY_NAME
0x0020
Ne retournez pas le nom convivial de l’adaptateur.
GAA_FLAG_INCLUDE_WINS_INFO
0x0040
Adresses de retour des serveurs WINS (Windows Internet Name Service).

Cet indicateur est pris en charge sur Windows Vista et versions ultérieures.

GAA_FLAG_INCLUDE_GATEWAYS
0x0080
Retourne les adresses des passerelles par défaut.

Cet indicateur est pris en charge sur Windows Vista et versions ultérieures.

GAA_FLAG_INCLUDE_ALL_INTERFACES
0x0100
Retourne les adresses de toutes les interfaces NDIS.

Cet indicateur est pris en charge sur Windows Vista et versions ultérieures.

GAA_FLAG_INCLUDE_ALL_COMPARTMENTS
0x0200
Retourne les adresses dans tous les compartiments de routage.

Cet indicateur n’est actuellement pas pris en charge et réservé pour une utilisation ultérieure.

GAA_FLAG_INCLUDE_TUNNEL_BINDINGORDER
0x0400
Retourne les adresses de l’adaptateur triées dans l’ordre de liaison de tunnel. Cet indicateur est pris en charge sur Windows Vista et versions ultérieures.

[in] Reserved

Ce paramètre n’est actuellement pas utilisé, mais est réservé à une utilisation future du système. L’application appelante doit passer la valeur NULL pour ce paramètre.

[in, out] AdapterAddresses

Pointeur vers une mémoire tampon qui contient une liste liée de structures IP_ADAPTER_ADDRESSES lors d’un retour réussi.

[in, out] SizePointer

Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée par AdapterAddresses.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS (définie sur la même valeur que NO_ERROR).

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour Description
ERROR_ADDRESS_NOT_ASSOCIATED
Aucune adresse n’a encore été associée au point de terminaison réseau. Les informations de bail DHCP étaient disponibles.
ERROR_BUFFER_OVERFLOW
La taille de mémoire tampon indiquée par le paramètre SizePointer est trop petite pour contenir les informations de l’adaptateur ou le paramètre AdapterAddresses a la valeur NULL. Le paramètre SizePointer retourné pointe vers la taille requise de la mémoire tampon pour contenir les informations de l’adaptateur.
ERROR_INVALID_PARAMETER
L’un des paramètres n’est pas valide. Cette erreur est retournée pour l’une des conditions suivantes : le paramètre SizePointer a la valeur NULL, le paramètre Addressn’est pas AF_INET, AF_INET6 ou AF_UNSPEC, ou les informations d’adresse pour les paramètres demandés sont supérieures à ULONG_MAX.
ERROR_NOT_ENOUGH_MEMORY
Des ressources de mémoire insuffisantes sont disponibles pour terminer l’opération.
ERROR_NO_DATA
Aucune adresse n’a été trouvée pour les paramètres demandés.
Autres
Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Notes

The
La fonction GetAdaptersAddresses peut récupérer des informations pour les adresses IPv4 et IPv6.

Les adresses sont retournées sous la forme d’une liste liée de structures IP_ADAPTER_ADDRESSES dans la mémoire tampon pointée par le paramètre AdapterAddresses . L’application qui appelle la fonction GetAdaptersAddresses doit allouer la quantité de mémoire nécessaire pour retourner les structures IP_ADAPTER_ADDRESSES pointées par le paramètre AdapterAddresses . Lorsque ces structures retournées ne sont plus nécessaires, l’application doit libérer la mémoire allouée. Pour ce faire, appelez la fonction HeapAlloc pour allouer de la mémoire et appelez ultérieurement la fonction HeapFree pour libérer la mémoire allouée, comme indiqué dans l’exemple de code. D’autres fonctions d’allocation de mémoire et gratuites peuvent être utilisées tant que la même famille de fonctions est utilisée à la fois pour l’allocation et la fonction libre.

GetAdaptersAddresses est implémenté uniquement en tant qu’appel de fonction synchrone. La fonction GetAdaptersAddresses nécessite une quantité importante de ressources réseau et de temps à exécuter, car toutes les tables d’interface réseau de bas niveau doivent être parcourues.

Une méthode qui peut être utilisée pour déterminer la mémoire nécessaire pour retourner les structures IP_ADAPTER_ADDRESSES pointées par le paramètre AdapterAddresses consiste à passer une taille de mémoire tampon trop petite, comme indiqué dans le paramètre SizePointer dans le premier appel à la fonction GetAdaptersAddresses , afin que la fonction échoue avec ERROR_BUFFER_OVERFLOW. Lorsque la valeur de retour est ERROR_BUFFER_OVERFLOW, le paramètre SizePointer retourné pointe vers la taille requise de la mémoire tampon pour contenir les informations de l’adaptateur. Notez qu’il est possible que la taille de mémoire tampon requise pour les structures IP_ADAPTER_ADDRESSES pointées par le paramètre AdapterAddresses change entre les appels suivants à la fonction GetAdaptersAddresses si une adresse d’adaptateur est ajoutée ou supprimée. Toutefois, cette méthode d’utilisation de la fonction GetAdaptersAddresses est fortement déconseillée. Cette méthode nécessite l’appel de la fonction GetAdaptersAddresses plusieurs fois.

La méthode recommandée pour appeler la fonction GetAdaptersAddresses consiste à préallouer une mémoire tampon de travail de 15 Ko vers laquelle pointe le paramètre AdapterAddresses . Sur les ordinateurs classiques, cela réduit considérablement les risques que la fonction GetAdaptersAddresses retourne ERROR_BUFFER_OVERFLOW, ce qui nécessiterait d’appeler la fonction GetAdaptersAddresses plusieurs fois. L’exemple de code illustre cette méthode d’utilisation.

Dans les versions antérieures à Windows 10, l’ordre dans lequel les cartes apparaissent dans la liste retournée par cette fonction peut être contrôlé à partir du dossier Connexions réseau : sélectionnez l’élément de menu Paramètres avancés dans le menu Avancé. À compter de Windows 10, l’ordre dans lequel les adaptateurs apparaissent dans la liste est déterminé par la métrique de routage IPv4 ou IPv6.

Si le GAA_FLAG_INCLUDE_ALL_INTERFACES est défini, tous les adaptateurs NDIS sont récupérés, même les adresses associées à des adaptateurs non liés à une famille d’adresses spécifiée dans le paramètre Family . Lorsque cet indicateur n’est pas défini, seules les adresses liées à un adaptateur activé pour la famille d’adresses spécifiée dans le paramètre Family sont retournées.

La taille de la structure IP_ADAPTER_ADDRESSES a été modifiée sur Windows XP avec Service Pack 1 (SP1) et versions ultérieures. Plusieurs membres supplémentaires ont été ajoutés à cette structure. La taille de la structure IP_ADAPTER_ADDRESSES a également été modifiée sur Windows Vista et versions ultérieures. Plusieurs membres supplémentaires ont été ajoutés à cette structure. La taille de la structure IP_ADAPTER_ADDRESSES a également changé sur Windows Vista avec Service Pack 1 (SP1) et versions ultérieures et sur Windows Server 2008 et versions ultérieures. Un membre supplémentaire a été ajouté à cette structure. Le membre Length de la structure IP_ADAPTER_ADDRESSES retournée dans la liste liée des structures dans la mémoire tampon pointée par le paramètre AdapterAddresses doit être utilisé pour déterminer quelle version de la structure IP_ADAPTER_ADDRESSES est utilisée.

La fonction GetIpAddrTable récupère la table de mappage d’adresses interface vers IPv4 sur un ordinateur local et retourne ces informations dans une structure de MIB_IPADDRTABLE .

Dans le Kit de développement logiciel (SDK) de plateforme publié pour Windows Server 2003 et versions antérieures, la valeur de retour de la fonction GetAdaptersAddresses a été définie comme un DWORD, plutôt qu’un ULONG.

La structure SOCKET_ADDRESS est utilisée dans la structure IP_ADAPTER_ADDRESSES pointée par le paramètre AdapterAddresses . Sur le Kit de développement logiciel (SDK) Microsoft Windows publié pour Windows Vista et versions ultérieures, la organization des fichiers d’en-tête a changé et la structure SOCKET_ADDRESS est définie dans le fichier d’en-tête Ws2def.h qui est automatiquement inclus par le fichier d’en-tête Winsock2.h. Dans le Kit de développement logiciel (SDK) de plateforme publié pour Windows Server 2003 et Windows XP, la structure SOCKET_ADDRESS est déclarée dans le fichier d’en-tête Winsock2.h . Pour utiliser la structure IP_ADAPTER_ADDRESSES , le fichier d’en-tête Winsock2.h doit être inclus avant le fichier d’en-tête Iphlpapi.h .

Exemples

Cet exemple récupère la structure IP_ADAPTER_ADDRESSES pour les adaptateurs associés au système et imprime certains membres pour chaque interface d’adaptateur.

#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;
}

Spécifications

   
Client minimal pris en charge Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête iphlpapi.h
Bibliothèque Iphlpapi.lib
DLL Iphlpapi.dll

Voir aussi

GetIpAddrTable

HeapAlloc

HeapFree

Informations de référence sur les fonctions d’assistance IP

Page de démarrage de l’assistance IP

IP_ADAPTER_ADDRESSES

MIB_IPADDRTABLE

SOCKET_ADDRESS

Windows Sockets