Función GetInterfaceInfo (iphlpapi.h)
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 |
|---|---|
|
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 . |
|
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 . |
|
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. |
|
Esta función no se admite en el sistema operativo en uso en el sistema local. |
|
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 |
Consulte también
Referencia de la función auxiliar de IP