Instance Method

providePlaceholderAtURL:completionHandler:

Triggers the creation of a placeholder for the given URL.

Declaration

- (void)providePlaceholderAtURL:(NSURL *)url completionHandler:(void (^)(NSError *error))completionHandler;

Parameters

url

The URL of a shared document.

completionHandler

A block that the system calls after the placeholder is created.

The completion handler takes the following parameter:

error

If the placeholder was successfully written to disk, this value is nil. Otherwise, it holds an NSError object describing the error.

Discussion

The system calls this method when it needs a placeholder for a document that's returned by the File Provider extension, but is not stored locally. Override providePlaceholderAtURL:completionHandler: to create a placeholder for the given URL. This task can be broken into three steps: looking up the document’s file provider item, writing the placeholder, and calling the completion handler.

Look Up the Document's File Provider Item

  1. Get the document’s persistent identifier by calling persistentIdentifierForItemAtURL:, and pass in the value of the url parameter.

  2. Call itemForIdentifier:error:, and pass in the persistent identifier. This method returns the file provider item for the document.

Write the Placeholder

  1. Get the placeholder URL by calling placeholderURLForURL:, and pass in the value of the url parameter.

  2. Call writePlaceholderAtURL:withMetadata:error:, and pass in the placeholder URL and the file provider item.

Call the Completion Handler

After writing the placeholder to disk, call the completion handler. If any errors occur, pass them to the completion handler. The system then passes the error back to the original coordinated read or write.

Sample Implementation

override func providePlaceholder(at url: URL, completionHandler: @escaping (Error?) -> Void) {
    
    guard let identifier = persistentIdentifierForItem(at: url) else {
        completionHandler(NSFileProviderError(.noSuchItem))
        return
    }
    
    do {
        let fileProviderItem = try item(for: identifier)
        
        let placeholderURL = NSFileProviderManager.placeholderURL(for: url)
        try NSFileProviderManager.writePlaceholder(at: placeholderURL,
                                                   withMetadata: fileProviderItem)
        
        completionHandler(nil)
    }
    catch let error {
        completionHandler(error)
    }
}

See Also

Managing Shared Files

- itemChangedAtURL:

Tells the File Provider extension that a document has changed.

Deprecated
- startProvidingItemAtURL:completionHandler:

Provides an actual file on disk for a placeholder.

Deprecated
- stopProvidingItemAtURL:

Tells the File Provider extension that a given document is no longer being accessed.

Deprecated