DocumentProvider — ce este, crearea furnizorului și lucrul cu fișiere

Ce este DocumentProvider?

DocumentsProvider — este o clasă de bază Android care moștenește ContentProvider și permite aplicației să își ofere fișierele altor aplicații prin interfața de sistem SAF. Furnizorul creează un sistem de fișiere virtual pe care utilizatorul îl vede în dialogul de selectare a documentelor.

Fiecare furnizor organizează fișierele în rădăcini (roots) — puncte de intrare de nivel superior. De exemplu, Google Drive are rădăcinile „Discul meu” și „Partajate cu mine”. În interiorul rădăcinii, furnizorul returnează un arbore de documente, unde fiecare document este un fișier sau director cu un tip MIME, dimensiune și date specifice.

DocumentProvider face parte din pachetul android.provider și este disponibil începând cu Android 4.4 (API 19). Furnizorul este utilizat de servicii cloud, manageri de parole, aplicații de notițe și orice programe care stochează fișiere în format propriu.

Cum să creați un DocumentProvider personalizat

Crearea propriului DocumentProvider începe cu moștenirea clasei DocumentsProvider și implementarea a patru metode obligatorii. Furnizorul definește structura fișierelor care este afișată în selectorul de sistem SAF la selectarea fișierelor.

Prima metodă — queryRoots, care returnează un cursor cu coloanele Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY și Root.COLUMN_FLAGS. Fiecare rădăcină poate suporta flagurile: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH și FLAG_SUPPORTS_IS_CHILD.

A doua metodă obligatorie — queryChildDocuments, care returnează documentele copil pentru URI-ul specificat. Această metodă este apelată când utilizatorul deschide un director în selector. Fiecare document conține coloanele: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE și COLUMN_LAST_MODIFIED.

Metodele obligatorii ale DocumentsProvider

DocumentsProvider necesită implementarea a patru metode care formează structura fișierelor pentru selector. Fără ele, furnizorul nu va funcționa — dialogul de sistem SAF nu va putea afișa fișierele.

• queryRoots — returnează punctele de intrare rădăcină în depozit. Fiecare rădăcină este reprezentată de un rând în cursor cu ID, nume și pictogramă.
• queryDocument — returnează un document după ID-ul său. Folosit pentru a obține informații despre un fișier specific.
• queryChildDocuments — returnează documentele copil pentru URI-ul directorului părinte specificat.
• openDocument — deschide documentul după ID și returnează ParcelFileDescriptor pentru citire sau scriere.

Suplimentar, se pot implementa createDocument pentru crearea de fișiere noi, deleteDocument pentru ștergere și renameDocument pentru redenumire. Aceste metode necesită flagul FLAG_SUPPORTS_CREATE în rădăcină.

Înregistrarea furnizorului în AndroidManifest

DocumentProvider se înregistrează în AndroidManifest.xml ca un ContentProvider obișnuit cu intent-filter și flaguri suplimentare. Furnizorul trebuie protejat de accesul direct prin permission — se recomandă utilizarea android:exported="true" cu permission explicit.

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

Flagul grantUriPermissions permite SAF să delegheze temporar drepturile de acces aplicației apelante. Atributul authorities trebuie să fie unic — de obicei se folosește numele pachetului cu sufixul .documents. Se recomandă, de asemenea, specificarea meta-data cu resursă XML pentru configurarea rădăcinilor.

Exemplu de cod: implementarea DocumentsProvider

Implementarea DocumentsProvider necesită returnarea ParcelFileDescriptor din metoda openDocument. Pentru fișierele locale se folosește ParcelFileDescriptor.open, pentru cele cloud — ParcelFileDescriptor.open cu Pipe pentru transmitere în flux. Codul trebuie să gestioneze erorile de acces și absența fișierelor.

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

Gestionarea documentelor virtuale

DocumentProvider poate returna fișiere virtuale — documente care nu există ca fișiere separate pe disc. De exemplu, o notă din baza de date poate fi prezentată ca un PDF virtual. Pentru aceasta se folosește tipul MIME cu flagul FLAG_VIRTUAL_DOCUMENT, iar openDocument convertește datele în formatul solicitat înainte de trimitere.

DocumentProvider în iOS: UIDocumentPickerViewController

iOS are un mecanism similar — UIDocumentPickerViewController, care oferă, de asemenea, o interfață unificată de selectare a fișierelor. Cu toate acestea, în iOS, furnizorul de documente este implementat prin UIDocumentPickerDelegate și extensii de aplicații (App Extensions) cu tipul Document Provider.

Spre deosebire de Android DocumentsProvider, iOS UIDocumentPickerViewController nu necesită crearea unui furnizor personalizat pentru fișiere locale — selectorul de sistem suportă iCloud Drive și stocarea locală în mod implicit. Serviciile cloud terțe se înregistrează prin Document Provider extension cu cheia Info.plist NSExtensionFileProviderDocumentInterface.

Diferența principală: în Android, DocumentProvider este apelat activ prin SAF Intent și trebuie să implementeze singur navigarea. În iOS, UIDocumentPickerViewController folosește navigatorul de fișiere de sistem încorporat, iar extensia furnizorului răspunde doar pentru furnizarea conținutului la cerere.