Función SetIpForwardEntry2 (netioapi.h)

Artículo
03/15/2023

La función SetIpForwardEntry2 establece las propiedades de una entrada de ruta IP en el equipo local.

Sintaxis

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Route
);

Parámetros

[in] Route

Puntero a una entrada de estructura de MIB_IPFORWARD_ROW2 para una entrada de ruta IP. El miembro DestinationPrefix del MIB_IPFORWARD_ROW2 debe establecerse en un prefijo de destino IP válido, el miembro NextHop del MIB_IPFORWARD_ROW2 debe establecerse en una familia de direcciones IP válidas y una dirección IP, y se debe especificar el miembro InterfaceLuid o InterfaceIndex del MIB_IPFORWARD_ROW2 .

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_ACCESS_DENIED	Acceso denegado. Este error se devuelve 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).
ERROR_INVALID_PARAMETER	Se pasó un parámetro no válido a la función. Este error se devuelve si no se especificó un puntero NULL en el parámetro Route, no se especificó el miembro DestinationPrefix del MIB_IPFORWARD_ROW2 al que apunta el parámetro Route, no se especificó el miembro NextHop del MIB_IPFORWARD_ROW2 señalado por el parámetro Route, o los miembros InterfaceLuid o InterfaceIndex del MIB_IPFORWARD_ROW2 señalados por route el parámetro no se especificó.
ERROR_NOT_FOUND	No se encontró la interfaz especificada. Este error se devuelve si no se encontró la interfaz de red especificada por el miembro InterfaceLuid o InterfaceIndex del MIB_IPFORWARD_ROW2 señalado por el parámetro Route .
Otros	Use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Comentarios

La función SetIpForwardEntry2 se define en Windows Vista y versiones posteriores.

La función SetIpForwardEntry2 se usa para establecer las propiedades de una entrada de ruta IP existente en un equipo local.

El miembro DestinationPrefix de la estructura MIB_IPFORWARD_ROW2 a la que apunta el parámetro Route debe inicializarse en un prefijo de dirección IP y una familia válidos. El miembro NextHop de la estructura MIB_IPFORWARD_ROW2 a la que apunta el parámetro Route debe inicializarse en una dirección IP y una familia válidas. Además, al menos uno de los miembros siguientes de la estructura MIB_IPFORWARD_ROW2 apunta al parámetro Route debe inicializarse en la interfaz: InterfaceLuid o InterfaceIndex.

Los campos se usan en el orden indicado anteriormente. Por lo tanto, si se especifica InterfaceLuid , este miembro se usa para determinar la interfaz en la que se va a agregar la dirección IP de unidifusión. Si no se estableció ningún valor para el miembro InterfaceLuid (los valores de este miembro se establecieron en cero), el miembro InterfaceIndex se usará a continuación para determinar la interfaz.

El desplazamiento de la métrica de ruta especificado en el miembro Métrica de la estructura MIB_IPFORWARD_ROW2 a la que apunta el parámetro Route representa solo parte de la métrica de ruta completa. La métrica completa es una combinación de este desplazamiento de métrica de ruta agregado a la métrica de interfaz especificada en el miembro Métrica de la estructura MIB_IPINTERFACE_ROW de la interfaz asociada. Una aplicación puede recuperar la métrica de interfaz llamando a la función GetIpInterfaceEntry .

Los miembros Age y Origin de la estructura MIB_IPFORWARD_ROW2 a la que apunta la fila se omiten cuando se llama a la función SetIpForwardEntry2 . La pila de red establece estos miembros y no se puede cambiar mediante la función SetIpForwardEntry2 .

Se producirá un error en la función SetIpForwardEntry2 si los miembros DestinationPrefix y NextHop del MIB_IPFORWARD_ROW2 señalados por el parámetro Route no coinciden con una entrada de ruta IP en la interfaz especificada.

Un usuario que inició sesión como miembro del grupo Administradores solo puede llamar a la función SetIpForwardEntry2 . Si un usuario llama a SetIpForwardEntry2 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 SetIpForwardEntry2 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.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	netioapi.h (include Iphlpapi.h)
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll