Compartir a través de


Función AddIPAddress (iphlpapi.h)

La función AddIPAddress agrega la dirección IPv4 especificada al adaptador especificado.

Sintaxis

IPHLPAPI_DLL_LINKAGE DWORD AddIPAddress(
  [in]  IPAddr Address,
  [in]  IPMask IpMask,
  [in]  DWORD  IfIndex,
  [out] PULONG NTEContext,
  [out] PULONG NTEInstance
);

Parámetros

[in] Address

Dirección IPv4 que se va a agregar al adaptador, en forma de una estructura IPAddr .

[in] IpMask

Máscara de subred de la dirección IPv4 especificada en el parámetro Address . El parámetro IPMask usa el mismo formato que una estructura IPAddr .

[in] IfIndex

Índice del adaptador en el que se va a agregar la dirección IPv4.

[out] NTEContext

Puntero a una variable ULONG . Si la devolución se realiza correctamente, este parámetro apunta al contexto de entrada de tabla de red (NTE) para la dirección IPv4 que se agregó. El autor de la llamada puede usar más adelante este contexto en una llamada a la función DeleteIPAddress .

[out] NTEInstance

Puntero a una variable ULONG . Si la devolución se realiza correctamente, este parámetro apunta a la instancia de NTE para la dirección IPv4 que se agregó.

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_DEV_NOT_EXIST
El adaptador especificado por el parámetro IfIndex no existe.
ERROR_DUP_DOMAINNAME
La dirección IPv4 que se va a agregar que se especifica en el parámetro Address ya existe.
ERROR_GEN_FAILURE
Error general. Este error se devuelve para algunos valores especificados en el parámetro Address , como una dirección IPv4 que normalmente se considera una dirección de difusión.
ERROR_INVALID_HANDLE
El usuario que intenta realizar la llamada de función no es un administrador.
ERROR_INVALID_PARAMETER
Uno o varios de los parámetros no son válidos. Este error se devuelve si los parámetros NTEContext o NTEInstance son NULL. Este error también se devuelve cuando la dirección IP especificada en el parámetro Address es incoherente con el índice de interfaz especificado en el parámetro IfIndex (por ejemplo, una dirección de bucle invertido en una interfaz que no es de bucle invertido).
ERROR_NOT_SUPPORTED
La llamada de función no se admite en la versión de Windows en la que se ejecutó.
Otros
Use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Comentarios

La función AddIPAddress se usa para agregar una nueva entrada de dirección IPv4 en un equipo local. La dirección IPv4 agregada por la función AddIPAddress no es persistente. La dirección IPv4 solo existe siempre y cuando exista el objeto de adaptador. Al reiniciar el equipo, se destruye la dirección IPv4, como se restableced manualmente la tarjeta de interfaz de red (NIC). Además, ciertos eventos PnP pueden destruir la dirección.

Para crear una dirección IPv4 que persista, se puede usar el método EnableStatic de la clase Win32_NetworkAdapterConfiguration en los controles instrumental de administración de Windows (WMI). Los comandos netsh también se pueden usar para crear una dirección IPv4 persistente.

Para obtener más información, consulte la documentación sobre Netsh.exe en la documentación de Windows Sockets.

En Windows Server 2003, Windows XP y Windows 2000, si la dirección IPv4 del parámetro Address ya existe en la red, la función AddIPAddress devuelve NO_ERROR y la dirección IPv4 agregada es 0.0.0.0.0.

En Windows Vista y versiones posteriores, si la dirección IPv4 pasada en el parámetro Address ya existe en la red, la función AddIPAddress devuelve NO_ERROR y la dirección IPv4 duplicada se agrega con el miembro IP_DAD_STATE en la estructura IP_ADAPTER_UNICAST_ADDRESS establecida en IpDadStateDuplicate.

Una dirección IPv4 que se agrega mediante la función AddIPAddress se puede eliminar más adelante llamando a la función DeleteIPAddress pasando el parámetro NTEContext devuelto por la función AddIPAddress .

Para obtener información sobre los tipos de datos IPAddr e IPMask , vea Tipos de datos de Windows. Para convertir una dirección IPv4 entre la notación decimal con puntos y el formato IPAddr , use las funciones inet_addr y inet_ntoa .

En Windows Vista y versiones posteriores, se puede usar la función CreateUnicastIpAddressEntry para agregar una nueva entrada de dirección IPv4 o IPv6 de unidifusión en un equipo local.

Ejemplos

En el ejemplo siguiente se recupera la tabla de direcciones IP para determinar el índice de interfaz del primer adaptador y, a continuación, se agrega la dirección IP especificada en la línea de comandos al primer adaptador. A continuación, se elimina la dirección IP que se agregó.

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>

#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 argc, char **argv)
{

    /* Variables used by GetIpAddrTable */
    PMIB_IPADDRTABLE pIPAddrTable;
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;
    IN_ADDR IPAddr;
    DWORD ifIndex;

    /* IPv4 address and subnet mask we will be adding */
    UINT iaIPAddress;
    UINT iaIPMask;

    /* Variables where handles to the added IP are returned */
    ULONG NTEContext = 0;
    ULONG NTEInstance = 0;

    /* Variables used to return error message */
    LPVOID lpMsgBuf;

    // Validate the parameters
    if (argc != 3) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    iaIPAddress = inet_addr(argv[1]);
    if (iaIPAddress == INADDR_NONE) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    iaIPMask = inet_addr(argv[2]);
    if (iaIPMask == INADDR_NONE) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    // 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 == NULL) {
        printf("Error allocating memory needed to call GetIpAddrTable\n");
        exit (1);
    }
    else {
        dwSize = 0;
        // 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) {
        // Save the interface index to use for adding an IP address
        ifIndex = pIPAddrTable->table[0].dwIndex;
        printf("\n\tInterface Index:\t%ld\n", ifIndex);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwAddr;
        printf("\tIP Address:       \t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwAddr);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwMask;
        printf("\tSubnet Mask:      \t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwMask);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwBCastAddr;
        printf("\tBroadCast Address:\t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwBCastAddr);
        printf("\tReassembly size:  \t%lu\n\n",
               pIPAddrTable->table[0].dwReasmSize);
    } else {
        printf("Call to GetIpAddrTable failed with error %d.\n", dwRetVal);
        if (pIPAddrTable)
            FREE(pIPAddrTable);
        exit(1);
    }

    if (pIPAddrTable) {
        FREE(pIPAddrTable);
        pIPAddrTable = NULL;
    }

    if ((dwRetVal = AddIPAddress(iaIPAddress,
                                 iaIPMask,
                                 ifIndex,
                                 &NTEContext, &NTEInstance)) == NO_ERROR) {
        printf("\tIPv4 address %s was successfully added.\n", argv[1]);
    } else {
        printf("AddIPAddress 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);
        }
    }

// Delete the IP we just added using the NTEContext
// variable where the handle was returned       
    if ((dwRetVal = DeleteIPAddress(NTEContext)) == NO_ERROR) {
        printf("\tIPv4 address %s was successfully deleted.\n", argv[1]);
    } else {
        printf("\tDeleteIPAddress failed with error: %d\n", dwRetVal);
        exit(1);
    }

    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

Consulte también

CreateUnicastIpAddressEntry

DeleteIPAddress

GetAdapterIndex

GetIpAddrTable

Referencia de la función auxiliar de IP

Página de inicio del asistente de IP

IPAddr