DocumentProvider — What It Is, Creating a Provider and Working with Files

What is DocumentProvider?

DocumentsProvider is a base Android class that extends ContentProvider, allowing an application to provide its files to other applications through the system SAF interface. The provider creates a virtual file system that the user sees in the document selection dialog.

Each provider organizes files into roots — top-level entry points. For example, Google Drive has roots “My Drive” and “Shared with Me.” Within a root, the provider returns a tree of documents, where each document is a file or directory with a specific MIME type, size, and dates.

DocumentProvider is part of the android.provider package and is available starting from Android 4.4 (API 19). The provider is used by cloud services, password managers, note-taking apps, and any programs that store files in their own format.

How to Create a Custom DocumentProvider

Creating your own DocumentProvider begins with extending the DocumentsProvider class and implementing four required methods. The provider defines the file structure that appears in the system SAF picker when selecting files.

The first method is queryRoots, which returns a cursor with the columns Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY, and Root.COLUMN_FLAGS. Each root can support flags: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH, and FLAG_SUPPORTS_IS_CHILD.

The second mandatory method is queryChildDocuments, which returns the child documents of a specified URI. This method is called when the user opens a directory in the picker. Each document contains the columns: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE, and COLUMN_LAST_MODIFIED.

Mandatory Methods of DocumentsProvider

DocumentsProvider requires implementing four methods that form the file structure for the picker. Without them, the provider will not work — the system SAF dialog will not be able to display files.

• queryRoots — returns the root entry points to the storage. Each root is represented by a row in the cursor with an ID, name, and icon.
• queryDocument — returns a single document by its ID. Used to get information about a specific file.
• queryChildDocuments — returns child documents for the specified parent directory URI.
• openDocument — opens a document by ID and returns a ParcelFileDescriptor for reading or writing.

Additionally, you can implement createDocument for creating new files, deleteDocument for deletion, and renameDocument for renaming. These methods require the FLAG_SUPPORTS_CREATE flag in the root.

Registering the Provider in AndroidManifest

DocumentProvider is registered in AndroidManifest.xml as a regular ContentProvider with an additional intent filter and flags. The provider must be protected from direct access via permission — it is recommended to use android:exported="true" with explicit permission.

<provider
    android:name=".provider.CustomDocumentProvider"
    android:authorities="com.example.app.documents"
    android:exported="true"
    android:grantUriPermissions="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action
            android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
    <meta-data
        android:name="android.content.documents.roots"
        android:resource="@xml/file_paths" />
</provider>

The grantUriPermissions flag allows SAF to temporarily delegate access rights to the calling application. The authorities attribute must be unique — usually the package name with the .documents suffix is used. It is also recommended to specify meta-data with an XML resource for configuring roots.

Code Example: Implementing DocumentsProvider

Implementing DocumentsProvider requires returning a ParcelFileDescriptor from the openDocument method. For local files, ParcelFileDescriptor.open is used; for cloud files, ParcelFileDescriptor.open with Pipe is used for streaming. The code must handle access errors and missing files.

class CustomDocumentProvider : DocumentsProvider() {

    override fun queryRoots(): Cursor {
        val matrix = MatrixCursor(Root.COLUMNS)
        matrix.newRow().add(Root.COLUMN_ROOT_ID, "local")
            .add(Root.COLUMN_TITLE, "My Files")
            .add(Root.COLUMN_SUMMARY, "Local documents")
            .add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE)
        return matrix
    }

    override fun openDocument(
        documentId: String, flags: Int, cursor: CancellationSignal?
    ): ParcelFileDescriptor {
        val file = File(context.filesDir, documentId)
        val accessMode = ParcelFileDescriptor.parseMode(flags)
        return ParcelFileDescriptor.open(file, accessMode)
    }
}

Handling Virtual Documents

DocumentProvider can return virtual files — documents that do not exist as separate files on disk. For example, a database note can be presented as a virtual PDF. This uses a MIME type with the FLAG_VIRTUAL_DOCUMENT flag, and openDocument converts the data to the required format before sending.

DocumentProvider in iOS: UIDocumentPickerViewController

iOS has a similar mechanism — UIDocumentPickerViewController, which also provides a unified file selection interface. However, in iOS, the document provider is implemented through UIDocumentPickerDelegate and App Extensions with the Document Provider type.

Unlike Android DocumentsProvider, iOS UIDocumentPickerViewController does not require creating a custom provider for local files — the system picker supports iCloud Drive and local storage by default. Third-party cloud services register through a Document Provider extension with the Info.plist key NSExtensionFileProviderDocumentInterface.

The main difference: in Android, DocumentProvider is actively called through a SAF Intent and must implement navigation itself. In iOS, UIDocumentPickerViewController uses a built-in system file browser, and the extension provider is only responsible for providing content on request.