RtmAddRoute 函式

[路由 表管理員第 2 版 API 已取代此 API,且無法超過 Windows Server 2003。 應用程式應該使用路由表管理員第 2 版 API。]

RtmAddRoute函式會新增路由專案或更新現有的路由專案。

語法

DWORD RtmAddRoute(
  _In_  HANDLE ClientHandle,
  _In_  PVOID  Route,
  _In_  DWORD  TimeToLive,
  _Out_ DWORD  Flags,
  _Out_ PVOID  CurBestRoute,
  _Out_ PVOID  PrevBestRoute
);

參數

ClientHandle [in]

可識別用戶端的控制碼,因此會新增或更新路由的路由通訊協定。 藉由呼叫 RtmRegisterClient來取得此控制碼。

路由 [in]

指定新路由或更新路由之通訊協定系列特定結構的指標。 路由表管理員會使用下欄欄位來更新路由表:

意義
RR_Network
指定目的地網路編號。
RR_InterfaceID
指定接收路由的介面索引。
RR_NextHopAddress
指定下一個躍點路由器的位址。
RR_FamilySpecificData
指定通訊協定系列特有的資料。 雖然資料對路由表管理員而言是透明的,但在比較路由以判斷路由資訊是否已變更時,會考慮資料。 資料也可用來設定與路由通訊協定無關的計量值。 因此,此資料是用來判斷目的地網路的最佳路由。
RR_ProtocolSpecificData
指定提供路由的路由通訊協定特定的資料。
RR_TimeStamp
指定目前的系統時間。 此欄位是由路由表管理員所設定。

TimeToLive [in]

指定指定路由應該保留在路由表中的秒數。 如果此參數設定為 INFINITE,路由會保留到明確刪除為止。 TimeToLive的目前限制2147483秒 (24 天以上) 。

旗標 [out]

DWORD變數的指標。 此變數的值是由路由表管理員設定。 值表示變更的類型,以及所提供緩衝區中傳回的資訊。 此參數是下列其中一項。

Flags 意義
RTM_NO_CHANGE
新增或更新未變更任何重要的路由參數,或受影響的路由專案不是目的地網路專案之間的最佳路由。
RTM_ROUTE_ADDED
目的地網路已新增路由。 CurBestRoute參數會指向新增路由的資訊。
RTM_ROUTE_CHANGED
針對目的地網路的最佳路由,至少有一個重大參數已變更。 重要參數包括:
通訊協定識別碼
介面索引
下一個躍點位址
通訊協定系列特定的資料 (包括路由計量)

PrevBestRoute參數會指向變更前的路由資訊。 CurBestRoute參數指向目前 (,也就是變更後) 路由資訊。

CurBestRoute [out]

如果有的話,接收目前最佳路由資訊之結構的指標。 結構的類型專屬於通訊協定系列,例如 IP 或 IPX。

這是選擇性參數。 如果呼叫端指定此參數的 Null ,則不會傳回目前的最佳路由資訊。

PrevBestRoute [out]

如果有的話,接收先前最佳路由資訊之結構的指標。 結構的類型專屬於通訊協定系列,例如 IP 或 IPX。

這是選擇性參數。 如果呼叫端指定此參數的 Null ,則不會傳回先前的最佳路由資訊。

傳回值

傳回值是下列其中一個程式碼。

Description
NO_ERROR
已成功新增或更新路由。
ERROR_INVALID_HANDLE
用戶端控制碼參數不是有效的控制碼。
ERROR_INVALID_PARAMETER
路由結構包含不正確參數。
ERROR_NO_SYSTEM_RESOURCES
資源不足,無法執行作業。
ERROR_NOT_ENOUGH_MEMORY
記憶體不足,無法配置路由專案。

備註

如果目的地網路的最佳路由因此作業而變更,此函式會產生路由變更訊息。 不過,路由變更訊息不會傳送至發出此呼叫的用戶端。 相反地,此函式會透過 FlagsCurBestRoutePrevBestRoute 參數,直接將該用戶端傳回相關資訊。

規格需求

需求
最低支援的用戶端
都不支援
最低支援的伺服器
Windows 2000 Server [僅限傳統型應用程式]
伺服器終止支援
Windows Server 2003
標頭
Rtm.h
程式庫
Rtm.lib
DLL
Rtm.dll

另請參閱

路由表管理員第 1 版參考

路由表管理員第 1 版函式

RtmDeleteRoute

RtmDequeueRouteChangeMessage