DocumentProvider — co to je, vytvoření poskytovatele a práce se soubory

Co je DocumentProvider?

DocumentsProvider — je základní třída Androidu dědící ContentProvider, která umožňuje aplikaci poskytovat své soubory jiným aplikacím prostřednictvím systémového rozhraní SAF. Poskytovatel vytváří virtuální souborový systém, který uživatel vidí v dialogu výběru dokumentů.

Každý poskytovatel organizuje soubory do kořenů (roots) — vstupních bodů nejvyšší úrovně. Například Google Drive má kořeny „Můj disk" a „Sdíleno se mnou". Uvnitř kořene poskytovatel vrací strom dokumentů, kde každý dokument je soubor nebo adresář s určitým typem MIME, velikostí a daty.

DocumentProvider je součástí balíčku android.provider a je k dispozici od Androidu 4.4 (API 19). Poskytovatele používají cloudové služby, správci hesel, aplikace na poznámky a všechny programy, které ukládají soubory ve vlastním formátu.

Jak vytvořit vlastní DocumentProvider

Vytvoření vlastního DocumentProvider začíná děděním třídy DocumentsProvider a implementací čtyř povinných metod. Poskytovatel definuje strukturu souborů, která se zobrazuje v systémovém výběru SAF při výběru souborů.

První metoda — queryRoots, která vrací kurzor se sloupci Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY a Root.COLUMN_FLAGS. Každý kořen může podporovat příznaky: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH a FLAG_SUPPORTS_IS_CHILD.

Druhá povinná metoda — queryChildDocuments, která vrací podřízené dokumenty zadaného URI. Tato metoda je volána, když uživatel otevře adresář ve výběru. Každý dokument obsahuje sloupce: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE a COLUMN_LAST_MODIFIED.

Povinné metody DocumentsProvider

DocumentsProvider vyžaduje implementaci čtyř metod, které tvoří strukturu souborů pro výběr. Bez nich poskytovatel nebude fungovat — systémový dialog SAF nebude moci zobrazit soubory.

• queryRoots — vrací kořenové vstupní body do úložiště. Každý kořen je reprezentován řádkem v kurzoru s ID, názvem a ikonou.
• queryDocument — vrací jeden dokument podle jeho ID. Používá se k získání informací o konkrétním souboru.
• queryChildDocuments — vrací podřízené dokumenty pro zadané URI nadřazeného adresáře.
• openDocument — otevírá dokument podle ID a vrací ParcelFileDescriptor pro čtení nebo zápis.

Dodatečně lze implementovat createDocument pro vytváření nových souborů, deleteDocument pro mazání a renameDocument pro přejmenování. Tyto metody vyžadují příznak FLAG_SUPPORTS_CREATE v kořeni.

Registrace poskytovatele v AndroidManifest

DocumentProvider je registrován v AndroidManifest.xml jako běžný ContentProvider s dodatečným intent-filter a příznaky. Poskytovatel musí být chráněn před přímým přístupem pomocí permission — doporučuje se použít android:exported="true" s explicitní 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>

Příznak grantUriPermissions umožňuje SAF dočasně delegovat přístupová práva volající aplikaci. Atribut authorities musí být jedinečný — obvykle se používá název balíčku s příponou .documents. Doporučuje se také zadat meta-data s XML zdrojem pro konfiguraci kořenů.

Příklad kódu: implementace DocumentsProvider

Implementace DocumentsProvider vyžaduje vrácení ParcelFileDescriptor z metody openDocument. Pro místní soubory se používá ParcelFileDescriptor.open, pro cloudové soubory — ParcelFileDescriptor.open s Pipe pro streamový přenos. Kód musí zpracovávat chyby přístupu a neexistenci souborů.

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

Správa virtuálních dokumentů

DocumentProvider může vracet virtuální soubory — dokumenty, které neexistují jako samostatné soubory na disku. Například poznámka z databáze může být prezentována jako virtuální PDF. K tomu se používá typ MIME s příznakem FLAG_VIRTUAL_DOCUMENT a openDocument převede data do požadovaného formátu před odesláním.

DocumentProvider v iOS: UIDocumentPickerViewController

iOS má podobný mechanismus — UIDocumentPickerViewController, který také poskytuje jednotné rozhraní pro výběr souborů. V iOS je však poskytovatel dokumentů implementován prostřednictvím UIDocumentPickerDelegate a rozšíření aplikací (App Extensions) typu Document Provider.

Na rozdíl od Android DocumentsProvider, iOS UIDocumentPickerViewController nevyžaduje vytvoření vlastního poskytovatele pro místní soubory — systémový výběr ve výchozím nastavení podporuje iCloud Drive a místní úložiště. Cloudové služby třetích stran se registrují prostřednictvím Document Provider extension s klíčem Info.plist NSExtensionFileProviderDocumentInterface.

Hlavní rozdíl: v Androidu je DocumentProvider aktivně volán prostřednictvím SAF Intent a musí sám implementovat navigaci. V iOS používá UIDocumentPickerViewController vestavěný systémový prohlížeč souborů a rozšíření poskytovatele je odpovědné pouze za poskytování obsahu na vyžádání.