DocumentProvider — mi ez, szolgáltató létrehozása és fájlokkal való munka

Mi az a DocumentProvider?

DocumentsProvider — egy alap Android osztály, amely örökli a ContentProvider-t és lehetővé teszi egy alkalmazás számára, hogy fájljait más alkalmazásoknak biztosítsa a SAF rendszerfelületén keresztül. A szolgáltató egy virtuális fájlrendszert hoz létre, amelyet a felhasználó a dokumentumkiválasztási párbeszédablakban lát.

Minden szolgáltató gyökerekbe (roots) — legfelső szintű belépési pontokba rendezi a fájlokat. Például a Google Drive rendelkezik a „Saját lemez" és a „Megosztva velem" gyökerekkel. A gyökérben a szolgáltató egy dokumentumfát ad vissza, ahol minden dokumentum egy fájl vagy könyvtár meghatározott MIME-típussal, mérettel és dátumokkal.

A DocumentProvider az android.provider csomag része, és Android 4.4-től (API 19) érhető el. A szolgáltatót felhőszolgáltatások, jelszókezelők, jegyzetalkalmazások és minden olyan program használja, amely saját formátumban tárol fájlokat.

Egyéni DocumentProvider létrehozása

Létrehozása a saját DocumentProvider-nek a DocumentsProvider osztály öröklésével és négy kötelező metódus implementálásával kezdődik. A szolgáltató meghatározza a fájlszerkezetet, amely a SAF rendszerválasztójában jelenik meg fájlok kiválasztásakor.

Az első metódus — queryRoots, amely egy kurzort ad vissza a Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY és Root.COLUMN_FLAGS oszlopokkal. Minden gyökér támogathatja a FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH és FLAG_SUPPORTS_IS_CHILD jelzőket.

A második kötelező metódus — queryChildDocuments, amely visszaadja a megadott URI gyermekdokumentumait. Ezt a metódust akkor hívják meg, amikor a felhasználó megnyit egy könyvtárat a választóban. Minden dokumentum tartalmazza a Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE és COLUMN_LAST_MODIFIED oszlopokat.

A DocumentsProvider kötelező metódusai

DocumentsProvider négy metódus implementálását követeli meg, amelyek a fájlszerkezetet alkotják a választó számára. Nélkülük a szolgáltató nem fog működni — a SAF rendszer párbeszédablaka nem tudja megjeleníteni a fájlokat.

• queryRoots — visszaadja a tároló gyökér belépési pontjait. Minden gyökeret egy sor képvisel a kurzorban ID-vel, névvel és ikonnal.
• queryDocument — visszaad egy dokumentumot az ID-ja alapján. Egy adott fájlról való információ lekérésére használják.
• queryChildDocuments — visszaadja a gyermekdokumentumokat a megadott szülő könyvtár URI-jához.
• openDocument — megnyitja a dokumentumot ID alapján, és ParcelFileDescriptor-t ad vissza olvasáshoz vagy íráshoz.

Ezenkívül implementálható a createDocument új fájlok létrehozásához, a deleteDocument törléshez és a renameDocument átnevezéshez. Ezek a metódusok a FLAG_SUPPORTS_CREATE jelzőt igénylik a gyökérben.

A szolgáltató regisztrálása az AndroidManifest-ben

DocumentProvider regisztrálása az AndroidManifest.xml-ben egy szokásos ContentProvider-ként történik, további intent-filterrel és jelzőkkel. A szolgáltatót védeni kell a közvetlen hozzáféréstől permission segítségével — ajánlott az android:exported="true" használata explicit permission-nel.

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

A grantUriPermissions jelző lehetővé teszi a SAF számára, hogy ideiglenesen delegálja a hozzáférési jogokat a hívó alkalmazásnak. Az authorities attribútumnak egyedinek kell lennie — általában a csomagnév .documents utótaggal használatos. Ajánlott továbbá meta-data megadása XML erőforrással a gyökerek konfigurálásához.

Kód példa: DocumentsProvider implementálása

Implementálása a DocumentsProvider-nek megköveteli a ParcelFileDescriptor visszaadását az openDocument metódusból. Helyi fájlokhoz ParcelFileDescriptor.open, felhőfájlokhoz ParcelFileDescriptor.open Pipe-pal a streamelt átvitelhez használatos. A kódnak kezelnie kell a hozzáférési hibákat és a fájlok hiányát.

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

Virtuális dokumentumok kezelése

A DocumentProvider visszaadhat virtuális fájlokat — olyan dokumentumokat, amelyek nem léteznek különálló fájlként a lemezen. Például egy adatbázisbeli jegyzet virtuális PDF-ként jeleníthető meg. Ehhez a MIME-típust a FLAG_VIRTUAL_DOCUMENT jelzővel használják, és az openDocument átalakítja az adatokat a kért formátumba a küldés előtt.

DocumentProvider iOS-ben: UIDocumentPickerViewController

iOS hasonló mechanizmussal rendelkezik — UIDocumentPickerViewController, amely szintén egységes fájlkiválasztási felületet biztosít. Az iOS-ben azonban a dokumentumszolgáltató a UIDocumentPickerDelegate és az alkalmazáskiterjesztések (App Extensions) segítségével valósul meg Document Provider típussal.

Az Android DocumentsProvider-rel ellentétben az iOS UIDocumentPickerViewController nem igényel egyéni szolgáltató létrehozását helyi fájlokhoz — a rendszerválasztó alapértelmezés szerint támogatja az iCloud Drive-ot és a helyi tárhelyet. A harmadik féltől származó felhőszolgáltatások a Document Provider extension segítségével regisztrálnak az Info.plist NSExtensionFileProviderDocumentInterface kulccsal.

A fő különbség: Androidban a DocumentProvider aktívan meghívásra kerül a SAF Intent-en keresztül, és magának kell megvalósítania a navigációt. iOS-ben az UIDocumentPickerViewController a beépített rendszerfájl-böngészőt használja, és a szolgáltató kiterjesztése csak a tartalom igény szerinti biztosításáért felelős.