RtmLockRoute function (rtmv2.h)

Article
10/13/2021

The RtmLockRoute function locks or unlocks a route in the routing table. This protects the route while a client makes the necessary changes to the opaque route pointers owned by the client.

Syntax

DWORD RtmLockRoute(
  [in]  RTM_ENTITY_HANDLE RtmRegHandle,
  [in]  RTM_ROUTE_HANDLE  RouteHandle,
  [in]  BOOL              Exclusive,
  [in]  BOOL              LockRoute,
  [out] PRTM_ROUTE_INFO   *RoutePointer
);

Parameters

[in] RtmRegHandle

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

[in] RouteHandle

Handle to the route to lock.

[in] Exclusive

Specifies whether to lock or unlock the route in an exclusive (TRUE) or shared (FALSE) mode.

[in] LockRoute

Specifies whether to lock or unlock the route. Specify TRUE to lock the route; specify FALSE to unlock it.

[out] RoutePointer

If a pointer must be returned: On input, RoutePointer is a pointer to NULL. On output, if the client owns the route, RoutePointer receives a pointer to the next-hop; otherwise, RoutePointer remains unchanged.

If a handle does not need to be returned: On input, RoutePointer 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_ACCESS_DENIED	The calling client does not own this route.
ERROR_INVALID_HANDLE	The handle is invalid.

Remarks

Do not call any other RTMv2 functions until the route is unlocked by a call to RtmLockRoute and the LockRoute parameter is set to FALSE, or a call to RtmUpdateAndUnlockRoute.

Currently, this function locks the entire destination, not just the route.

Clients can only change the Neighbour, PrefInfo, BelongsToViews, EntitySpecificInfo, and NextHopsList members of the RTM_ROUTE_INFO structure.

If any of these values are changed, the client must call RtmUpdateAndUnlockRoute to notify the routing table manager of the changes.

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