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-ом и заставицама. Провајдер мора бити заштићен од директног приступа преко permisssion-а — препоручује се коришћење android:exported="true" са експлицитним permissions-ом.

<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 користи уграђени системски прегледач датотека, а проширење провајдера одговара само за пружање садржаја на захтев.