DocumentProvider — vad är det, skapa leverantör och arbeta med filer

Vad är DocumentProvider?

DocumentsProvider — är en grundläggande Android-klass som ärver ContentProvider och gör det möjligt för en app att tillhandahålla sina filer till andra appar via SAF-systemgränssnittet. Leverantören skapar ett virtuellt filsystem som användaren ser i dialogrutan för dokumentval.

Varje leverantör organiserar filer i rötter (roots) — startpunkter på högsta nivå. Till exempel har Google Drive rötterna “Min disk” och “Delat med mig”. Inuti roten returnerar leverantören ett dokumentträd, där varje dokument är en fil eller katalog med en specifik MIME-typ, storlek och datum.

DocumentProvider är en del av paketet android.provider och är tillgängligt från och med Android 4.4 (API 19). Leverantören används av molntjänster, lösenordshanterare, anteckningsappar och alla program som lagrar filer i eget format.

Skapa en anpassad DocumentProvider

Att skapa din egen DocumentProvider börjar med att ärva klassen DocumentsProvider och implementera fyra obligatoriska metoder. Leverantören bestämmer filstrukturen som visas i SAF-systemväljaren när du väljer filer.

Den första metoden — queryRoots, som returnerar en cursor med kolumnerna Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY och Root.COLUMN_FLAGS. Varje rot kan stödja flaggorna: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH och FLAG_SUPPORTS_IS_CHILD.

Den andra obligatoriska metoden — queryChildDocuments, som returnerar underordnade dokument för den angivna URI:n. Denna metod anropas när användaren öppnar en katalog i väljaren. Varje dokument innehåller kolumnerna: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE och COLUMN_LAST_MODIFIED.

Obligatoriska metoder i DocumentsProvider

DocumentsProvider kräver implementering av fyra metoder som bildar filstrukturen för väljaren. Utan dem kommer leverantören inte att fungera — SAF-systemdialogrutan kommer inte att kunna visa filer.

• queryRoots — returnerar rotstartpunkterna till lagringsplatsen. Varje rot representeras av en rad i cursorn med ID, namn och ikon.
• queryDocument — returnerar ett dokument baserat på dess ID. Används för att få information om en specifik fil.
• queryChildDocuments — returnerar underordnade dokument för den angivna URI:n för den överordnade katalogen.
• openDocument — öppnar dokumentet baserat på ID och returnerar ParcelFileDescriptor för läsning eller skrivning.

Dessutom kan createDocument för att skapa nya filer, deleteDocument för borttagning och renameDocument för omdöpning implementeras. Dessa metoder kräver flaggan FLAG_SUPPORTS_CREATE i roten.

Registrera leverantören i AndroidManifest

DocumentProvider registreras i AndroidManifest.xml som en vanlig ContentProvider med extra intent-filter och flaggor. Leverantören måste skyddas från direkt åtkomst via permission — det rekommenderas att använda android:exported="true" med explicit 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>

Flaggan grantUriPermissions gör det möjligt för SAF att tillfälligt delegera åtkomsträttigheter till den anropande appen. Attributet authorities måste vara unikt — vanligtvis används paketnamnet med suffixet .documents. Det rekommenderas också att ange meta-data med en XML-resurs för att konfigurera rötter.

Kodexempel: implementera DocumentsProvider

Implementering av DocumentsProvider kräver att ParcelFileDescriptor returneras från metoden openDocument. För lokala filer används ParcelFileDescriptor.open, för molnfiler — ParcelFileDescriptor.open med Pipe för strömmande överföring. Koden måste hantera åtkomstfel och att filer saknas.

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

Hantera virtuella dokument

DocumentProvider kan returnera virtuella filer — dokument som inte finns som separata filer på disken. Till exempel kan en anteckning från databasen presenteras som en virtuell PDF. För detta används MIME-typen med flaggan FLAG_VIRTUAL_DOCUMENT och openDocument konverterar data till det begärda formatet innan det skickas.

DocumentProvider i iOS: UIDocumentPickerViewController

iOS har en liknande mekanism — UIDocumentPickerViewController, som också ger ett enhetligt gränssnitt för filval. I iOS implementeras dock dokumentleverantören via UIDocumentPickerDelegate och apptillägg (App Extensions) av typen Document Provider.

Till skillnad från Android DocumentsProvider kräver iOS UIDocumentPickerViewController ingen anpassad leverantör för lokala filer — systemväljaren stöder iCloud Drive och lokal lagring som standard. Molntjänster från tredje part registreras via Document Provider extension med Info.plist-nyckeln NSExtensionFileProviderDocumentInterface.

Huvudskillnaden: i Android anropas DocumentProvider aktivt via SAF Intent och måste själv implementera navigering. I iOS använder UIDocumentPickerViewController den inbyggda systemfilbläddraren och leverantörstillägget ansvarar endast för att tillhandahålla innehåll på begäran.