DocumentProvider — что это, создание провайдера и работа с файлами

Что такое DocumentProvider?

DocumentsProvider — это базовый класс Android, наследующий ContentProvider, который позволяет приложению предоставлять свои файлы другим приложениям через системный интерфейс SAF. Провайдер создаёт виртуальную файловую систему, которую видит пользователь в диалоге выбора документов.

Каждый провайдер организует файлы в корни (roots) — верхнеуровневые точки входа. Например, Google Drive имеет корни "Мой диск" и "Доступные мне". Внутри корня провайдер возвращает дерево документов, где каждый документ — это файл или директория с определёнными MIME-типом, размером и датами.

DocumentProvider входит в состав android.provider пакета и доступен начиная с Android 4.4 (API 19). Провайдер используется облачными сервисами, менеджерами паролей, приложениями заметок и любыми программами, хранящими файлы в собственном формате.

Как создать кастомный DocumentProvider

Создание собственного DocumentProvider начинается с наследования класса DocumentsProvider и реализации четырёх обязательных методов. Провайдер определяет файловую структуру, которая отображается в системном пикере SAF при выборе файлов.

Первый метод — queryRoots, который возвращает курсор с колонками Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY и Root.COLUMN_FLAGS. Каждый корень может поддерживать флаги: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH и FLAG_SUPPORTS_IS_CHILD.

Второй обязательный метод — queryChildDocuments, возвращающий дочерние документы указанного URI. Этот метод вызывается, когда пользователь открывает директорию в пикере. Каждый документ содержит колонки: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE и COLUMN_LAST_MODIFIED.

Обязательные методы DocumentsProvider

DocumentsProvider требует реализации четырёх методов, которые формируют файловую структуру для пикера. Без них провайдер не будет работать — системный SAF диалог не сможет отобразить файлы.

• queryRoots — возвращает корневые точки входа в хранилище. Каждый корень представлен строкой в курсоре с ID, названием и иконкой.
• queryDocument — возвращает один документ по его ID. Используется для получения информации о конкретном файле.
• queryChildDocuments — возвращает дочерние документы для указанного URI родительской директории.
• openDocument — открывает документ по ID и возвращает ParcelFileDescriptor для чтения или записи.

Дополнительно можно реализовать createDocument для создания новых файлов, deleteDocument для удаления и renameDocument для переименования. Эти методы требуют флага FLAG_SUPPORTS_CREATE в корне.

Регистрация провайдера в AndroidManifest

DocumentProvider регистрируется в AndroidManifest.xml как обычный ContentProvider с дополнительным intent-фильтром и флагами. Провайдер должен быть защищён от прямого доступа через permission — рекомендуется использовать android:exported="true" с явным 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>

Флаг grantUriPermissions позволяет SAF временно делегировать права доступа вызывающему приложению. Атрибут authorities должен быть уникальным — обычно используется package name с суффиксом .documents. Рекомендуется также указать meta-data с XML-ресурсом для настройки корней.

Пример кода: реализация DocumentsProvider

Реализация DocumentsProvider требует вернуть ParcelFileDescriptor из метода openDocument. Для локальных файлов используется ParcelFileDescriptor.open, для облачных — ParcelFileDescriptor.open с Pipe для потоковой передачи. Код должен обрабатывать ошибки доступа и отсутствия файлов.

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)
    }
}

Обработка виртуальных документов

DocumentProvider может возвращать виртуальные файлы — документы, не существующие как отдельные файлы на диске. Например, заметка из базы данных может быть представлена как виртуальный PDF. Для этого используется MIME-тип с флагом FLAG_VIRTUAL_DOCUMENT, а openDocument конвертирует данные в нужный формат перед отправкой.

DocumentProvider в iOS: UIDocumentPickerViewController

iOS имеет аналогичный механизм — UIDocumentPickerViewController, который также предоставляет единый интерфейс выбора файлов. Однако в iOS провайдер документов реализуется через UIDocumentPickerDelegate и расширения приложений (App Extensions) с типом Document Provider.

В отличие от Android DocumentsProvider, iOS UIDocumentPickerViewController не требует создания кастомного провайдера для локальных файлов — системный пикер поддерживает iCloud Drive и локальное хранилище по умолчанию. Сторонние облачные сервисы регистрируются через Document Provider extension с Info.plist ключом NSExtensionFileProviderDocumentInterface.

Основное различие: в Android DocumentProvider активно вызывается через SAF Intent и должен сам реализовать навигацию. В iOS UIDocumentPickerViewController использует встроенный системный браузер файлов, а провайдер расширения отвечает только за предоставление контента по запросу.