Contents

CKFetchRecordZoneChangesOperation

An operation that fetches record zone changes.

Declaration

class CKFetchRecordZoneChangesOperation

Mentioned in

Overview

Use this operation to fetch record changes in one or more record zones, such as those that occur during record creation, modification, and deletion. You provide a configuration object for each record zone to query for changes. The configuration contains a server change token, which is an opaque pointer to a specific change in the zone’s history. CloudKit returns only the changes that occur after that point. For the first time you fetch a record zone’s changes, or to refetch all changes in a zone’s history, use nil instead.

CloudKit processes the record zones in succession, and returns the changes for each zone in batches. Each batch yields a new change token. If all batches return without error, the operation issues a final change token for that zone. The change tokens conform to NSSecureCoding and are safe to cache on-disk. This operation’s tokens aren’t compatible with CKFetchDatabaseChangesOperation so you should segregate them in your app’s cache. Don’t infer behavior or order from the tokens’ contents.

If you create record zones in the private database, fetch all changes the first time the app launches. Cache the results on-device and use CKRecordZoneSubscription to subscribe to future changes. Fetch those changes on receipt of the push notifications the subscription generates. If you use the shared database, subscribe to changes with CKDatabaseSubscription instead. When a user participates in sharing, CloudKit adds and removes record zones. This means you don’t know in advance which zones exist in the shared database. Use CKFetchDatabaseChangesOperation to fetch shared record zones on receipt of the subscription’s push notifications. Then fetch the changes in those zones using this operation. Regardless of which database you use, it’s not necessary to perform fetches each time your app launches, or to schedule fetches at regular intervals.

To run the operation, add it to the corresponding database’s operation queue. The operation executes its callbacks on a private serial queue.

The following example demonstrates how to create the operation, configure its callbacks, and execute it. For brevity, it omits the delete and operation completion callbacks.

// Create a dictionary that maps a record zone ID to its
// corresponding zone configuration. The configuration
// contains the server change token from the most recent
// fetch of that record zone.
NSMutableDictionary *configurations = [NSMutableDictionary new];
for (CKRecordZoneID *recordZoneID in recordZoneIDs) {
    CKFetchRecordZoneChangesConfiguration *config =
        [CKFetchRecordZoneChangesConfiguration new];
    config.previousServerChangeToken = [tokenCache objectForKey:recordZoneID];
    [configurations setObject:config forKey:recordZoneID];
}

// Create a fetch operation with an array of record zone IDs
// and the zone configuration mapping dictionary.
CKFetchRecordZoneChangesOperation *operation =
    [[CKFetchRecordZoneChangesOperation alloc]
     initWithRecordZoneIDs:recordZoneIDs
     configurationsByRecordZoneID:configurations];

// Process each changed record as CloudKit returns it.
operation.recordChangedBlock = ^(CKRecord *record) {
    recordHandler(record);
};

// Cache the change tokens that CloudKit provides as
// the operation runs.
operation.recordZoneChangeTokensUpdatedBlock = ^(CKRecordZoneID *recordZoneID,
                                                 CKServerChangeToken *token,
                                                 NSData *data) {
    [tokenCache setObject:token forKey:recordZoneID];
};

// If the fetch for the current record zone completes
// successfully, cache the final change token.
operation.recordZoneFetchCompletionBlock = ^(CKRecordZoneID *recordZoneID,
                                             CKServerChangeToken *token,
                                             NSData *data, BOOL more,
                                             NSError *error) {
    if (error) {
        // Handle the error.
    } else {
        [tokenCache setObject:token forKey:recordZoneID];
    }
};

// Set an appropriate QoS and add the operation to the shared
// database's operation queue to execute it.
operation.qualityOfService = NSQualityOfServiceUtility;
[CKContainer.defaultContainer.sharedCloudDatabase addOperation:operation];

Topics

Creating a Zone Change Operation

Configuring the Zone Change Operation

Processing the Zone Change Operation Results

Deprecated

Instance Properties

See Also

Record Zone Changes