RtmCreateRouteEnum 函式 (rtmv2.h)

發行項
03/01/2024

RtmCreateRouteEnum 函式會針對路由表中的特定目的地或目的地範圍建立路由的列舉。用戶端可以列舉一或多個檢視的路由，或針對所有檢視列舉路由。

語法

DWORD RtmCreateRouteEnum(
  [in]  RTM_ENTITY_HANDLE RtmRegHandle,
  [in]  RTM_DEST_HANDLE   DestHandle,
  [in]  RTM_VIEW_SET      TargetViews,
  [in]  RTM_ENUM_FLAGS    EnumFlags,
  [in]  PRTM_NET_ADDRESS  StartDest,
  [in]  RTM_MATCH_FLAGS   MatchingFlags,
  [in]  PRTM_ROUTE_INFO   CriteriaRoute,
  [in]  ULONG             CriteriaInterface,
  [out] PRTM_ENUM_HANDLE  RtmEnumHandle
);

參數

[in] RtmRegHandle

從先前呼叫 RtmRegisterEntity 取得的用戶端句柄。

[in] DestHandle

處理要列舉路由的目的地。此參數是選擇性的，而且可以設定為 NULL;指定 NULL 會列舉所有目的地的所有路由。如果 EnumFlags 包含RTM_ENUM_START，請指定 NULL。

[in] TargetViews

指定建立列舉時要使用的檢視集。使用下列旗標。

常數	意義
RTM_VIEW_MASK_ANY	從所有檢視傳回目的地。這是預設值。
RTM_VIEW_MASK_UCAST	從單播檢視傳回目的地。
RTM_VIEW_MASK_MCAST	從多播檢視傳回目的地。

[in] EnumFlags

指定要包含在列舉中的路由。使用兩組旗標;使用每個集合 (的一個旗標，例如RTM_ENUM_ALL_ROUTES和RTM_ENUM_START) 。

常數	意義
RTM_ENUM_ALL_ROUTES	傳回所有路由。
RTM_ENUM_OWN_ROUTES	只傳回客戶端擁有的路由。

常數	意義
RTM_ENUM_NEXT	列舉從指定位址/遮罩長度開始的路由， (例如 10/8) 。列舉會繼續到路由表的結尾。
RTM_ENUM_RANGE	列舉位址/遮罩長度所指定範圍中的路由， (例如 10/8) 。
RTM_ENUM_START	列舉從 0/0 開始的路由。針對 NetAddress 指定 NULL。

[in] StartDest

包含列舉起始位址之RTM_NET_ADDRESS 結構的指標。如果 EnumFlags 包含RTM_ENUM_START，則會忽略此參數。

[in] MatchingFlags

指定要比對之路由的元素。除非另有說明，否則只會傳回符合 CriteriaRoute 和 CriteriaInterface 中所指定準則的路由。使用下列旗標。

常數	意義
RTM_MATCH_FULL	比對路由與所有準則。
RTM_MATCH_INTERFACE	比對位於相同介面上的路由。用戶端可以指定 CriteriaRoute 的 NULL。
RTM_MATCH_NEIGHBOUR	比對路由與相同的芳鄰。
RTM_MATCH_NEXTHOP	比對具有相同下一個躍點的路由。
RTM_MATCH_NONE	比對任何準則;會傳回目的地的所有路由。如果設定此旗標，則會忽略 CriteriaRoute 參數。
RTM_MATCH_OWNER	比對具有相同擁有者的路由。
RTM_MATCH_PREF	比對具有相同喜好設定的路由。

[in] CriteriaRoute

指定要列舉的路由。此參數是選擇性的，如果 MatchingFlags 包含RTM_MATCH_INTERFACE或RTM_MATCH_NONE，則可以設定為 NULL。

[in] CriteriaInterface

ULONG 的指標，指定應該位於哪些介面路由上。除非 MatchingFlags 包含 RTM_MATCH_INTERFACE，否則會忽略此參數。

[out] RtmEnumHandle

在輸入時， RtmEnumHandle 是 NULL 的指標。

在輸出上， RtmEnumHandle 會接收列舉句柄的指標。在所有後續對 RtmGetEnumRoutes、 RtmReleaseRoutes 和 RtmDeleteEnumHandle 的後續呼叫中使用此句柄。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，傳回值就是下列其中一個錯誤碼。

值	意義
ERROR_INVALID_PARAMETER	參數包含不正確的資訊。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成這項作業。
ERROR_NOT_SUPPORTED	不支援一或多個指定的檢視。

備註

如果 EnumFlags 包含RTM_ENUM_RANGE，請使用 NetAddress 指定要列舉的路由表範圍。例如，如果用戶端將 NetAddress 設定為 10/8，則會傳回範圍 10.0.0.0/8 到 10.255.255.255/32 的目的地。

不再需要列舉句柄時，請呼叫 RtmDeleteEnumHandle 加以釋放。

如需使用此函式的範例程式代碼，請參閱列舉所有路由。

規格需求

需求	值
最低支援的用戶端	都不支援
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	rtmv2.h
程式庫	Rtm.lib
Dll	Rtm.dll