DocumentProvider — was ist das, Erstellung eines Anbieters und Arbeiten mit Dateien

Was ist DocumentProvider?

DocumentsProvider ist eine Android-Basisklasse, die ContentProvider erweitert und einer Anwendung ermöglicht, ihre Dateien über die SAF-Systemschnittstelle anderen Anwendungen bereitzustellen. Der Anbieter erstellt ein virtuelles Dateisystem, das der Benutzer im Dokumentenauswahldialog sieht.

Jeder Anbieter organisiert Dateien in Stammverzeichnissen (roots) — Einstiegspunkte der obersten Ebene. Beispielsweise hat Google Drive die Stammverzeichnisse „Mein Laufwerk“ und „Für mich freigegeben.“ Innerhalb eines Stammverzeichnisses gibt der Anbieter einen Dokumentenbaum zurück, wobei jedes Dokument eine Datei oder ein Verzeichnis mit einem bestimmten MIME-Typ, einer Größe und Daten ist.

DocumentProvider ist Teil des android.provider Pakets und ab Android 4.4 (API 19) verfügbar. Der Anbieter wird von Cloud-Diensten, Passwort-Managern, Notiz-Apps und allen Programmen verwendet, die Dateien in einem eigenen Format speichern.

Wie erstellt man einen benutzerdefinierten DocumentProvider

Das Erstellen eines eigenen DocumentProvider beginnt mit dem Erweitern der Klasse DocumentsProvider und der Implementierung von vier erforderlichen Methoden. Der Anbieter definiert die Dateistruktur, die bei der Dateiauswahl in der System-SAF-Auswahl erscheint.

Die erste Methode ist queryRoots, die einen Cursor mit den Spalten Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY und Root.COLUMN_FLAGS zurückgibt. Jeder Stamm kann Flags unterstützen: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH und FLAG_SUPPORTS_IS_CHILD.

Die zweite erforderliche Methode ist queryChildDocuments, die die untergeordneten Dokumente einer angegebenen URI zurückgibt. Diese Methode wird aufgerufen, wenn der Benutzer in der Auswahl ein Verzeichnis öffnet. Jedes Dokument enthält die Spalten: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE und COLUMN_LAST_MODIFIED.

Erforderliche Methoden von DocumentsProvider

DocumentsProvider erfordert die Implementierung von vier Methoden, die die Dateistruktur für die Auswahl bilden. Ohne sie funktioniert der Anbieter nicht — der System-SAF-Dialog kann keine Dateien anzeigen.

• queryRoots — gibt die Stammeinstiegspunkte zum Speicher zurück. Jeder Stamm wird durch eine Zeile im Cursor mit einer ID, einem Namen und einem Symbol dargestellt.
• queryDocument — gibt ein einzelnes Dokument anhand seiner ID zurück. Wird verwendet, um Informationen über eine bestimmte Datei zu erhalten.
• queryChildDocuments — gibt untergeordnete Dokumente für die angegebene URI des übergeordneten Verzeichnisses zurück.
• openDocument — öffnet ein Dokument anhand der ID und gibt einen ParcelFileDescriptor zum Lesen oder Schreiben zurück.

Zusätzlich können createDocument zum Erstellen neuer Dateien, deleteDocument zum Löschen und renameDocument zum Umbenennen implementiert werden. Diese Methoden erfordern das Flag FLAG_SUPPORTS_CREATE im Stammverzeichnis.

Registrierung des Anbieters in AndroidManifest

DocumentProvider wird in AndroidManifest.xml als normaler ContentProvider mit einem zusätzlichen Intent-Filter und Flags registriert. Der Anbieter muss vor direktem Zugriff durch Berechtigungen geschützt werden — es wird empfohlen, android:exported="true" mit expliziter Berechtigung zu verwenden.

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

Das Flag grantUriPermissions ermöglicht es SAF, der aufrufenden Anwendung temporär Zugriffsrechte zu delegieren. Das Attribut authorities muss eindeutig sein — normalerweise wird der Paketname mit dem Suffix .documents verwendet. Es wird auch empfohlen, Metadaten mit einer XML-Ressource zur Konfiguration der Stammverzeichnisse anzugeben.

Codebeispiel: Implementierung von DocumentsProvider

Die Implementierung von DocumentsProvider erfordert die Rückgabe eines ParcelFileDescriptor aus der openDocument-Methode. Für lokale Dateien wird ParcelFileDescriptor.open verwendet, für Cloud-Dateien — ParcelFileDescriptor.open mit Pipe für Streaming. Der Code muss Zugriffsfehler und fehlende Dateien behandeln.

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

Behandlung virtueller Dokumente

DocumentProvider kann virtuelle Dateien zurückgeben — Dokumente, die nicht als separate Dateien auf der Festplatte existieren. Beispielsweise kann eine Datenbanknotiz als virtuelles PDF dargestellt werden. Dazu wird ein MIME-Typ mit dem Flag FLAG_VIRTUAL_DOCUMENT verwendet, und openDocument konvertiert die Daten vor dem Senden in das angeforderte Format.

DocumentProvider in iOS: UIDocumentPickerViewController

iOS verfügt über einen ähnlichen Mechanismus — UIDocumentPickerViewController, der ebenfalls eine einheitliche Dateiauswahloberfläche bietet. Allerdings wird der Dokumentenanbieter in iOS über UIDocumentPickerDelegate und App-Erweiterungen (App Extensions) vom Typ Document Provider implementiert.

Im Gegensatz zum Android DocumentsProvider benötigt iOS UIDocumentPickerViewController keinen benutzerdefinierten Anbieter für lokale Dateien — die Systemauswahl unterstützt standardmäßig iCloud Drive und lokalen Speicher. Drittanbieter-Cloud-Dienste registrieren sich über eine Document Provider-Erweiterung mit dem Info.plist-Schlüssel NSExtensionFileProviderDocumentInterface.

Der Hauptunterschied: In Android wird DocumentProvider aktiv über einen SAF-Intent aufgerufen und muss die Navigation selbst implementieren. In iOS verwendet UIDocumentPickerViewController einen integrierten System-Dateibrowser, und der Erweiterungsanbieter ist nur für die Bereitstellung von Inhalten auf Anfrage verantwortlich.