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

Статья
08/24/2023

Функция GetIpAddrTable извлекает таблицу сопоставления адресов interface-to-IPv4.

Синтаксис

IPHLPAPI_DLL_LINKAGE DWORD GetIpAddrTable(
  [out]     PMIB_IPADDRTABLE pIpAddrTable,
  [in, out] PULONG           pdwSize,
  [in]      BOOL             bOrder
);

Параметры

[out] pIpAddrTable

Указатель на буфер, который получает таблицу сопоставления адресов interface-to-IPv4 в виде структуры MIB_IPADDRTABLE .

[in, out] pdwSize

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

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

[in] bOrder

Если этот параметр имеет значение TRUE, то возвращаемая таблица сопоставления сортируется по IPv4-адресу в порядке возрастания. Сортировка выполняется в сетевом порядке байтов. Например, 10.0.0.255 выходит непосредственно перед 10.0.1.0.

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

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

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

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

На IPv4-адреса, возвращаемые функцией GetIpAddrTable , влияет состояние сетевых интерфейсов на локальном компьютере. Сброс сетевого интерфейса вручную карта (NIC) и некоторых событий PnP может привести к удалению или изменению IP-адреса.

В Windows Server 2003 и Windows XP IPv4-адреса, возвращаемые функцией GetIpAddrTable , также затрагиваются, если функция отслеживания мультимедиа в стеке TCP/IP на локальном компьютере была отключена путем вызова функции DisableMediaSense . Если функция GetIpAddrTable отключена, функция GetIpAddrTable может возвращать IPv4-адреса, связанные с отключенными интерфейсами. Эти ipv4-адреса для отключенных интерфейсов недопустимы для использования.

В Windows Server 2008 и Windows Vista IPv4-адреса, возвращаемые функцией GetIpAddrTable , не затрагиваются возможностью отслеживания мультимедиа в стеке TCP/IP на локальном компьютере. Функция GetIpAddrTable возвращает только допустимые IPv4-адреса.

Функцию GetAdaptersAddresses , доступную в Windows XP, можно использовать для получения адресов IPv6 и IPv4 и сведений об интерфейсе.

Структура MIB_IPADDRTABLE , возвращаемая функцией GetIpAddrTable , может содержать заполнение для выравнивания между элементом dwNumEntries и первой записью массива MIB_IPADDRROW в элементе таблицы . Между MIB_IPADDRROW записями массива в элементе таблицы также может присутствовать заполнение для выравнивания. Любой доступ к записи MIB_IPADDRROW массива должен предполагать, что может существовать заполнение.

В пакете SDK для Windows, выпущенном для Windows Vista и более поздних версий, организация файлов заголовков изменилась, и MIB_IPADDRROW определяется в файле заголовка Ipmib.h , а не в файле заголовка Iprtrmib.h . Обратите внимание, что файл заголовка Ipmib.h автоматически включается в файл заголовка Iprtrmib.h , который автоматически включается в файл заголовка Iphlpapi.h . Файлы заголовков Ipmib.h и Iprtrmib.h никогда не следует использовать напрямую.

Примеры

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

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int __cdecl main()
{

    int i;
    
    /* Variables used by GetIpAddrTable */
    PMIB_IPADDRTABLE pIPAddrTable;
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;
    IN_ADDR IPAddr;

    /* Variables used to return error message */
    LPVOID lpMsgBuf;

    // Before calling AddIPAddress we use GetIpAddrTable to get
    // an adapter to which we can add the IP.
    pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(sizeof (MIB_IPADDRTABLE));

    if (pIPAddrTable) {
        // Make an initial call to GetIpAddrTable to get the
        // necessary size into the dwSize variable
        if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
            ERROR_INSUFFICIENT_BUFFER) {
            FREE(pIPAddrTable);
            pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);

        }
        if (pIPAddrTable == NULL) {
            printf("Memory allocation failed for GetIpAddrTable\n");
            exit(1);
        }
    }
    // Make a second call to GetIpAddrTable to get the
    // actual data we want
    if ( (dwRetVal = GetIpAddrTable( pIPAddrTable, &dwSize, 0 )) != NO_ERROR ) { 
        printf("GetIpAddrTable failed with error %d\n", dwRetVal);
        if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, dwRetVal, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),       // Default language
                          (LPTSTR) & lpMsgBuf, 0, NULL)) {
            printf("\tError: %s", lpMsgBuf);
            LocalFree(lpMsgBuf);
        }
        exit(1);
    }

    printf("\tNum Entries: %ld\n", pIPAddrTable->dwNumEntries);
    for (i=0; i < (int) pIPAddrTable->dwNumEntries; i++) {
        printf("\n\tInterface Index[%d]:\t%ld\n", i, pIPAddrTable->table[i].dwIndex);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwAddr;
        printf("\tIP Address[%d]:     \t%s\n", i, inet_ntoa(IPAddr) );
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwMask;
        printf("\tSubnet Mask[%d]:    \t%s\n", i, inet_ntoa(IPAddr) );
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwBCastAddr;
        printf("\tBroadCast[%d]:      \t%s (%ld%)\n", i, inet_ntoa(IPAddr), pIPAddrTable->table[i].dwBCastAddr);
        printf("\tReassembly size[%d]:\t%ld\n", i, pIPAddrTable->table[i].dwReasmSize);
        printf("\tType and State[%d]:", i);
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_PRIMARY)
            printf("\tPrimary IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DYNAMIC)
            printf("\tDynamic IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DISCONNECTED)
            printf("\tAddress is on disconnected interface");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DELETED)
            printf("\tAddress is being deleted");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_TRANSIENT)
            printf("\tTransient address");
        printf("\n");
    }

    if (pIPAddrTable) {
        FREE(pIPAddrTable);
        pIPAddrTable = NULL;
    }

    exit(0);
}

Требования


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