Content and Change Tracking

Create enumerators to specify your file provider's content, and track changes to that content.

Overview

To display your file provider's items to the user, you tell the system about those items and any changes to their contents. You do this by providing enumerators.

To provide an enumerator, create a class that adopts the NSFileProviderEnumerator protocol. The system uses this enumerator to represent an item (a folder or a document) managed by your file provider. In addition, the system uses the enumerator to track any changes to the item.

The system also uses an enumerator to track the working set (a set of special items like Recents or Favorites).

You create enumerators to handle these use cases:

When...

You are passed...

Your enumerator returns...

The user begins browsing your file provider's content

The rootContainer constant

The content of your file provider's root directory, and any changes to that content

The user opens a new folder while browsing your file provider's content

The folder's persistent identifier

The content of the specified folder, and any changes to its content

The user opens a document from your file provider

The document's persistent identifier

Changes to the open document

The system is alerted to changes to the working set

The workingSet constant

The content of your working set, and any changes to that content

Once requested, an enumerator is used to provide both the content and any changes for an item. When the system is finished with the item, it calls the enumerator’s invalidate() method. For example, if you return an enumerator that provides the content of a directory, as long as the enumerator is active, the system also uses it to enumerate changes to the directory.

The system may have multiple, active enumerators for a number of different items. Some of these may represent items that are currently displayed on screen. Others may be items that are no longer displayed, but the enumerator is retained for performance reasons. You need to inform the system of any changes to the content managed by any of the active enumerators, as well as any changes to the working set (whether or not it has an active enumerator).

Topics

First Steps

protocol NSFileProviderEnumerator

A protocol for enumerating items and changes.

Content

Defining Your File Provider's Content

Create enumerators to specify your file provider's content.

protocol NSFileProviderEnumerationObserver

An observer that receives batches of items during enumeration.

struct NSFileProviderPage

A synchronization point that represents the next batch of items to be returned by an enumerator.

Change Tracking

Tracking Your File Provider's Changes

Create an enumerator to track changes to your file provider's content.

protocol NSFileProviderChangeObserver

An observer that receives changes and deletions during enumeration.

struct NSFileProviderSyncAnchor

A synchronization point that represents the last batch of changes returned by the enumerator.