Função GetIpAddrTable (iphlpapi.h)

A função GetIpAddrTable recupera a tabela de mapeamento de endereços de interface para IPv4.

Sintaxe

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

Parâmetros

[out] pIpAddrTable

Um ponteiro para um buffer que recebe a tabela de mapeamento de endereços IPv4 da interface como uma estrutura de MIB_IPADDRTABLE .

[in, out] pdwSize

Na entrada, especifica o tamanho em bytes do buffer apontado pelo parâmetro pIpAddrTable .

Na saída, se o buffer não for grande o suficiente para manter a tabela de mapeamento retornada, a função definirá esse parâmetro igual ao tamanho do buffer necessário em bytes.

[in] bOrder

Se esse parâmetro for TRUE, a tabela de mapeamento retornada será classificada em ordem crescente pelo endereço IPv4. A classificação é executada na ordem de bytes de rede. Por exemplo, 10.0.0.255 vem imediatamente antes de 10.0.1.0.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro.

Observações

A função GetIpAddrTable recupera a tabela de mapeamento de endereços IPv4 de interface para IPv4 em um computador local e retorna essas informações em uma estrutura MIB_IPADDRTABLE .

Os endereços IPv4 retornados pela função GetIpAddrTable são afetados pelo status dos adaptadores de rede em um computador local. Redefinir manualmente uma NIC (placa de interface de rede) e determinados eventos PnP pode resultar na remoção ou alteração de um endereço IP.

No Windows Server 2003 e no Windows XP, os endereços IPv4 retornados pela função GetIpAddrTable também serão afetados se a capacidade de detecção de mídia da pilha TCP/IP em um computador local tiver sido desabilitada chamando a função DisableMediaSense . Quando a detecção de mídia tiver sido desabilitada, a função GetIpAddrTable poderá retornar endereços IPv4 associados a interfaces desconectadas. Esses endereços Ipv4 para interfaces desconectadas não são válidos para uso.

No Windows Server 2008 e no Windows Vista, os endereços IPv4 retornados pela função GetIpAddrTable não são afetados pela capacidade de detecção de mídia da pilha TCP/IP em um computador local. A função GetIpAddrTable retorna apenas endereços IPv4 válidos.

A função GetAdaptersAddresses disponível no Windows XP pode ser usada para recuperar endereços IPv6 e IPv4 e informações de interface.

A estrutura de MIB_IPADDRTABLE retornada pela função GetIpAddrTable pode conter preenchimento para alinhamento entre o membro dwNumEntries e a primeira entrada de matriz MIB_IPADDRROW no membro da tabela . O preenchimento para alinhamento também pode estar presente entre as entradas de matriz MIB_IPADDRROW no membro da tabela . Qualquer acesso a uma entrada de matriz MIB_IPADDRROW deve assumir que o preenchimento pode existir.

No SDK (Microsoft Windows Software Development Kit) lançado para Windows Vista e posterior, a organização dos arquivos de cabeçalho foi alterada e o MIB_IPADDRROW é definido no arquivo de cabeçalho Ipmib.h não no arquivo de cabeçalho Iprtrmib.h . Observe que o arquivo de cabeçalho Ipmib.h é incluído automaticamente em Iprtrmib.h , que é incluído automaticamente no arquivo de cabeçalho Iphlpapi.h . Os arquivos de cabeçalho Ipmib.h e Iprtrmib.h nunca devem ser usados diretamente.

Exemplos

O exemplo a seguir recupera a tabela de endereços IP e imprime alguns membros das entradas de endereço IP na tabela.

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

Requirements

Consulte também

AddIPAddress

DisableMediaSense

GetAdaptersAddresses

Referência de função auxiliar de IP

IP_ADAPTER_ADDRESSES

MIB_IPADDRROW

MIB_IPADDRTABLE

RestoreMediaSense