Функция GetIfTable (iphlpapi.h)

Статья
08/24/2023

Функция GetIfTable извлекает таблицу интерфейса MIB-II.

Синтаксис

IPHLPAPI_DLL_LINKAGE DWORD GetIfTable(
  [out]     PMIB_IFTABLE pIfTable,
  [in, out] PULONG       pdwSize,
  [in]      BOOL         bOrder
);

Параметры

[out] pIfTable

Указатель на буфер, который получает таблицу интерфейса в виде структуры MIB_IFTABLE .

[in, out] pdwSize

На входных данных указывает размер буфера в байтах, на который указывает параметр pIfTable .

В выходных данных, если буфер недостаточно велик для хранения возвращаемой таблицы интерфейса, функция устанавливает этот параметр равным требуемому размеру буфера в байтах.

[in] bOrder

Логическое значение, указывающее, следует ли отсортировать возвращаемую таблицу интерфейса в порядке возрастания по индексу интерфейса. Если этот параметр имеет значение TRUE, таблица сортируется.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.

Если функция завершается сбоем, возвращается один из следующих кодов ошибок.

Код возврата	Описание
ERROR_INSUFFICIENT_BUFFER	Буфер, на который указывает параметр pIfTable, недостаточно велик. Требуемый размер возвращается в переменной DWORD , на которую указывает параметр pdwSize .
ERROR_INVALID_PARAMETER	Параметр pdwSize имеет значение NULL, или GetIfTable не может выполнить запись в память, на которую указывает параметр pdwSize .
ERROR_NOT_SUPPORTED	Эта функция не поддерживается в операционной системе, используемой в локальной системе.
Другое	Используйте функцию FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

The
Функция GetIfTable перечисляет физические интерфейсы в локальной системе и возвращает эти сведения в MIB_IFTABLE структуре. Физические интерфейсы включают программный интерфейс замыкания на себя.

Функции GetIfTable2 и GetIfTable2Ex , доступные в Windows Vista и более поздних версиях, являются расширенной версией функции GetIfTable , которая перечисляет физический и логический интерфейсы в локальной системе. Логические интерфейсы включают различные интерфейсы минипорта глобальной сети, используемые для инкапсуляции L2TP, PPTP, PPOE и других туннелей.

Интерфейсы возвращаются в MIB_IFTABLE структуре в буфере, на который указывает параметр pIfTable . Структура MIB_IFTABLE содержит число интерфейсов и массив MIB_IFROW структур для каждого интерфейса.

Обратите внимание, что возвращаемая структура MIB_IFTABLE , на которую указывает параметр pIfTable, может содержать заполнение для выравнивания между элементом dwNumEntries и первой записью массива MIB_IFROW в элементе таблицыструктуры MIB_IFTABLE . Между MIB_IFROW записями массива также может присутствовать заполнение для выравнивания. Любой доступ к MIB_IFROW записи массива должен предполагать наличие заполнения.

Примеры

В следующем примере извлекается таблица интерфейса и выводится количество записей в таблице и некоторые данные по каждой записи.

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

    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");
        return 1;
    }
    // Make an initial call to GetIfTable to get the
    // necessary size into dwSize
    dwSize = sizeof (MIB_IFTABLE);
    if (GetIfTable(pIfTable, &dwSize, FALSE) == ERROR_INSUFFICIENT_BUFFER) {
        FREE(pIfTable);
        pIfTable = (MIB_IFTABLE *) MALLOC(dwSize);
        if (pIfTable == NULL) {
            printf("Error allocating memory needed to call GetIfTable\n");
            return 1;
        }
    }
    // Make a second call to GetIfTable to get the actual
    // data we want.
    if ((dwRetVal = GetIfTable(pIfTable, &dwSize, FALSE)) == NO_ERROR) {
        printf("\tNum Entries: %ld\n\n", pIfTable->dwNumEntries);
        for (i = 0; i < pIfTable->dwNumEntries; i++) {
            pIfRow = (MIB_IFROW *) & pIfTable->table[i];
            printf("\tIndex[%d]:\t %ld\n", i, pIfRow->dwIndex);
            printf("\tInterfaceName[%d]:\t %ws", i, pIfRow->wszName);
            printf("\n");
            printf("\tDescription[%d]:\t ", i);
            for (j = 0; j < pIfRow->dwDescrLen; j++)
                printf("%c", pIfRow->bDescr[j]);
            printf("\n");
            printf("\tType[%d]:\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 %ld\n", i, pIfRow->dwSpeed);
            printf("\tPhysical Addr:\t ");
            if (pIfRow->dwPhysAddrLen == 0)
                printf("\n");
            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("Unreachable\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->dwAdminStatus);
                break;
            }
            printf("\n");
        }
    } else {
        printf("GetIfTable failed with error: \n", dwRetVal);
        if (pIfTable != NULL) {
            FREE(pIfTable);
            pIfTable = NULL;
        }  
        return 1;
        // Here you can use FormatMessage to find out why 
        // it failed.
    }
    if (pIfTable != NULL) {
        FREE(pIfTable);
        pIfTable = NULL;
    }
    return 0;
}

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	iphlpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll