RtmCreateEnumerationHandle

[This is preliminary documentation and subject to change.]

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 (RTM).

HANDLE RtmCreateEnumerationHandle(
  DWORD  ProtocolFamily,     // type of network (IP or IPX)
  DWORD  EnumerationFlags,   // flags that specify type of criteria
  PVOID  CriteriaRoute       // structure that holds criteria values
);
 

Parameters

ProtocolFamily

Specifies the protocol family of the routes to enumerate.

EnumerationFlags

Limits the set of routes returned by the enumeration API to a subset defined by these 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	Values
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 member of the structure pointed to by CriteriaRoute.
RTM_ONLY_THIS_PROTOCOL	Enumerate only those routes that were added by the protocol handler 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

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 Values

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:

ERROR_NO_ROUTES

No routes exist with 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

Insufficient resources to carry out the operation.

ERROR_NOT_ENOUGH_MEMORY

Insufficient memory to allocate the handle.

QuickInfo

  Windows NT: Use version 5.0 and later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in rtm.h.
  Import Library: Link with rtm.lib.

See Also

GetLastError, RTM_IP_ROUTE, RTM_IPX_ROUTE, RtmCloseEnumerationHandle, RtmEnumerateGetNextRoute