Función DeleteIpForwardEntry (iphlpapi.h)
La función DeleteIpForwardEntry elimina una ruta existente en la tabla de enrutamiento IPv4 del equipo local.
Sintaxis
IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parámetros
[in] pRoute
Puntero a una estructura de MIB_IPFORWARDROW . Esta estructura especifica información que identifica la ruta que se va a eliminar. El llamador debe especificar valores para los miembros dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop y dwForwardProto de la estructura.
Valor devuelto
La función devuelve NO_ERROR (cero) si la rutina 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 de error | Significado |
|---|---|
|
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 dwForwardMask de la estructura PMIB_IPFORWARDROW no es una máscara de subred IPv4 válida, el miembro dwForwardIfIndex es NULL o uno de los demás miembros de la estructura MIB_IPFORWARDROW no es válido. |
|
El parámetro pRoute apunta a una entrada de ruta que no existe. |
|
El transporte IPv4 no está configurado en el equipo local. |
|
La función puede devolver otros códigos de error. |
Si se produce un error en la función, use FormatMessage para obtener la cadena de mensaje para el error devuelto.
Comentarios
El miembro dwForwardProto de MIB_IPFORWARDROW puntero de estructura a por el parámetro de ruta debe establecerse en MIB_IPPROTO_NETMGMT de lo contrario, se producirá un error en DeleteIpForwardEntry . 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, DeleteIpForwardEntry 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, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 y dwForwardMetric5.
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 DeleteIpForwardEntry . Si un usuario llama a DeleteIpForwardEntry 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 DeleteIpForwardEntry 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 de código siguiente se muestra cómo cambiar la puerta de enlace predeterminada a NewGateway. Al llamar a GetIpForwardTable, cambiar la puerta de enlace y, a continuación, llamar a SetIpForwardEntry no cambiará la ruta, sino que agregará una nueva. Si existen varias puertas de enlace predeterminadas, 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 = 0xDDBBCCAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int i;
// Identify the required size of the buffer.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
// Allocate memory for the table.
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Retrieve the table.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
}
if (dwStatus != ERROR_SUCCESS) {
printf("getIpForwardTable failed.\n");
if (pIpForwardTable)
free(pIpForwardTable);
exit(1);
}
// Search for the required row in the table. The default gateway has a destination
// of 0.0.0.0. Be aware the table continues to be searched, but only
// one row is copied. This is to ensure that, if multiple gateways exist, all of them are deleted.
//
for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
if (pIpForwardTable->table[i].dwForwardDest == 0) {
// The default gateway was found.
if (!pRow) {
// Allocate memory to store the row. This is easier than manually filling
// the row structure; only the gateway address is changed.
//
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 other properties of the route will
// remain the same.
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 the memory.
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