RtmRegisterForChangeNotification function (rtmv2.h)

Article
10/13/2021

The RtmRegisterForChangeNotification function informs the routing table manager that the client should receive change notifications for the specified types of changes. The routing table manager returns a change notification handle, which the client must use when requesting change information after receiving a change notification message.

Syntax

DWORD RtmRegisterForChangeNotification(
  [in]  RTM_ENTITY_HANDLE  RtmRegHandle,
  [in]  RTM_VIEW_SET       TargetViews,
  [in]  RTM_NOTIFY_FLAGS   NotifyFlags,
  [in]  PVOID              NotifyContext,
  [out] PRTM_NOTIFY_HANDLE NotifyHandle
);

Parameters

[in] RtmRegHandle

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

[in] TargetViews

Specifies the views in which to register for change notification.

[in] NotifyFlags

Specifies the flags that indicate the type of changes for which the client requests notification. The following flags are used. (The flags are to be joined using a logical OR.)

Constant	Meaning
RTM_CHANGE_TYPE_ALL	Notify the client of any change to a destination.
RTM_CHANGE_TYPE_BEST	Notify the client of changes to the current best route, or when the best route changes.
RTM_CHANGE_TYPE_FORWARDING	Notify the client of any best route changes that affect forwarding, such as next hop changes.
RTM_NOTIFY_ONLY_MARKED_DESTS	Notify the client of changes to destinations that the client has marked. If this flag is not specified, change notification messages for all destinations are sent.

[in] NotifyContext

Specifies the notification context that the RTM_EVENT_CALLBACK uses to indicate new changes. The notification context is the Context2 parameter of the RTM_EVENT_CALLBACK callback.

[out] NotifyHandle

Receives a handle to a change notification. The handle must be used when calling RtmGetChangedDests.

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_INVALID_PARAMETER	A parameter contains incorrect information.
ERROR_NO_SYSTEM_RESOURCES	There are not enough available system resources to complete this operation. The routing table manager has exceeded the maximum number of change notifications that can be cached.
ERROR_NOT_ENOUGH_MEMORY	There is not enough memory to complete this operation.
ERROR_NOT_SUPPORTED	One or more of the specified views is not supported.

Remarks

A client calls RtmMarkDestForChangeNotification when it is registering for changes to a specific destination.

The routing table manager uses the RTM_EVENT_CALLBACK callback, specified when the client called RtmRegisterEntity, to notify the client when changes have occurred; the client must call RtmGetChangedDests to receive the actual change information.

For sample code using this function, see Register For Change Notification.

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