providePlaceholder(at:completionHandler:)

Triggers the creation of a placeholder for the given URL.

Declaration

func providePlaceholder(at url: URL, completionHandler: @escaping  @Sendable ((any Error)?) -> Void)

func providePlaceholder(at url: URL) async throws

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

important:

You can call this method from synchronous code using a completion handler, as shown on this page, or you can call it as an asynchronous method that has the following declaration:

func providePlaceholder(at url: URL) async throws

For information about concurrency and asynchronous code in Swift, see Calling Objective-C APIs Asynchronously.

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 providePlaceholder(at: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

Get the document’s persistent identifier by calling persistentIdentifierForItem(at:), and pass in the value of the url parameter.
Call item(for:), and pass in the persistent identifier. This method returns the file provider item for the document.

Write the Placeholder

Get the placeholder URL by calling placeholderURL(for:), and pass in the value of the url parameter.
Call writePlaceholder(at:withMetadata:), 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)
    }
}