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-filter и флагове. Доставчикът трябва да бъде защитен от директен достъп чрез 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 трябва да бъде уникален — обикновено се използва името на пакета с наставка .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 използва вградения системен файлов браузър, а разширението на доставчика отговаря само за предоставяне на съдържание при поискване.