Função GetInterfaceInfo (iphlpapi.h)

Artigo
08/24/2023

A função GetInterfaceInfo obtém a lista dos adaptadores de interface de rede com IPv4 habilitado no sistema local.

Sintaxe

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

Parâmetros

[out] pIfTable

Um ponteiro para um buffer que especifica uma estrutura IP_INTERFACE_INFO que recebe a lista de adaptadores. Esse buffer deve ser alocado pelo chamador.

[in, out] dwOutBufLen

Um ponteiro para uma variável DWORD que especifica o tamanho do buffer apontado pelo parâmetro pIfTable para receber a estrutura IP_INTERFACE_INFO . Se esse tamanho for insuficiente para manter as informações da interface IPv4, GetInterfaceInfo preencherá essa variável com o tamanho necessário e retornará um código de erro de ERROR_INSUFFICIENT_BUFFER.

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 seguintes códigos de erro.

Código de retorno	Descrição
ERROR_INSUFFICIENT_BUFFER	O buffer para receber as informações do adaptador IPv4 é muito pequeno. Esse valor será retornado se o parâmetro dwOutBufLen indicar que o buffer apontado pelo parâmetro pIfTable é muito pequeno para recuperar as informações da interface IPv4. O tamanho necessário é retornado na variável DWORD apontada pelo parâmetro dwOutBufLen .
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se o parâmetro dwOutBufLen for NULL ou GetInterfaceInfo não conseguir gravar na memória apontada pelo parâmetro dwOutBufLen .
ERROR_NO_DATA	Não há adaptadores de rede habilitados para IPv4 no sistema local. Esse valor também será retornado se todos os adaptadores de rede no sistema local estiverem desabilitados.
ERROR_NOT_SUPPORTED	Não há suporte para essa função no sistema operacional em uso no sistema local.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função GetInterfaceInfo é específica para adaptadores de rede com IPv4 habilitado. A função retorna uma estrutura IP_INTERFACE_INFO apontada pelo parâmetro pIfTable que contém o número de adaptadores de rede com IPv4 habilitado no sistema local e uma matriz de estruturas IP_ADAPTER_INDEX_MAP com informações sobre cada adaptador de rede com IPv4 habilitado. A estrutura IP_INTERFACE_INFO retornada por GetInterfaceInfo contém pelo menos uma estrutura IP_ADAPTER_INDEX_MAP mesmo que o membro NumAdapters da estrutura IP_INTERFACE_INFO indique que nenhum adaptador de rede com IPv4 está habilitado. Quando o membro NumAdapters da estrutura IP_INTERFACE_INFO retornado por GetInterfaceInfo é zero, o valor dos membros da estrutura de IP_ADAPTER_INDEX_MAP única retornada na estrutura IP_INTERFACE_INFO é indefinido.

Se a função GetInterfaceInfo for chamada com um buffer muito pequeno para recuperar as informações da interface IPv4 (o parâmetro dwOutBufLen indica que o buffer apontado pelo parâmetro pIfTable é muito pequeno), a função retornará ERROR_INSUFFICIENT_BUFFER. O tamanho necessário é retornado na variável DWORD apontada pelo parâmetro dwOutBufLen .

A maneira correta de usar a função GetInterfaceInfo é chamar essa função duas vezes. Na primeira chamada, passe um ponteiro NULL no parâmetro pIfTable e zero na variável apontada pelo parâmetro dwOutBufLen . A chamada falhará com ERROR_INSUFFICIENT_BUFFER e o tamanho necessário para esse buffer será retornado na variável DWORD apontada pelo parâmetro dwOutBufLen . Em seguida, um buffer pode ser alocado do tamanho necessário usando o valor apontado pelo dwOutBufLen. Em seguida, a função GetInterfaceInfo pode ser chamada uma segunda vez com um ponteiro para esse buffer passado no parâmetro pIfTable e o comprimento do buffer definido para o tamanho desse buffer.

As funções GetAdaptersInfo e GetInterfaceInfo não retornam informações sobre a interface de loopback. As informações sobre a interface de loopback são retornadas pela função GetIpAddrTable .

No Windows Vista e posterior, o membro Name da estrutura IP_ADAPTER_INDEX_MAP retornado na estrutura IP_INTERFACE_INFO pode ser uma cadeia de caracteres Unicode do GUID para o adaptador de rede (a cadeia de caracteres começa com o caractere '{').

Exemplos

O exemplo a seguir recupera a lista de adaptadores de rede com IPv4 habilitado no sistema local e imprime várias propriedades do primeiro adaptador de rede.

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

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