RtmGetLessSpecificDestination function (rtmv2.h)
The RtmGetLessSpecificDestination function searches the routing table for a destination with the next-best-match (longest) prefix, given a destination prefix. The requested destination information is returned.
Syntax
DWORD RtmGetLessSpecificDestination(
[in] RTM_ENTITY_HANDLE RtmRegHandle,
[in] RTM_DEST_HANDLE DestHandle,
[in] ULONG ProtocolId,
[in] RTM_VIEW_SET TargetViews,
[out] PRTM_DEST_INFO DestInfo
);
Parameters
[in] RtmRegHandle
Handle to the client obtained from a previous call to RtmRegisterEntity.
[in] DestHandle
Handle to the destination.
[in] ProtocolId
Specifies the protocol identifier. The ProtocolID is not part of the search criteria. The routing table manager uses this identifier to determine which route information to return. For example, if a client specifies the RIP protocol identifier, the best RIP route is returned, even if a non-RIP route is the best route to the destination.
Specify RTM_BEST_PROTOCOL to return a route regardless of which protocol owns it. Specify RTM_THIS_PROTOCOL to return the best route for the calling protocol.
[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] DestInfo
On input, DestInfo is a pointer to an RTM_DEST_INFO structure.
On output, DestInfo is filled with the requested destination information.
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 |
|---|---|
|
A parameter contains incorrect information. |
|
The next best destination cannot be found. |
Remarks
The DestInfo parameter is a variable-sized RTM_DEST_INFO structure. If the client specifies more than one view using TargetViews, the size of DestInfo increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how much memory to allocate for the DestInfo structure before calling this function. Use the value specified for TargetViews as a parameter to RTM_SIZE_OF_DEST_INFO.
The RtmGetLessSpecificDestination function is used after a call to RtmGetMostSpecificDestination to return the next-best match for a destination. This call is also used after a prior call to RtmGetLessSpecificDestination to return the next successive less-specific match. Clients can use this function to "walk up" the prefix tree for a destination.
This call is also used after calls to functions that return an RTM_DEST_INFO structure, such as RtmGetDestInfo and RtmGetChangedDests.
The RtmGetLessSpecificDestination function returns matches until it reaches the default route, if it exists. Once the default route is found, RtmGetLessSpecificDestination returns ERROR_NOT_FOUND.
One common use for the RtmGetLessSpecificDestination and RtmGetMostSpecificDestination functions, is to retrieve each of the matching destinations.
For sample code using this function, see Search for Routes Using a Prefix Tree.
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 |