RtmGetExactMatchRoute function (rtmv2.h)

Article
10/13/2021

The RtmGetExactMatchRoute function searches the routing table for a route that exactly matches the specified route. The route to search for is indicated by a network address, subnet mask, and other route-matching criteria. If an exact match is found, the route information is returned.

Syntax

DWORD RtmGetExactMatchRoute(
  [in]      RTM_ENTITY_HANDLE RtmRegHandle,
  [in]      PRTM_NET_ADDRESS  DestAddress,
  [in]      RTM_MATCH_FLAGS   MatchingFlags,
  [in, out] PRTM_ROUTE_INFO   RouteInfo,
  [in]      ULONG             InterfaceIndex,
  [in]      RTM_VIEW_SET      TargetViews,
  [out]     PRTM_ROUTE_HANDLE RouteHandle
);

Parameters

[in] RtmRegHandle

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

[in] DestAddress

Pointer to the destination network address.

[in] MatchingFlags

Specifies the criteria to use when searching for the route. The following flags are used.

Constant	Meaning
RTM_MATCH_FULL	Match routes with all criteria.
RTM_MATCH_INTERFACE	Match routes that are on the same interface.
RTM_MATCH_NEIGHBOUR	Match routes with the same neighbor.
RTM_MATCH_NEXTHOP	Match routes that have the same next hop.
RTM_MATCH_NONE	Match none of the criteria; all routes for the destination are returned.
RTM_MATCH_OWNER	Match routes with the same owner.
RTM_MATCH_PREF	Match routes that have the same preference.

[in, out] RouteInfo

On input, RouteInfo is a pointer an RTM_ROUTE_INFO structure that contains the criteria that specifies the route to find.

On output, RouteInfo receives the route information for the route that matched the criteria.

[in] InterfaceIndex

If RTM_MATCH_INTERFACE is specified in MatchingFlags, InterfaceIndex specifies the interface on which the route must be present (that is, the route has a next hop on that interface).

[in] TargetViews

Specifies the views from which to return information. If the client specifies RTM_VIEW_MASK_ANY, destination information is returned from all views; however, no view-specific information is returned.

[out] RouteHandle

If a handle must be returned: On input, RouteHandle is a pointer to NULL.

On output, RouteHandle receives a pointer to the route handle; otherwise, RouteHandle remains unchanged.

If a handle does not need to be returned: On input, RouteHandle is NULL.

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_NOT_FOUND	The specified route was not found.

Remarks

Consider using RtmGetExactMatchDestination if you have no route-matching criteria specified in the MatchingFlags parameter.

The following members of the RTM_ROUTE_INFO structure that is passed in the RouteInfo parameter are used to match a route:

Neighbour
NextHopsList
PrefInfo
RouteOwner

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