RtmCreateDestEnum function (rtmv2.h)

Article
10/13/2021

The RtmCreateDestEnum function starts an enumeration of the destinations in the routing table. A client can enumerate destinations for one or more views, or for all views.

Syntax

DWORD RtmCreateDestEnum(
  [in]  RTM_ENTITY_HANDLE RtmRegHandle,
  [in]  RTM_VIEW_SET      TargetViews,
  [in]  RTM_ENUM_FLAGS    EnumFlags,
  [in]  PRTM_NET_ADDRESS  NetAddress,
  [in]  ULONG             ProtocolId,
  [out] PRTM_ENUM_HANDLE  RtmEnumHandle
);

Parameters

[in] RtmRegHandle

Handle to the client obtained from a previous call to RtmRegisterEntity.

[in] TargetViews

Specifies the set of views to use when creating the enumeration. The following flags are used.

Constant	Meaning
RTM_VIEW_MASK_ANY	Return destinations from all views. This is the default value.
RTM_VIEW_MASK_UCAST	Return destinations from the unicast view.
RTM_VIEW_MASK_MCAST	Return destinations from the multicast view.

[in] EnumFlags

Specifies which destinations to include in the enumeration. Two sets of flags are used; use one flag from each set (for example, use RTM_ENUM_ALL_DESTS and RTM_ENUM_START).

Constant	Meaning
RTM_ENUM_ALL_DESTS	Return all destinations.
RTM_ENUM_OWN_DESTS	Return destinations for which the client owns the best route to a destination in any of the specified views.

Constant	Meaning
RTM_ENUM_NEXT	Enumerate destinations starting at the specified address/mask length (such as 10/8). The enumeration continues to the end of the routing table.
RTM_ENUM_RANGE	Enumerate destinations in the range specified by the address/mask length (such as 10/8).
RTM_ENUM_START	Enumerate destinations starting at 0/0. Specify NULL for NetAddress.

[in] NetAddress

Pointer to an RTM_NET_ADDRESS structure that contains the starting address of the enumeration. Specify NULL if EnumFlags contains RTM_ENUM_START.

[in] ProtocolId

Specifies the protocol identifier used to determine the best route information returned by the RtmGetEnumDests function. The ProtocolID is not part of the search criteria. The routing table manager uses this identifier to determine which route information to return (for example, if a client specifies the RIP protocol identifier, the best RIP route is returned, even if a non-RIP route is the best route to the destination).

Specify RTM_BEST_PROTOCOL to return a route regardless of which protocol owns it. Specify RTM_THIS_PROTOCOL to return the best route for the calling protocol.

[out] RtmEnumHandle

On input, RtmEnumHandle is a pointer to NULL.

On output, RtmEnumHandle receives a pointer to a handle to the enumeration. Use this handle in all subsequent calls to RtmGetEnumDests, RtmReleaseDests, and RtmDeleteEnumHandle.

Return value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value	Meaning
ERROR_INVALID_PARAMETER	A parameter contains incorrect information.
ERROR_NOT_ENOUGH_MEMORY	There is not enough memory to complete this operation.
ERROR_NOT_SUPPORTED	One or more of the specified views is not supported.

Remarks

If EnumFlags contains RTM_ENUM_RANGE, use NetAddress to specify the range of the routing table to enumerate. For example, if a client sets NetAddress to 10/8, destinations in the range 10.0.0.0/8 to 10.255.255.255/32 are returned.

When the enumeration handle is no longer required, release it by calling RtmDeleteEnumHandle.

For sample code using this function, see Enumerate All Destinations.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	rtmv2.h
Library	Rtm.lib
DLL	Rtm.dll