RtmUpdateAndUnlockRoute function (rtmv2.h)

Article
10/13/2021

The RtmUpdateAndUnlockRoute function updates the position of the route in the set of routes for a destination, and adjusts the best route information for the destination.

This function is used after a client has locked a route and updated it directly (also known as in-place updating).

Syntax

DWORD RtmUpdateAndUnlockRoute(
  [in]  RTM_ENTITY_HANDLE       RtmRegHandle,
  [in]  RTM_ROUTE_HANDLE        RouteHandle,
  [in]  ULONG                   TimeToLive,
  [in]  RTM_ROUTE_LIST_HANDLE   RouteListHandle,
  [in]  RTM_NOTIFY_FLAGS        NotifyType,
  [in]  RTM_NOTIFY_HANDLE       NotifyHandle,
  [out] PRTM_ROUTE_CHANGE_FLAGS ChangeFlags
);

Parameters

[in] RtmRegHandle

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

[in] RouteHandle

Handle to the route to change.

[in] TimeToLive

Specifies the time, in milliseconds, after which the route is expired. Specify INFINITE to prevent routes from expiring.

[in] RouteListHandle

Handle to an optional route list to which to move the route. This parameter is optional and can be set to NULL.

[in] NotifyType

Set this parameter to NULL. NotifyType is reserved for future use.

[in] NotifyHandle

Set this parameter to NULL. NotifyHandle is reserved for future use.

[out] ChangeFlags

Receives RTM_ROUTE_CHANGE_BEST if the best route was changed.

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_ACCESS_DENIED	The calling client does not own this route.

Remarks

Before calling this function, the client should lock the route using RtmLockRoute, which returns a pointer to the route. Then, the client can update the route information using the pointer. Finally, the client should call RtmUpdateAndUnlockRoute. If the function executes successfully, the route is unlocked. If the call failed, the client must unlock the route by calling RtmLockRoute with the LockRoute parameter set to FALSE.

For sample code using this function, see Update a Route In Place Using RtmUpdateAndUnlockRoute.

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