GetInterfaceInfo, fonction (iphlpapi.h)

Article
08/24/2023

La fonction GetInterfaceInfo obtient la liste des cartes d’interface réseau avec IPv4 activé sur le système local.

Syntaxe

IPHLPAPI_DLL_LINKAGE DWORD GetInterfaceInfo(
  [out]     PIP_INTERFACE_INFO pIfTable,
  [in, out] PULONG             dwOutBufLen
);

Paramètres

[out] pIfTable

Pointeur vers une mémoire tampon qui spécifie une structure IP_INTERFACE_INFO qui reçoit la liste des adaptateurs. Cette mémoire tampon doit être allouée par l’appelant.

[in, out] dwOutBufLen

Pointeur vers une variable DWORD qui spécifie la taille de la mémoire tampon pointée vers le paramètre pIfTable pour recevoir la structure IP_INTERFACE_INFO . Si cette taille est insuffisante pour contenir les informations d’interface IPv4, GetInterfaceInfo remplit cette variable avec la taille requise et retourne un code d’erreur de ERROR_INSUFFICIENT_BUFFER.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

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

Code de retour	Description
ERROR_INSUFFICIENT_BUFFER	La mémoire tampon pour recevoir les informations de l’adaptateur IPv4 est trop petite. Cette valeur est retournée si le paramètre dwOutBufLen indique que la mémoire tampon pointée par le paramètre pIfTable est trop petite pour récupérer les informations d’interface IPv4. La taille requise est retournée dans la variable DWORD pointée par le paramètre dwOutBufLen .
ERROR_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si le paramètre dwOutBufLen a la valeur NULL ou si GetInterfaceInfo ne peut pas écrire dans la mémoire vers laquelle pointe le paramètre dwOutBufLen .
ERROR_NO_DATA	Aucune carte réseau n’est activée pour IPv4 sur le système local. Cette valeur est également retournée si toutes les cartes réseau du système local sont désactivées.
ERROR_NOT_SUPPORTED	Cette fonction n’est pas prise en charge sur le système d’exploitation utilisé sur le système local.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Notes

La fonction GetInterfaceInfo est spécifique aux cartes réseau avec IPv4 activé. La fonction retourne une structure IP_INTERFACE_INFO pointée vers le paramètre pIfTable qui contient le nombre de cartes réseau avec IPv4 activé sur le système local et un tableau de structures IP_ADAPTER_INDEX_MAP avec des informations sur chaque carte réseau avec IPv4 activé. La structure IP_INTERFACE_INFO retournée par GetInterfaceInfo contient au moins une structure IP_ADAPTER_INDEX_MAP même si le membre NumAdapters de la structure IP_INTERFACE_INFO indique qu’aucune carte réseau avec IPv4 n’est activée. Lorsque le membre NumAdapters de la structure IP_INTERFACE_INFO retournée par GetInterfaceInfo est égal à zéro, la valeur des membres de la structure IP_ADAPTER_INDEX_MAP unique retournée dans la structure IP_INTERFACE_INFO n’est pas définie.

Si la fonction GetInterfaceInfo est appelée avec une mémoire tampon trop petite pour récupérer les informations d’interface IPv4 (le paramètre dwOutBufLen indique que la mémoire tampon pointée par le paramètre pIfTable est trop petite), la fonction retourne ERROR_INSUFFICIENT_BUFFER. La taille requise est retournée dans la variable DWORD pointée par le paramètre dwOutBufLen .

La bonne façon d’utiliser la fonction GetInterfaceInfo consiste à appeler cette fonction deux fois. Dans le premier appel, passez un pointeur NULL dans le paramètre pIfTable et zéro dans la variable pointée par le paramètre dwOutBufLen . L’appel échoue avec ERROR_INSUFFICIENT_BUFFER et la taille requise pour cette mémoire tampon est retournée dans la variable DWORD pointée par le paramètre dwOutBufLen . Une mémoire tampon peut ensuite être allouée de la taille requise à l’aide de la valeur pointée par le dwOutBufLen. Ensuite, la fonction GetInterfaceInfo peut être appelée une deuxième fois avec un pointeur vers cette mémoire tampon passé dans le paramètre pIfTable et la longueur de la mémoire tampon définie sur la taille de cette mémoire tampon.

Les fonctions GetAdaptersInfo et GetInterfaceInfo ne retournent pas d’informations sur l’interface de bouclage. Les informations sur l’interface de bouclage sont retournées par la fonction GetIpAddrTable .

Sur Windows Vista et versions ultérieures, le membre Name de la structure IP_ADAPTER_INDEX_MAP retournée dans la structure IP_INTERFACE_INFO peut être une chaîne Unicode du GUID pour l’interface réseau (la chaîne commence par le caractère « { »).

Exemples

L’exemple suivant récupère la liste des cartes réseau avec IPv4 activé sur le système local et imprime les différentes propriétés de la première carte réseau.

#include <winsock2.h>
#include <ws2ipdef.h>
#include <iphlpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x)) 
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int main()
{

// Declare and initialize variables
    PIP_INTERFACE_INFO pInfo = NULL;
    ULONG ulOutBufLen = 0;

    DWORD dwRetVal = 0;
    int iReturn = 1;

    int i;

// Make an initial call to GetInterfaceInfo to get
// the necessary size in the ulOutBufLen variable
    dwRetVal = GetInterfaceInfo(NULL, &ulOutBufLen);
    if (dwRetVal == ERROR_INSUFFICIENT_BUFFER) {
        pInfo = (IP_INTERFACE_INFO *) MALLOC(ulOutBufLen);
        if (pInfo == NULL) {
            printf
                ("Unable to allocate memory needed to call GetInterfaceInfo\n");
            return 1;
        }
    }
// Make a second call to GetInterfaceInfo to get
// the actual data we need
    dwRetVal = GetInterfaceInfo(pInfo, &ulOutBufLen);
    if (dwRetVal == NO_ERROR) {
        printf("Number of Adapters: %ld\n\n", pInfo->NumAdapters);
        for (i = 0; i < pInfo->NumAdapters; i++) {
            printf("Adapter Index[%d]: %ld\n", i,
                   pInfo->Adapter[i].Index);
            printf("Adapter Name[%d]: %ws\n\n", i,
                   pInfo->Adapter[i].Name);
        }
        iReturn = 0;
    } else if (dwRetVal == ERROR_NO_DATA) {
        printf
            ("There are no network adapters with IPv4 enabled on the local system\n");
        iReturn = 0;
    } else {
        printf("GetInterfaceInfo failed with error: %d\n", dwRetVal);
        iReturn = 1;
    }

    FREE(pInfo);
    return (iReturn);
}

Spécifications


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