GetInterfaceInfo-Funktion (iphlpapi.h)

Artikel
08/24/2023

Die GetInterfaceInfo-Funktion ruft die Liste der Netzwerkschnittstellenadapter ab, bei denen IPv4 auf dem lokalen System aktiviert ist.

Syntax

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

Parameter

[out] pIfTable

Ein Zeiger auf einen Puffer, der eine IP_INTERFACE_INFO Struktur angibt, die die Liste der Adapter empfängt. Dieser Puffer muss vom Aufrufer zugewiesen werden.

[in, out] dwOutBufLen

Ein Zeiger auf eine DWORD-Variable , der die Größe des Puffers angibt, auf den der pIfTable-Parameter verweist, um die IP_INTERFACE_INFO Struktur zu empfangen. Wenn diese Größe nicht ausreicht, um die IPv4-Schnittstelleninformationen zu enthalten, füllt GetInterfaceInfo diese Variable mit der erforderlichen Größe aus und gibt einen Fehlercode mit ERROR_INSUFFICIENT_BUFFER zurück.

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_INSUFFICIENT_BUFFER	Der Puffer zum Empfangen der IPv4-Adapterinformationen ist zu klein. Dieser Wert wird zurückgegeben, wenn der dwOutBufLen-Parameter angibt, dass der Puffer, auf den der pIfTable-Parameter verweist, zu klein ist, um die IPv4-Schnittstelleninformationen abzurufen. Die erforderliche Größe wird in der DWORD-Variable zurückgegeben, auf die der dwOutBufLen-Parameter verweist.
ERROR_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn der dwOutBufLen-ParameterNULL ist oder GetInterfaceInfo nicht in den Speicher schreiben kann, auf den der dwOutBufLen-Parameter verweist.
ERROR_NO_DATA	Es sind keine Netzwerkadapter für IPv4 auf dem lokalen System aktiviert. Dieser Wert wird auch zurückgegeben, wenn alle Netzwerkadapter auf dem lokalen System deaktiviert sind.
ERROR_NOT_SUPPORTED	Diese Funktion wird auf dem Betriebssystem, das auf dem lokalen System verwendet wird, nicht unterstützt.
Andere	Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die GetInterfaceInfo-Funktion ist spezifisch für Netzwerkadapter, bei denen IPv4 aktiviert ist. Die Funktion gibt eine IP_INTERFACE_INFO Struktur zurück, auf die der pIfTable-Parameter verweist, der die Anzahl von Netzwerkadaptern mit aktiviertem IPv4 auf dem lokalen System und ein Array von IP_ADAPTER_INDEX_MAP Strukturen mit Informationen zu jedem Netzwerkadapter mit aktiviertem IPv4 enthält. Die vonGetInterfaceInfo zurückgegebene IP_INTERFACE_INFO-Struktur enthält mindestens eine IP_ADAPTER_INDEX_MAP-Struktur , auch wenn das NumAdapters-Element der IP_INTERFACE_INFO-Struktur angibt, dass keine Netzwerkadapter mit IPv4 aktiviert sind. Wenn das NumAdapters-Element der vonGetInterfaceInfo zurückgegebenen IP_INTERFACE_INFO-Struktur 0 ist, ist der Wert der Elemente der einzelnen IP_ADAPTER_INDEX_MAP Struktur, die in der IP_INTERFACE_INFO-Struktur zurückgegeben werden, undefiniert.

Wenn die GetInterfaceInfo-Funktion mit einem zu kleinen Puffer aufgerufen wird, um die IPv4-Schnittstelleninformationen abzurufen (der dwOutBufLen-Parameter gibt an, dass der Puffer, auf den der pIfTable-Parameter verweist, zu klein ist), gibt die Funktion ERROR_INSUFFICIENT_BUFFER zurück. Die erforderliche Größe wird in der DWORD-Variable zurückgegeben, auf die der dwOutBufLen-Parameter verweist.

Die richtige Möglichkeit, die GetInterfaceInfo-Funktion zu verwenden, besteht darin, diese Funktion zweimal aufzurufen. Übergeben Sie im ersten Aufruf einen NULL-Zeiger im pIfTable-Parameter und null in der Variablen, auf die der dwOutBufLen-Parameter verweist. Der Aufruf schlägt mit ERROR_INSUFFICIENT_BUFFER fehl, und die erforderliche Größe für diesen Puffer wird in der DWORD-Variablen zurückgegeben, auf die der dwOutBufLen-Parameter verweist. Ein Puffer kann dann mit der erforderlichen Größe zugeordnet werden, indem der Wert verwendet wird, auf den die dwOutBufLen verweist. Dann kann die GetInterfaceInfo-Funktion ein zweites Mal aufgerufen werden, wobei ein Zeiger auf diesen Puffer im pIfTable-Parameter übergeben wird und die Länge des Puffers auf die Größe dieses Puffers festgelegt ist.

Die Funktionen GetAdaptersInfo und GetInterfaceInfo geben keine Informationen zur Loopbackschnittstelle zurück. Informationen zur Loopbackschnittstelle werden von der GetIpAddrTable-Funktion zurückgegeben.

Unter Windows Vista und höher kann der Name-Member der IP_ADAPTER_INDEX_MAP-Struktur , die in der IP_INTERFACE_INFO-Struktur zurückgegeben wird, eine Unicode-Zeichenfolge der GUID für die Netzwerkschnittstelle sein (die Zeichenfolge beginnt mit dem Zeichen '{').

Beispiele

Im folgenden Beispiel wird die Liste der Netzwerkadapter abgerufen, für die IPv4 auf dem lokalen System aktiviert ist, und es werden verschiedene Eigenschaften des ersten Netzwerkadapters ausgegeben.

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

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