Framework

FileProvider

Implement a File Provider extension so that other apps can access the documents and directories stored and managed by your containing app.

Overview

If your app is primarily focused on storing and managing user documents, you can implement a File Provider extension to give users access to their content while they're using other apps.

Your file provider provides access to files stored on your server.

The File Provider extension:

Creates placeholders for remote files that you download only as needed.
Intercepts coordinated reads from the host app, so that the file can be downloaded or updated from the remote server before the read occurs.
Triggers a notification after coordinated writes from the host app, so that the extension can upload the changes to the remote server as needed.
Enumerates the stored documents and folders.
Executes actions—such as importing, moving, renaming, or deleting items—on the stored documents and folders.

Other apps access the stored documents using either the UIDocumentBrowserViewController or UIDocumentPickerViewController classes. These classes provide a standard user interface for browsing and interacting with the stored documents and folders. However, you can add custom actions to the browser's context menu using the FileProviderUI framework.

You can also define custom message interfaces for your file provider. Use these interfaces to add features that aren't provided by the base API. For more information, see NSFileProviderService.

Does Your App Need a File Provider?

In general, implement a File Provider extension only if your app provides access to documents stored on a remote server. You don't need a File Provider extension to provide access to documents stored locally.

To give other apps access to the files in your Documents directory, just set the proper keys in your app's Info.plist file. You can either set the UISupportsDocumentBrowser key (for document browser-based apps), or set both the UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace keys.

These keys enable other apps to open and edit the contents of your Documents directory in place. Your files also appear in both the Files app and the document browser. For more information, see the UIDocumentBrowserViewController class.

Supporting Drag and Drop

If your application acts as a drag source for remote documents, override your NSItemProvider subclass's registerFileRepresentation(forTypeIdentifier:fileOptions:visibility:loadHandler:) method, and return the URL for the item being dragged. This URL is the value returned by your extension's urlForItem(withPersistentIdentifier:) method. The URL may refer to a local file or (if you don't have a local copy) to the file's placeholder.

If the URL points to a placeholder, the system calls your File Provider extension's startProvidingItem(at:completionHandler:) method, giving you the opportunity to download the file.

Topics

First Steps

class NSFileProviderExtension

The principal class for the File Provider extension.

class NSFileProviderManager

A manager object that you use to communicate with the file provider from either your app or your File Provider extension.

Provided Items

Items provide information about the documents and folders managed by your file provider.

typealias NSFileProviderItem

An item managed by the File Provider extension.

protocol NSFileProviderItemProtocol

A protocol that defines the properties of an item managed by the File Provider extension.

struct NSFileProviderItemIdentifier

A unique identifier for an item managed by the File Provider extension.

struct NSFileProviderItemCapabilities

An item's capabilities, which define the actions that the user can perform in the document browser.

Content and Change Tracking

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

Compatibility

Creating File Providers for Multiple Versions of iOS

Create File Provider extensions that support different versions of iOS.

Errors

struct NSFileProviderError

A structure that contains information about file provider errors.

let NSFileProviderErrorDomain: String

The domain for errors raised by the File Provider extension.

let NSFileProviderErrorCollidingItemKey: String

The key for accessing the existing item from a filename collision error's userInfo property.

Deprecated

let NSFileProviderErrorNonExistentItemIdentifierKey: String

The key for accessing the identifier from a NSFileProviderError.Code.noSuchItem error's userInfo property.

Protocols

protocol NSFileProviderItemDecorating

protocol NSFileProviderItemFlags

Reference

FileProvider Data Types