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
标头	rtmv2.h
Library	Rtm.lib
DLL	Rtm.dll