RtmAddRouteToDest 函式 (rtmv2.h)

發行項
03/01/2024

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
程式庫	Rtm.lib
Dll	Rtm.dll