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 |
|---|---|
|
El adaptador especificado por el parámetro IfIndex no existe. |
|
La dirección IPv4 que se va a agregar que se especifica en el parámetro Address ya existe. |
|
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. |
|
El usuario que intenta realizar la llamada de función no es un administrador. |
|
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). |
|
La llamada de función no se admite en la versión de Windows en la que se ejecutó. |
|
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
Referencia de la función auxiliar de IP