ListChanges Method

Lists changes to resources in the currently selected drive.

Syntax

int ListChanges();

Remarks

This method lists changes to resources in the drive currently selected by Drive.

Starting from a Baseline State

For most use-cases, it is necessary to obtain a baseline of the full drive hierarchy in order to have a context onto which later changes can be applied.

To obtain a full drive hierarchy baseline, ensure that both ChangeMarker and NextChangeMarker are empty, and then call ListChanges. Then follow the process described in the "General Usage" section (below) until ChangeMarker is empty, keeping in mind that the results being returned are not necessarily* changes, but rather the current state of all resources in the drive.

*If any resources in the drive are changed before all result pages of the baseline have been returned, OneDrive may append those change items to the end of the baseline's results. Refer to the "Usage Considerations" section (below) for more information.

Starting from the Latest State

For use-cases that don't require a baseline (e.g., perhaps an application just displays a "ticker" with change information), call GetCurrentChangeMarker. This will populate NextChangeMarker immediately.

General Usage

When this method is called, it will use the change marker stored in either ChangeMarker or NextChangeMarker (only one can be populated at a time) to request the next page of changes. This method causes the ResourceList event to fire once for each change, and will also populate the Resource* properties.

If there are still more changes available to list when this method returns, the ChangeMarker property will be populated. Continue to call this method until ChangeMarker is empty to accumulate all pages of results in the Resource* properties. (Once there aren't any more changes available to list, the NextChangeMarker property will be populated instead.)

When NextChangeMarker is populated, it is always populated with a value that (at the time of population) points to the most current state. (Since "the most current state" implies that there are no further changes to list, calling ListChanges immediately after NextChangeMarker is populated will not return any further changes.)

Example of Getting a Baseline and then Listing Changes

// Get a full drive hierarchy baseline first.
Onedrive onedrive = new Onedrive();

onedrive.ListChanges();
do {
  // Continue to call ListChanges() until ChangeMarker is the empty string (indicating there
  // are no more changes to list).
  onedrive.ListChanges();
} while (onedrive.ChangeMarker.Length > 0);

for (int i = 0; i < onedrive.Resources.Count; i++) {
  // Apply the baseline drive state.
}

// Now NextChangeMarker will be populated. If we were to call ListChanges() again right now,
// nothing would be listed and NextChangeMarker would still be populated.

// Wait 2 minutes and then try to list changes again. Assume something changes while we wait.
Thread.Sleep(120000);

onedrive.ListChanges();
do {
  onedrive.ListChanges();
} while (onedrive.ChangeMarker.Length > 0);

for (int i = 0; i < onedrive.Resources.Count; i++) {
  // Apply the changes.
}

Usage Considerations

Keep the following things in mind when working with OneDrive changes:
  • When listing changes, certain resource properties are not included. For example, resource paths are not returned; always use resource Ids when tracking changes.
  • It is possible for a resource, uniquely identified by its Id, to appear more than once in a change set. (This can happen if changes are being listed, and then a change occurs before all result pages in the change set are returned; OneDrive will then typically append the new change to the end of the current change set.) Since a OneDrive change always reflects the latest state of a resource, just use the latest one.
  • OneDrive will report a change when a resource is created, renamed, modified, or deleted; but it only explicitly specifies deletions. However, it is easy to differentiate between the other change events by keeping track of resource Ids, names, and last modified times; and then comparing old and new values when changes arrive.

Error Handling

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Cloud 2020 Qt Edition - Version 20.0 [Build 8265]