RtmLockRoute function (rtmv2.h)
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 |
|---|---|
|
The calling client does not own this route. |
|
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 |