RtmCreateEnumerationHandle function

[This API has been superseded by the Routing Table Manager Version 2 API and will not be available beyond Windows Server 2003. Applications should use the Routing Table Manager Version 2 API.]

The RtmCreateEnumerationHandle function returns a handle to use with RtmEnumerateGetNextRoute to scan through all routes, or a subset of routes, known to the routing table manager.

Syntax

HANDLE RtmCreateEnumerationHandle(
  _In_ DWORD ProtocolFamily,
  _In_ DWORD EnumerationFlags,
  _In_ PVOID CriteriaRoute
);

Parameters

ProtocolFamily [in]

Specifies the protocol family of the routes to enumerate.

EnumerationFlags [in]

Specifies which routes should be enumerated. This parameter limits the set of routes returned by the enumeration API to a subset defined by the following flags and the values in the corresponding members of the structure pointed to by the CriteriaRoute parameter. This parameter can be one of the following values.

EnumerationFlags	Meaning
RTM_ONLY_THIS_NETWORK	Enumerate only those routes that have the same network number as the RR_Network member of the structure pointed to by CriteriaRoute.
RTM_ONLY_THIS_INTERFACE	Enumerate only those routes that were obtained through the interface specified by the RR_InterfaceID field of the structure pointed to by CriteriaRoute.
RTM_ONLY_THIS_PROTOCOL	Enumerate only those routes that were added by the routing protocol specified by the RR_RoutingProtocol field of the structure pointed to by CriteriaRoute.
RTM_ONLY_BEST_ROUTES	Enumerate only the best routes to each of the networks in the set.

CriteriaRoute [in]

Pointer to a protocol-family-specific route structure (RTM_IP_ROUTE or RTM_IPX_ROUTE). The member values in this structure correspond to the flags specified by the EnumerationFlags parameter.

Return value

If the function succeeds, the return value is a HANDLE to use with subsequent enumeration calls.

If the function fails, or no routes exist with the specified criteria, the return value is NULL. Call GetLastError to obtain more information.

Value	Description
ERROR_NO_ROUTES	There are no routes that have the specified criteria.
ERROR_INVALID_PARAMETER	One or more of the input parameters is invalid (for example, unknown protocol family, invalid enumeration flags).
ERROR_NO_SYSTEM_RESOURCES	There are insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY	There is insufficient memory to allocate the handle.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows 2000 Server [desktop apps only]
End of server support	Windows Server 2003
Header	Rtm.h
Library	Rtm.lib
DLL	Rtm.dll

See also

Routing Table Manager Version 1 Reference

Routing Table Manager Version 1 Functions

GetLastError

RTM_IP_ROUTE

RTM_IPX_ROUTE

RtmCloseEnumerationHandle

RtmEnumerateGetNextRoute