Función CreateIpForwardEntry (iphlpapi.h)
La función CreateIpForwardEntry crea una ruta en la tabla de enrutamiento IPv4 del equipo local.
Sintaxis
IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parámetros
[in] pRoute
Puntero a una estructura de MIB_IPFORWARDROW que especifica la información de la nueva ruta. El llamador debe especificar valores para todos los miembros de esta estructura. El autor de la llamada debe especificar MIB_IPPROTO_NETMGMT para el miembro dwForwardProto de MIB_IPFORWARDROW.
Valor devuelto
La función devuelve NO_ERROR (cero) si la función es correcta.
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 |
|---|---|
|
Se denegó el acceso. Este error se devuelve en Windows Vista y Windows Server 2008 en varias condiciones que incluyen lo siguiente: el usuario carece de los privilegios administrativos necesarios en el equipo local o la aplicación no se ejecuta en un shell mejorado como administrador integrado (administrador de RunAs). |
|
Un parámetro de entrada no es válido, no se realizó ninguna acción. Este error se devuelve si el parámetro pRoute es NULL, el miembro dwForwardProto de MIB_IPFORWARDROW no se estableció en MIB_IPPROTO_NETMGMT, el miembro dwForwardMask de la estructura PMIB_IPFORWARDROW no es una máscara de subred IPv4 válida o uno de los otros miembros de la estructura MIB_IPFORWARDROW no es válido. |
|
El transporte IPv4 no está configurado en el equipo local. |
|
Use FormatMessage para obtener la cadena de mensaje para el error devuelto. |
Comentarios
El miembro dwForwardProto de MIB_IPFORWARDROW estructura a la que apunta el parámetro de ruta debe establecerse en MIB_IPPROTO_NETMGMT de lo contrario, se producirá un error en CreateIpForwardEntry . Los identificadores de protocolo de enrutamiento se usan para identificar la información de ruta del protocolo de enrutamiento especificado. Por ejemplo, MIB_IPPROTO_NETMGMT se usa para identificar información de ruta para el enrutamiento IP establecido a través de la administración de red, como el Protocolo de configuración dinámica de host (DHCP), el Protocolo de administración de red simple (SNMP) o mediante llamadas a las funciones CreateIpForwardEntry, DeleteIpForwardEntry o SetIpForwardEntry .
En Windows Vista y Windows Server 2008, la métrica de ruta especificada en el miembro dwForwardMetric1 de la estructura de MIB_IPFORWARDROW a la que apunta el parámetro pRoute representa una combinación de la métrica de ruta agregada a la métrica de interfaz especificada en el miembro Metric de la estructura MIB_IPINTERFACE_ROW de la interfaz asociada. Por lo tanto, el miembro dwForwardMetric1 de la estructura MIB_IPFORWARDROW debe ser igual o mayor que el miembro Metric de la estructura de MIB_IPINTERFACE_ROW asociada. Si una aplicación desea establecer la métrica de ruta en 0, el miembro dwForwardMetric1 de la estructura de MIB_IPFORWARDROW debe establecerse igual al valor de la métrica de interfaz especificada en el miembro Metric de la estructura de MIB_IPINTERFACE_ROW asociada. Una aplicación puede recuperar la métrica de interfaz llamando a la función GetIpInterfaceEntry .
En Windows Vista y Windows Server 2008, CreateIpForwardEntry solo funciona en interfaces con una sola subfase (donde el LUID de interfaz y el LUID de subinterfacio son los mismos). El miembro dwForwardIfIndex de la estructura MIB_IPFORWARDROW especifica la interfaz.
CreateIpForwardEntry no usa actualmente varios miembros de la estructura MIB_IPFORWARDROW a la que apunta el parámetro route. Estos miembros incluyen dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 y dwForwardMetric5.
Una nueva ruta creada por CreateIpForwardEntry tendrá automáticamente un valor predeterminado para dwForwardAge de INFINITE.
Para modificar una ruta existente en la tabla de enrutamiento IPv4, use la función SetIpForwardEntry . Para recuperar la tabla de enrutamiento IPv4, llame a la función GetIpForwardTable .
En Windows Vista y versiones posteriores, un usuario que inició sesión como miembro del grupo Administradores solo puede llamar a la función CreateIpForwardEntry . Si un usuario llama a CreateIpForwardEntry que no es miembro del grupo Administradores, se producirá un error en la llamada de función y se devolverá ERROR_ACCESS_DENIED .
La función CreateIpForwardEntry también puede producir un error debido al control de cuentas de usuario (UAC) en Windows Vista y versiones posteriores. Si un usuario que ha iniciado sesión como miembro del grupo Administradores que no sea el administrador integrado ejecuta esta función, se producirá un error en esta llamada a menos que la aplicación se haya marcado en el archivo de manifiesto con un valor requestedExecutionLevel establecido en requireAdministrator. Si la aplicación carece de este archivo de manifiesto, un usuario que inició sesión como miembro del grupo Administradores distinto del administrador integrado debe ejecutar la aplicación en un shell mejorado como administrador integrado (administrador de runas) para que esta función se realice correctamente.
Ejemplos
En el ejemplo siguiente se muestra cómo cambiar la puerta de enlace predeterminada a NewGateway. Simplemente llamando a GetIpForwardTable, cambiando la puerta de enlace y, a continuación, llamando a SetIpForwardEntry no cambiará la ruta, sino que simplemente agregará una nueva. Si por algún motivo hay varias puertas de enlace predeterminadas presentes, este código los eliminará. Tenga en cuenta que la nueva puerta de enlace debe ser viable; de lo contrario, TCP/IP omitirá el cambio.
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
#pragma comment(lib, "iphlpapi.lib")
int main()
{
// Declare and initialize variables
PMIB_IPFORWARDTABLE pIpForwardTable = NULL;
PMIB_IPFORWARDROW pRow = NULL;
DWORD dwSize = 0;
BOOL bOrder = FALSE;
DWORD dwStatus = 0;
DWORD NewGateway = 0xDDCCBBAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int i;
// Find out how big our buffer needs to be.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
// Allocate the memory for the table
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Now get the table.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
}
if (dwStatus != ERROR_SUCCESS) {
printf("getIpForwardTable failed.\n");
if (pIpForwardTable)
free(pIpForwardTable);
exit(1);
}
// Search for the row in the table we want. The default gateway has a destination
// of 0.0.0.0. Notice that we continue looking through the table, but copy only
// one row. This is so that if there happen to be multiple default gateways, we can
// be sure to delete them all.
for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
if (pIpForwardTable->table[i].dwForwardDest == 0) {
// We have found the default gateway.
if (!pRow) {
// Allocate some memory to store the row in; this is easier than filling
// in the row structure ourselves, and we can be sure we change only the
// gateway address.
pRow = (PMIB_IPFORWARDROW) malloc(sizeof (MIB_IPFORWARDROW));
if (!pRow) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Copy the row
memcpy(pRow, &(pIpForwardTable->table[i]),
sizeof (MIB_IPFORWARDROW));
}
// Delete the old default gateway entry.
dwStatus = DeleteIpForwardEntry(&(pIpForwardTable->table[i]));
if (dwStatus != ERROR_SUCCESS) {
printf("Could not delete old gateway\n");
exit(1);
}
}
}
// Set the nexthop field to our new gateway - all the other properties of the route will
// be the same as they were previously.
pRow->dwForwardNextHop = NewGateway;
// Create a new route entry for the default gateway.
dwStatus = CreateIpForwardEntry(pRow);
if (dwStatus == NO_ERROR)
printf("Gateway changed successfully\n");
else if (dwStatus == ERROR_INVALID_PARAMETER)
printf("Invalid parameter.\n");
else
printf("Error: %d\n", dwStatus);
// Free resources
if (pIpForwardTable)
free(pIpForwardTable);
if (pRow)
free(pRow);
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