RtmGetChangedDests function (rtmv2.h)

Article
10/13/2021

The RtmGetChangedDests function returns a set of destinations with changed information.

Syntax

DWORD RtmGetChangedDests(
  [in]      RTM_ENTITY_HANDLE RtmRegHandle,
  [in]      RTM_NOTIFY_HANDLE NotifyHandle,
  [in, out] PUINT             NumDests,
  [out]     PRTM_DEST_INFO    ChangedDests
);

Parameters

[in] RtmRegHandle

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

[in] NotifyHandle

Handle to a change notification obtained from a previous call to RtmRegisterForChangeNotification.

[in, out] NumDests

On input, NumDests is a pointer to a UINT value that specifies the maximum number of destinations that can be received by ChangedDests.

On output, NumDests receives the actual number of destinations received by ChangedDests.

[out] ChangedDests

On input, ChangedDests is a pointer to an array of RTM_DEST_INFO structures.

On output, ChangedDests is filled with the changed 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
ERROR_INVALID_PARAMETER	A parameter contains incorrect information.
ERROR_NO_MORE_ITEMS	No more changed destinations to retrieve.

Remarks

A client is notified of changes by an RTM_EVENT_CALLBACK. The RTM_EVENT_CALLBACK is only used to notify the client, not deliver the changes. After a change notification is received, the client must call RtmGetChangedDests repeatedly to retrieve all the changes.

If two or more changes to the same destination have occurred since the notification, only the latest change is returned.

When a client no longer needs the handles in ChangedDests, the client must use RtmReleaseChangedDests to release the handles.

For sample code using this function, see Use the Event Notification Callback.

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