Función RtmAddRouteToDest (rtmv2.h)

Artículo
08/25/2023

La función RtmAddRouteToDest agrega una nueva ruta a la tabla de enrutamiento o actualiza una ruta existente en la tabla de enrutamiento. Si cambia la mejor ruta, se genera una notificación de cambio.

Sintaxis

DWORD RtmAddRouteToDest(
  [in]      RTM_ENTITY_HANDLE       RtmRegHandle,
  [in, out] PRTM_ROUTE_HANDLE       RouteHandle,
  [in]      PRTM_NET_ADDRESS        DestAddress,
  [in]      PRTM_ROUTE_INFO         RouteInfo,
  [in]      ULONG                   TimeToLive,
  [in]      RTM_ROUTE_LIST_HANDLE   RouteListHandle,
  [in]      RTM_NOTIFY_FLAGS        NotifyType,
  [in]      RTM_NOTIFY_HANDLE       NotifyHandle,
  [in, out] PRTM_ROUTE_CHANGE_FLAGS ChangeFlags
);

Parámetros

[in] RtmRegHandle

Identificador para el cliente obtenido de una llamada anterior a RtmRegisterEntity.

[in, out] RouteHandle

Si el cliente tiene un identificador (actualizando una ruta): en la entrada, RouteHandle es un puntero al identificador de ruta. En la salida, RouteHandle no cambia.

Si el cliente no tiene un identificador y se debe devolver un identificador (el cliente agrega o actualiza una ruta): En la entrada, RouteHandle es un puntero a NULL. En la salida, RouteHandle recibe un puntero al identificador de ruta. Los valores de RouteInfo se usan para identificar la ruta que se va a actualizar.

Si no es necesario devolver un identificador (el cliente está agregando o actualizando una ruta): en la entrada, RouteHandle es NULL. Los valores de RouteInfo se usan para identificar la ruta que se va a actualizar.

[in] DestAddress

Puntero a la dirección de red de destino a la que se va a agregar o actualizar la ruta.

[in] RouteInfo

Puntero a la información de ruta que se va a agregar o actualizar.

[in] TimeToLive

Especifica la hora, en milisegundos, después de la cual la ruta ha expirado. Especifique INFINITE para evitar que expiren las rutas.

[in] RouteListHandle

Controle a una lista de rutas a la que se va a mover la ruta. Este parámetro es opcional y se puede establecer en NULL.

[in] NotifyType

Establezca este parámetro en NULL. Este parámetro se reserva para uso futuro.

[in] NotifyHandle

Establezca este parámetro en NULL. Este parámetro se reserva para uso futuro.

[in, out] ChangeFlags

En la entrada, ChangeFlags es un puntero a un tipo de datos RTM_ROUTE_CHANGE_FLAGS que indica si el administrador de tablas de enrutamiento debe agregar una nueva ruta o actualizar una existente.

En la salida, ChangeFlags es un puntero a un tipo de datos RTM_ROUTE_CHANGE_FLAGS que recibe la marca que indica el tipo de cambio que se realizó realmente y si se cambió la mejor ruta. Se usan las marcas siguientes.

Constante	Significado
RTM_ROUTE_CHANGE_FIRST	Indica que el administrador de tablas de enrutamiento no debe comprobar el miembro Vecino del parámetro RouteInfo al determinar si dos rutas son iguales.
RTM_ROUTE_CHANGE_NEW	Devuelto por el administrador de tablas de enrutamiento para indicar que se creó una nueva ruta.
RTM_ROUTE_CHANGE_BEST	Devuelto por el administrador de tablas de enrutamiento para indicar que la ruta que se agregó o actualizó era la mejor ruta, o que debido al cambio, una nueva ruta se convirtió en la mejor ruta.

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.

Valor	Significado
ERROR_ACCESS_DENIED	El cliente que realiza la llamada no posee esta ruta.
ERROR_INVALID_HANDLE	El identificador no es válido.
ERROR_INVALID_PARAMETER	Un parámetro contiene información incorrecta.
ERROR_NOT_ENOUGH_MEMORY	No hay suficiente memoria para completar esta operación.

Comentarios

Dos rutas se consideran iguales si los valores siguientes son iguales:

Red de destino
Propietario de la ruta
Vecino que proporcionó la ruta

Cuando un cliente actualiza una ruta, es más eficaz pasar un identificador a la ruta para actualizar en el parámetro RouteHandle , ya que el administrador de tablas de enrutamiento no tiene que realizar una búsqueda de la ruta en la tabla de enrutamiento.

Si se devolvió un identificador, libere el identificador cuando ya no sea necesario mediante una llamada a RtmReleaseRoutes.

Para obtener código de ejemplo con esta función, consulte Agregar y actualizar rutas mediante RtmAddRouteToDest.

Requisitos

Requisito	Value
Cliente mínimo compatible	No se admite ninguno
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	rtmv2.h
Library	Rtm.lib
Archivo DLL	Rtm.dll