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.
[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.
[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 |
|---|---|
|
Aucune adresse n’a encore été associée au point de terminaison réseau. Les informations de bail DHCP étaient disponibles. |
|
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. |
|
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. |
|
Des ressources de mémoire insuffisantes sont disponibles pour terminer l’opération. |
|
Aucune adresse n’a été trouvée pour les paramètres demandés. |
|
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
Informations de référence sur les fonctions d’assistance IP