GetIfEntry-Funktion (iphlpapi.h)

Die GetIfEntry-Funktion ruft Informationen für die angegebene Schnittstelle auf dem lokalen Computer ab.

Syntax

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

Parameter

[in, out] pIfRow

Ein Zeiger auf eine MIB_IFROW Struktur, die bei erfolgreicher Rückgabe Informationen für eine Schnittstelle auf dem lokalen Computer empfängt. Legen Sie bei der Eingabe den dwIndex-Member von MIB_IFROW auf den Index der Schnittstelle fest, für die Informationen abgerufen werden sollen. Der Wert für dwIndex muss durch einen vorherigen Aufruf der Funktion GetIfTable, GetIfTable2 oder GetIfTable2Ex abgerufen werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.

Rückgabecode Beschreibung
ERROR_CAN_NOT_COMPLETE
Die Anforderung konnte nicht abgeschlossen werden. Dies ist ein interner Fehler.
ERROR_INVALID_DATA
Ungültige Daten. Dieser Fehler wird zurückgegeben, wenn der Netzwerkschnittstellenindex, der vom dwIndex-Member der MIB_IFROW Struktur angegeben wird, auf die der pIfRow-Parameter verweist, kein gültiger Schnittstellenindex auf dem lokalen Computer ist.
ERROR_INVALID_PARAMETER
Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein NULL-Zeiger im pIfRow-Parameter übergeben wird.
ERROR_NOT_FOUND
Die angegebene Schnittstelle konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn der netzwerkschnittstellenindex, der vom dwIndex-Element der MIB_IFROW-Struktur angegeben wurde, auf die der pIfRow-Parameter verweist, nicht gefunden werden konnte.
ERROR_NOT_SUPPORTED
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn IPv4 auf dem lokalen Computer nicht konfiguriert ist.
Andere
Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die GetIfEntry-Funktion ruft Informationen für eine Schnittstelle auf einem lokalen Computer ab.

Der dwIndex-Member in der MIB_IFROW Struktur, auf die der pIfRow-Parameter verweist, muss in einem gültigen Netzwerkschnittstellenindex initialisiert werden, der durch einen vorherigen Aufruf der GetIfTable-, GetIfTable2- oder GetIfTable2Ex-Funktion abgerufen wurde.

Die GetIfEntry-Funktion schlägt fehl, wenn der dwIndex-Member des MIB_IFROW , auf den der pIfRow-Parameter verweist, nicht mit einem vorhandenen Schnittstellenindex auf dem lokalen Computer übereinstimmt.

Beispiele

Im folgenden Beispiel werden die Einträge aus der Schnittstellentabelle abgerufen und einige der für diesen Eintrag verfügbaren Informationen ausgegeben.

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

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile iphlpapi.h
Bibliothek Iphlpapi.lib
DLL Iphlpapi.dll

Weitere Informationen

GetIfEntry2

GetIfTable

GetIfTable2

GetIfTable2Ex

GetNumberOfInterfaces

Ip-Hilfsfunktionsreferenz

MIB_IFROW

MIB_IFTABLE

MIB_IF_ROW2

MIB_IF_TABLE2

SetIfEntry