Funzione GetInterfaceInfo (iphlpapi.h)

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.

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

Vedi anche

GetAdaptersInfo

GetIpAddrTable

GetNumberOfInterfaces

Informazioni di riferimento sulle funzioni helper IP

Pagina iniziale dell'helper IP

IP_ADAPTER_INDEX_MAP

IP_INTERFACE_INFO