Funzione GetInterfaceInfo (iphlpapi.h)

Articolo
08/24/2023

La funzione GetInterfaceInfo ottiene l'elenco delle schede di interfaccia di rete con IPv4 abilitato nel sistema locale.

Sintassi

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

Parametri

[out] pIfTable

Puntatore a un buffer che specifica una struttura IP_INTERFACE_INFO che riceve l'elenco di adattatori. Questo buffer deve essere allocato dal chiamante.

[in, out] dwOutBufLen

Puntatore a una variabile DWORD che specifica le dimensioni del buffer a cui punta il parametro pIfTable per ricevere la struttura IP_INTERFACE_INFO . Se questa dimensione non è sufficiente per contenere le informazioni sull'interfaccia IPv4, GetInterfaceInfo compila questa variabile con le dimensioni necessarie e restituisce un codice di errore di ERROR_INSUFFICIENT_BUFFER.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene NO_ERROR.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_INSUFFICIENT_BUFFER	Il buffer per ricevere le informazioni sull'adattatore IPv4 è troppo piccolo. Questo valore viene restituito se il parametro dwOutBufLen indica che il buffer a cui punta il parametro pIfTable è troppo piccolo per recuperare le informazioni sull'interfaccia IPv4. La dimensione richiesta viene restituita nella variabile DWORD a cui punta il parametro dwOutBufLen .
ERROR_INVALID_PARAMETER	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se il parametro dwOutBufLen è NULL o GetInterfaceInfo non è in grado di scrivere nella memoria a cui punta il parametro dwOutBufLen .
ERROR_NO_DATA	Nel sistema locale non sono abilitate schede di rete per IPv4. Questo valore viene restituito anche se tutte le schede di rete nel sistema locale sono disabilitate.
ERROR_NOT_SUPPORTED	Questa funzione non è supportata nel sistema operativo in uso nel sistema locale.
Altri	Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Commenti

La funzione GetInterfaceInfo è specifica per le schede di rete con IPv4 abilitato. La funzione restituisce una struttura IP_INTERFACE_INFO a cui punta il parametro pIfTable che contiene il numero di schede di rete con IPv4 abilitato nel sistema locale e una matrice di strutture IP_ADAPTER_INDEX_MAP con informazioni su ogni scheda di rete con IPv4 abilitato. La struttura IP_INTERFACE_INFO restituita da GetInterfaceInfo contiene almeno una struttura IP_ADAPTER_INDEX_MAP anche se il membro NumAdapters della struttura IP_INTERFACE_INFO indica che non sono abilitate schede di rete con IPv4. Quando il membro NumAdapters della struttura IP_INTERFACE_INFO restituito da GetInterfaceInfo è zero, il valore dei membri della singola struttura IP_ADAPTER_INDEX_MAP restituita nella struttura IP_INTERFACE_INFO non è definita.

Se la funzione GetInterfaceInfo viene chiamata con un buffer troppo piccolo per recuperare le informazioni sull'interfaccia IPv4 (il parametro dwOutBufLen indica che il buffer a cui punta il parametro pIfTable è troppo piccolo), la funzione restituisce ERROR_INSUFFICIENT_BUFFER. La dimensione richiesta viene restituita nella variabile DWORD a cui punta il parametro dwOutBufLen .

Il modo corretto per usare la funzione GetInterfaceInfo consiste nel chiamare questa funzione due volte. Nella prima chiamata passare un puntatore NULL nel parametro pIfTable e zero nella variabile a cui punta il parametro dwOutBufLen . La chiamata avrà esito negativo con ERROR_INSUFFICIENT_BUFFER e le dimensioni necessarie per questo buffer vengono restituite nella variabile DWORD a cui punta il parametro dwOutBufLen . È quindi possibile allocare un buffer delle dimensioni necessarie usando il valore a cui punta dwOutBufLen. La funzione GetInterfaceInfo può quindi essere chiamata una seconda volta con un puntatore a questo buffer passato nel parametro pIfTable e la lunghezza del buffer impostato sulle dimensioni di questo buffer.

Le funzioni GetAdaptersInfo e GetInterfaceInfo non restituiscono informazioni sull'interfaccia di loopback. Le informazioni sull'interfaccia di loopback vengono restituite dalla funzione GetIpAddrTable .

In Windows Vista e versioni successive il membro Name della struttura IP_ADAPTER_INDEX_MAP restituita nella struttura IP_INTERFACE_INFO può essere una stringa Unicode del GUID per l'interfaccia di rete (la stringa inizia con il carattere '{').

Esempio

Nell'esempio seguente viene recuperato l'elenco delle schede di rete con IPv4 abilitato nel sistema locale e vengono stampate varie proprietà della prima scheda di rete.

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

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	iphlpapi.h
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll