Función GetIpAddrTable (iphlpapi.h)

Artículo
08/24/2023

La función GetIpAddrTable recupera la tabla de asignación de direcciones de interfaz a IPv4.

Sintaxis

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

Parámetros

[out] pIpAddrTable

Puntero a un búfer que recibe la tabla de asignación de direcciones IPv4 de interfaz a IPv4 como una estructura de MIB_IPADDRTABLE .

[in, out] pdwSize

En la entrada, especifica el tamaño en bytes del búfer al que apunta el parámetro pIpAddrTable .

En la salida, si el búfer no es lo suficientemente grande como para contener la tabla de asignación devuelta, la función establece este parámetro igual al tamaño de búfer necesario en bytes.

[in] bOrder

Si este parámetro es TRUE, la tabla de asignación devuelta se ordena en orden ascendente por dirección IPv4. La ordenación se realiza en orden de bytes de red. Por ejemplo, 10.0.0.255 viene inmediatamente antes de la versión 10.0.1.0.

Valor devuelto

Si la función se realiza 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 al que apunta el parámetro pIpAddrTable no es lo suficientemente grande. El tamaño necesario se devuelve en la variable DWORD a la que apunta el parámetro pdwSize .
ERROR_INVALID_PARAMETER	El parámetro pdwSize es NULL o GetIpAddrTable no puede escribir en la memoria a la que apunta el parámetro pdwSize .
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 GetIpAddrTable recupera la tabla de asignación de direcciones de interfaz a IPv4 en un equipo local y devuelve esta información en una estructura MIB_IPADDRTABLE .

Las direcciones IPv4 devueltas por la función GetIpAddrTable se ven afectadas por el estado de las interfaces de red en un equipo local. Restablecer manualmente una tarjeta de interfaz de red (NIC) y ciertos eventos PnP pueden dar lugar a que se quite o cambie una dirección IP.

En Windows Server 2003 y Windows XP, las direcciones IPv4 devueltas por la función GetIpAddrTable también se ven afectadas si la funcionalidad de detección multimedia de la pila TCP/IP en un equipo local se ha deshabilitado llamando a la función DisableMediaSense . Cuando se ha deshabilitado la detección de medios, la función GetIpAddrTable puede devolver direcciones IPv4 asociadas a interfaces desconectadas. Estas direcciones Ipv4 para interfaces desconectadas no son válidas para su uso.

En Windows Server 2008 y Windows Vista, las direcciones IPv4 devueltas por la función GetIpAddrTable no se ven afectadas por la funcionalidad de detección multimedia de la pila TCP/IP en un equipo local. La función GetIpAddrTable devuelve solo direcciones IPv4 válidas.

La función GetAdaptersAddresses disponible en Windows XP se puede usar para recuperar direcciones IPv6 e IPv4 e información de interfaz.

La estructura MIB_IPADDRTABLE devuelta por la función GetIpAddrTable puede contener relleno para la alineación entre el miembro dwNumEntries y la primera entrada de matriz MIB_IPADDRROW del miembro de tabla . El relleno para la alineación también puede estar presente entre las entradas de matriz de MIB_IPADDRROW en el miembro de tabla . Cualquier acceso a una entrada de matriz MIB_IPADDRROW debe suponer que puede existir relleno.

En el Kit de desarrollo de software (SDK) de Microsoft Windows publicado para Windows Vista y versiones posteriores, la organización de los archivos de encabezado ha cambiado y el MIB_IPADDRROW se define en el archivo de encabezado Ipmib.h no en el archivo de encabezado Iprtrmib.h . Tenga en cuenta que el archivo de encabezado Ipmib.h se incluye automáticamente en Iprtrmib.h , que se incluye automáticamente en el archivo de encabezado Iphlpapi.h . Los archivos de encabezado Ipmib.h e Iprtrmib.h nunca se deben usar directamente.

Ejemplos

En el ejemplo siguiente se recupera la tabla de direcciones IP y, a continuación, se imprimen algunos miembros de las entradas de dirección IP de la tabla.

#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 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