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