Функция RtmAddRouteToDest (rtmv2.h)

Статья
08/25/2023

Функция RtmAddRouteToDest добавляет новый маршрут в таблицу маршрутизации или обновляет существующий маршрут в таблице маршрутизации. При изменении наилучшего маршрута создается уведомление об изменении.

Синтаксис

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
);

Параметры

[in] RtmRegHandle

Дескриптор клиента, полученного при предыдущем вызове RtmRegisterEntity.

[in, out] RouteHandle

Если у клиента есть дескриптор (обновление маршрута): на входных данных RouteHandle является указателем на дескриптор маршрута. В выходных данных RouteHandle не изменяется.

Если у клиента нет дескриптора и должен быть возвращен дескриптор (клиент добавляет или обновляет маршрут): на входных данных RouteHandle является указателем на NULL. В выходных данных RouteHandle получает указатель на дескриптор маршрута. Значения в RouteInfo используются для определения маршрута для обновления.

Если дескриптор не требуется возвращать (клиент добавляет или обновляет маршрут): на входных данных RouteHandle имеет значение NULL. Значения в RouteInfo используются для определения маршрута для обновления.

[in] DestAddress

Указатель на сетевой адрес назначения, к которому добавляется или обновляется маршрут.

[in] RouteInfo

Указатель на сведения о маршруте для добавления или обновления.

[in] TimeToLive

Указывает время (в миллисекундах), по истечении которого истекает маршрут. Укажите INFINITE, чтобы предотвратить истечение срока действия маршрутов.

[in] RouteListHandle

Обработка списка маршрутов, в который нужно переместить маршрут. Этот параметр является необязательным и может иметь значение NULL.

[in] NotifyType

Задайте для этого параметра значение NULL. Этот параметр зарезервирован для использования в будущем.

[in] NotifyHandle

Задайте для этого параметра значение NULL. Этот параметр зарезервирован для использования в будущем.

[in, out] ChangeFlags

Во входных данных ChangeFlags является указателем на тип данных RTM_ROUTE_CHANGE_FLAGS , который указывает, должен ли диспетчер таблиц маршрутизации добавлять новый маршрут или обновлять существующий.

В выходных данных ChangeFlags является указателем на тип данных RTM_ROUTE_CHANGE_FLAGS , который получает флаг, указывающий тип фактически выполненного изменения, а также, был ли изменен лучший маршрут. Используются следующие флаги.

Константа	Значение
RTM_ROUTE_CHANGE_FIRST	Указывает, что диспетчер таблиц маршрутизации не должен проверка соседний член параметра RouteInfo при определении того, равны ли два маршрута.
RTM_ROUTE_CHANGE_NEW	Возвращается диспетчером таблиц маршрутизации, чтобы указать, что был создан новый маршрут.
RTM_ROUTE_CHANGE_BEST	Возвращается диспетчером таблиц маршрутизации, чтобы указать, что добавленный или обновленный маршрут является лучшим маршрутом или что из-за изменения новый маршрут стал лучшим маршрутом.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.

Если функция завершается сбоем, возвращается один из следующих кодов ошибок.

Значение	Значение
ERROR_ACCESS_DENIED	Вызывающий клиент не владеет этим маршрутом.
ERROR_INVALID_HANDLE	Дескриптор недействителен.
ERROR_INVALID_PARAMETER	Параметр содержит неверные сведения.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения этой операции.

Когда клиент обновляет маршрут, более эффективно передать дескриптор маршруту для обновления в параметре RouteHandle , так как диспетчер таблиц маршрутизации не должен выполнять поиск маршрута в таблице маршрутизации.

Если дескриптор был возвращен, отпустите дескриптор, когда он больше не требуется, вызвав RtmReleaseRoutes.

Пример кода, использующий эту функцию, см. в разделе Добавление и обновление маршрутов с помощью RtmAddRouteToDest.

Требования

Требование	Значение
Минимальная версия клиента	Ни одна версия не поддерживается
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	rtmv2.h
Библиотека	Rtm.lib
DLL	Rtm.dll