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 використовує вбудований системний браузер файлів, а провайдер розширення відповідає лише за надання контенту за запитом.