Função GetIpAddrTable (iphlpapi.h)
A função GetIpAddrTable recupera a tabela de mapeamento de endereços IPv4 de interface para.
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 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 como 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 retornado
Se a função for bem-sucedida, o valor retornado será NO_ERROR.
Se a função falhar, o valor retornado será um dos códigos de erro a seguir.
| Código de retorno | Descrição |
|---|---|
|
O buffer apontado pelo parâmetro pIpAddrTable não é grande o suficiente. O tamanho necessário é retornado na variável DWORD apontada pelo parâmetro pdwSize . |
|
O parâmetro pdwSize é NULL ou GetIpAddrTable não pode gravar na memória apontada pelo parâmetro pdwSize . |
|
Não há suporte para essa função no sistema operacional em uso no sistema local. |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
A função GetIpAddrTable recupera a tabela de mapeamento de endereços IPv4 da interface 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 (cartão 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 o recurso de detecção de mídia da pilha TCP/IP em um computador local tiver sido desabilitado chamando a função DisableMediaSense . Quando o sensoriamento de mídia tiver sido desabilitado, 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 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 da matriz MIB_IPADDRROW no membro da tabela . Qualquer acesso a uma entrada de matriz MIB_IPADDRROW deve assumir que o preenchimento pode existir.
No Microsoft Windows Software Development Kit (SDK) lançado para Windows Vista e posterior, a organização de arquivos de cabeçalho foi alterada e o MIB_IPADDRROW é definido no arquivo de cabeçalho Ipmib.h que não está 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);
}
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | iphlpapi.h |
| Biblioteca | Iphlpapi.lib |
| DLL | Iphlpapi.dll |