Condividi tramite


Funzione GetIfEntry (iphlpapi.h)

La funzione GetIfEntry recupera informazioni per l'interfaccia specificata nel computer locale.

Sintassi

IPHLPAPI_DLL_LINKAGE DWORD GetIfEntry(
  [in, out] PMIB_IFROW pIfRow
);

Parametri

[in, out] pIfRow

Puntatore a una struttura MIB_IFROW che, in caso di restituzione riuscita, riceve informazioni per un'interfaccia nel computer locale. In input impostare il membro dwIndex di MIB_IFROW sull'indice dell'interfaccia per cui recuperare informazioni. Il valore per la funzione dwIndex deve essere recuperato da una chiamata precedente alla funzione GetIfTable, GetIfTable2 o GetIfTable2Ex.

Valore restituito

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

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

Codice restituito Descrizione
ERROR_CAN_NOT_COMPLETE
Impossibile completare la richiesta. Errore interno.
ERROR_INVALID_DATA
I dati non sono validi. Questo errore viene restituito se l'indice dell'interfaccia di rete specificato dal membro dwIndex della struttura MIB_IFROW puntato al parametro pIfRow non è un indice di interfaccia valido nel computer locale.
ERROR_INVALID_PARAMETER
Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se un puntatore NULL viene passato nel parametro pIfRow .
ERROR_NOT_FOUND
Impossibile trovare l'interfaccia specificata. Questo errore viene restituito se non è stato possibile trovare l'indice dell'interfaccia di rete specificato dal membro dwIndex della struttura MIB_IFROW a cui punta il parametro pIfRow .
ERROR_NOT_SUPPORTED
La richiesta non è supportata. Questo errore viene restituito se IPv4 non è configurato nel computer locale.
Altri
Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

La funzione GetIfEntry recupera informazioni per un'interfaccia in un computer locale.

Il membro dwIndex nella struttura MIB_IFROW puntato dal parametro pIfRow deve essere inizializzato in un indice di interfaccia di rete valido recuperato da una chiamata precedente alla funzione GetIfTable,GetIfTable2 o GetIfTable2Ex .

La funzione GetIfEntry avrà esito negativo se il membro dwIndex del MIB_IFROW indicato dal parametro pIfRow non corrisponde a un indice di interfaccia esistente nel computer locale.

Esempio

Nell'esempio seguente vengono recuperate le voci dalla tabella dell'interfaccia e vengono stampate alcune delle informazioni disponibili per tale voce.

#include <winsock2.h>
#include <ws2tcpip.h>
#pragma comment(lib, "IPHLPAPI.lib")

#include <iphlpapi.h>

#include <stdio.h>
#include <stdlib.h>

#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.

    // Declare and initialize variables.
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;

    unsigned int i, j;

    /* variables used for GetIfTable and GetIfEntry */
    MIB_IFTABLE *pIfTable;
    MIB_IFROW *pIfRow;

    // Allocate memory for our pointers.
    pIfTable = (MIB_IFTABLE *) MALLOC(sizeof (MIB_IFTABLE));
    if (pIfTable == NULL) {
        printf("Error allocating memory needed to call GetIfTable\n");
        exit (1);
    }
    // Before calling GetIfEntry, we call GetIfTable to make
    // sure there are entries to get and retrieve the interface index.

    // Make an initial call to GetIfTable to get the
    // necessary size into dwSize
    dwSize = sizeof (MIB_IFTABLE);
    if (GetIfTable(pIfTable, &dwSize, 0) == ERROR_INSUFFICIENT_BUFFER) {
        FREE(pIfTable);
        pIfTable = (MIB_IFTABLE *) MALLOC(dwSize);
        if (pIfTable == NULL) {
            printf("Error allocating memory\n");
            exit (1);
        }
    }
    // Make a second call to GetIfTable to get the actual
    // data we want.
    if ((dwRetVal = GetIfTable(pIfTable, &dwSize, 0)) == NO_ERROR) {
        if (pIfTable->dwNumEntries > 0) {
            pIfRow = (MIB_IFROW *) MALLOC(sizeof (MIB_IFROW));
            if (pIfRow == NULL) {
                printf("Error allocating memory\n");
                if (pIfTable != NULL) {
                    FREE(pIfTable);
                    pIfTable = NULL;
                }
                exit (1);
            }

            printf("\tNum Entries: %ld\n\n", pIfTable->dwNumEntries);
            for (i = 0; i < pIfTable->dwNumEntries; i++) {
                pIfRow->dwIndex = pIfTable->table[i].dwIndex;
                if ((dwRetVal = GetIfEntry(pIfRow)) == NO_ERROR) {
                    printf("\tIndex:\t %ld\n", pIfRow->dwIndex);
                    printf("\tInterfaceName[%d]:\t ", i);
                    if (pIfRow->wszName != NULL)
                        printf("%ws", pIfRow->wszName);
                    printf("\n");

                    printf("\tDescription[%d]:\t ", i);
                    for (j = 0; j < pIfRow->dwDescrLen; j++)
                        printf("%c", pIfRow->bDescr[j]);
                    printf("\n");

                    printf("\tIndex[%d]:\t\t %d\n", i, pIfRow->dwIndex);

                    printf("\tType[%d]:\t\t ", i);
                    switch (pIfRow->dwType) {
                    case IF_TYPE_OTHER:
                        printf("Other\n");
                        break;
                    case IF_TYPE_ETHERNET_CSMACD:
                        printf("Ethernet\n");
                        break;
                    case IF_TYPE_ISO88025_TOKENRING:
                        printf("Token Ring\n");
                        break;
                    case IF_TYPE_PPP:
                        printf("PPP\n");
                        break;
                    case IF_TYPE_SOFTWARE_LOOPBACK:
                        printf("Software Lookback\n");
                        break;
                    case IF_TYPE_ATM:
                        printf("ATM\n");
                        break;
                    case IF_TYPE_IEEE80211:
                        printf("IEEE 802.11 Wireless\n");
                        break;
                    case IF_TYPE_TUNNEL:
                        printf("Tunnel type encapsulation\n");
                        break;
                    case IF_TYPE_IEEE1394:
                        printf("IEEE 1394 Firewire\n");
                        break;
                    default:
                        printf("Unknown type %ld\n", pIfRow->dwType);
                        break;
                    }

                    printf("\tMtu[%d]:\t\t %ld\n", i, pIfRow->dwMtu);

                    printf("\tSpeed[%d]:\t\t %ld\n", i, pIfRow->dwSpeed);

                    printf("\tPhysical Addr:\t\t ");
                    if (pIfRow->dwPhysAddrLen == 0)
                        printf("\n");
//                    for (j = 0; j < (int) pIfRow->dwPhysAddrLen; j++) {
                    for (j = 0; j < pIfRow->dwPhysAddrLen; j++) {
                        if (j == (pIfRow->dwPhysAddrLen - 1))
                            printf("%.2X\n", (int) pIfRow->bPhysAddr[j]);
                        else
                            printf("%.2X-", (int) pIfRow->bPhysAddr[j]);
                    }
                    printf("\tAdmin Status[%d]:\t %ld\n", i,
                           pIfRow->dwAdminStatus);

                    printf("\tOper Status[%d]:\t ", i);
                    switch (pIfRow->dwOperStatus) {
                    case IF_OPER_STATUS_NON_OPERATIONAL:
                        printf("Non Operational\n");
                        break;
                    case IF_OPER_STATUS_UNREACHABLE:
                        printf("Unreasonable\n");
                        break;
                    case IF_OPER_STATUS_DISCONNECTED:
                        printf("Disconnected\n");
                        break;
                    case IF_OPER_STATUS_CONNECTING:
                        printf("Connecting\n");
                        break;
                    case IF_OPER_STATUS_CONNECTED:
                        printf("Connected\n");
                        break;
                    case IF_OPER_STATUS_OPERATIONAL:
                        printf("Operational\n");
                        break;
                    default:
                        printf("Unknown status %ld\n", 
                            pIfRow->dwOperStatus);
                        break;
                    }
                    printf("\n");
                }

                else {
                    printf("GetIfEntry failed for index %d with error: %ld\n",
                           i, dwRetVal);
                    // Here you can use FormatMessage to find out why 
                    // it failed.

                }
            }
        } else {
            printf("\tGetIfTable failed with error: %ld\n", dwRetVal);
        }

    }
    
    exit (0);
}

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

Vedi anche

GetIfEntry2

GetIfTable

GetIfTable2

GetIfTable2Ex

GetNumberOfInterfaces

Informazioni di riferimento sulla funzione helper IP

MIB_IFROW

MIB_IFTABLE

MIB_IF_ROW2

MIB_IF_TABLE2

SetIfEntry