Función GetInterfaceInfo (iphlpapi.h)

Artículo
08/24/2023

La función GetInterfaceInfo obtiene la lista de adaptadores de interfaz de red con IPv4 habilitado en el sistema local.

Sintaxis

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

Parámetros

[out] pIfTable

Puntero a un búfer que especifica una estructura IP_INTERFACE_INFO que recibe la lista de adaptadores. El autor de la llamada debe asignar este búfer.

[in, out] dwOutBufLen

Puntero a una variable DWORD que especifica el tamaño del búfer al que apunta el parámetro pIfTable para recibir la estructura IP_INTERFACE_INFO . Si este tamaño no es suficiente para contener la información de la interfaz IPv4, GetInterfaceInfo rellena esta variable con el tamaño necesario y devuelve un código de error de ERROR_INSUFFICIENT_BUFFER.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es NO_ERROR.

Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_INSUFFICIENT_BUFFER	El búfer para recibir la información del adaptador IPv4 es demasiado pequeño. Este valor se devuelve si el parámetro dwOutBufLen indica que el búfer al que apunta el parámetro pIfTable es demasiado pequeño para recuperar la información de la interfaz IPv4. El tamaño necesario se devuelve en la variable DWORD a la que apunta el parámetro dwOutBufLen .
ERROR_INVALID_PARAMETER	Se pasó un parámetro no válido a la función. Este error se devuelve si el parámetro dwOutBufLen es NULL o GetInterfaceInfo no puede escribir en la memoria a la que apunta el parámetro dwOutBufLen .
ERROR_NO_DATA	No hay adaptadores de red habilitados para IPv4 en el sistema local. Este valor también se devuelve si todos los adaptadores de red del sistema local están deshabilitados.
ERROR_NOT_SUPPORTED	Esta función no se admite en el sistema operativo en uso en el sistema local.
Otros	Use FormatMessage para obtener la cadena de mensaje del error devuelto.

Comentarios

La función GetInterfaceInfo es específica de los adaptadores de red con IPv4 habilitado. La función devuelve una estructura IP_INTERFACE_INFO a la que apunta el parámetro pIfTable que contiene el número de adaptadores de red con IPv4 habilitado en el sistema local y una matriz de estructuras de IP_ADAPTER_INDEX_MAP con información sobre cada adaptador de red con IPv4 habilitado. La estructura IP_INTERFACE_INFO devuelta por GetInterfaceInfo contiene al menos una estructura de IP_ADAPTER_INDEX_MAP , incluso si el miembro NumAdapters de la estructura IP_INTERFACE_INFO indica que no hay adaptadores de red con IPv4 habilitados. Cuando el miembro NumAdapters de la estructura de IP_INTERFACE_INFO devuelto por GetInterfaceInfo es cero, el valor de los miembros de la estructura de IP_ADAPTER_INDEX_MAP única devuelta en la estructura IP_INTERFACE_INFO es indefinido.

Si se llama a la función GetInterfaceInfo con un búfer demasiado pequeño para recuperar la información de la interfaz IPv4 (el parámetro dwOutBufLen indica que el búfer al que apunta el parámetro pIfTable es demasiado pequeño), la función devuelve ERROR_INSUFFICIENT_BUFFER. El tamaño necesario se devuelve en la variable DWORD a la que apunta el parámetro dwOutBufLen .

La manera correcta de usar la función GetInterfaceInfo es llamar a esta función dos veces. En la primera llamada, pase un puntero NULL en el parámetro pIfTable y cero en la variable a la que apunta el parámetro dwOutBufLen . Se producirá un error en la llamada con ERROR_INSUFFICIENT_BUFFER y se devolverá el tamaño necesario para este búfer en la variable DWORD a la que apunta el parámetro dwOutBufLen . Después, se puede asignar un búfer del tamaño necesario mediante el valor señalado por dwOutBufLen. A continuación, se puede llamar a la función GetInterfaceInfo una segunda vez con un puntero a este búfer pasado en el parámetro pIfTable y la longitud del búfer establecido en el tamaño de este búfer.

Las funciones GetAdaptersInfo y GetInterfaceInfo no devuelven información sobre la interfaz de bucle invertido. La función GetIpAddrTable devuelve información sobre la interfaz de bucle invertido.

En Windows Vista y versiones posteriores, el miembro Name de la estructura de IP_ADAPTER_INDEX_MAP devuelto en la estructura IP_INTERFACE_INFO puede ser una cadena Unicode del GUID para la interfaz de red (la cadena comienza con el carácter '{').

Ejemplos

En el ejemplo siguiente se recupera la lista de adaptadores de red con IPv4 habilitado en el sistema local e imprime varias propiedades del primer adaptador de red.

#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 compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	iphlpapi.h
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll