Edit

Share via

RtmGetExactMatchRoute function (rtmv2.h)

  • Article

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

See also

RTM_NET_ADDRESS

RTM_ROUTE_INFO

RtmGetExactMatchDestination

RtmGetLessSpecificDestination

RtmGetMostSpecificDestination

RtmIsBestRoute