DocumentProvider — wat is het, een provider maken en werken met bestanden

Wat is DocumentProvider?

DocumentsProvider — is een basis-Android-klasse die ContentProvider erft en een app in staat stelt zijn bestanden aan andere apps aan te bieden via de SAF-systeeminterface. De provider creëert een virtueel bestandssysteem dat de gebruiker ziet in het dialoogvenster voor documentselectie.

Elke provider organiseert bestanden in wortels (roots) — toegangspunten op hoog niveau. Google Drive heeft bijvoorbeeld de wortels „Mijn schijf" en „Gedeeld met mij". Binnen een wortel retourneert de provider een documentenboom, waarbij elk document een bestand of map is met een specifiek MIME-type, grootte en datums.

DocumentProvider maakt deel uit van het android.provider-pakket en is beschikbaar vanaf Android 4.4 (API 19). De provider wordt gebruikt door clouddiensten, wachtwoordmanagers, notitie-apps en alle programma's die bestanden in eigen formaat opslaan.

Een aangepaste DocumentProvider maken

Het maken van uw eigen DocumentProvider begint met het overerven van de klasse DocumentsProvider en het implementeren van vier verplichte methoden. De provider bepaalt de bestandsstructuur die wordt weergegeven in de SAF-systeemkiezer bij het selecteren van bestanden.

De eerste methode — queryRoots, die een cursor retourneert met de kolommen Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY en Root.COLUMN_FLAGS. Elke wortel kan vlaggen ondersteunen: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH en FLAG_SUPPORTS_IS_CHILD.

De tweede verplichte methode — queryChildDocuments, die onderliggende documenten van de opgegeven URI retourneert. Deze methode wordt aangeroepen wanneer de gebruiker een map opent in de kiezer. Elk document bevat de kolommen: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE en COLUMN_LAST_MODIFIED.

Verplichte methoden van DocumentsProvider

DocumentsProvider vereist implementatie van vier methoden die de bestandsstructuur voor de kiezer vormen. Zonder hen werkt de provider niet — het SAF-systeemdialoogvenster kan geen bestanden weergeven.

• queryRoots — retourneert de worteltoegangspunten tot de opslag. Elke wortel wordt vertegenwoordigd door een rij in de cursor met ID, naam en pictogram.
• queryDocument — retourneert één document op basis van zijn ID. Wordt gebruikt om informatie over een specifiek bestand te krijgen.
• queryChildDocuments — retourneert onderliggende documenten voor de opgegeven bovenliggende map-URI.
• openDocument — opent het document op ID en retourneert ParcelFileDescriptor voor lezen of schrijven.

Daarnaast kunnen createDocument voor het maken van nieuwe bestanden, deleteDocument voor verwijderen en renameDocument voor hernoemen worden geïmplementeerd. Deze methoden vereisen de vlag FLAG_SUPPORTS_CREATE in de wortel.

De provider registreren in AndroidManifest

DocumentProvider wordt geregistreerd in AndroidManifest.xml als een gewone ContentProvider met extra intent-filter en vlaggen. De provider moet worden beschermd tegen directe toegang via permission — het wordt aanbevolen android:exported="true" te gebruiken met expliciete 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>

De vlag grantUriPermissions stelt SAF in staat tijdelijk toegangsrechten te delegeren aan de aanroepende app. Het attribuut authorities moet uniek zijn — meestal wordt de pakketnaam met het achtervoegsel .documents gebruikt. Het wordt ook aanbevolen om meta-data met een XML-bron op te geven voor het configureren van wortels.

Codevoorbeeld: DocumentsProvider implementeren

Implementatie van DocumentsProvider vereist het retourneren van ParcelFileDescriptor uit de methode openDocument. Voor lokale bestanden wordt ParcelFileDescriptor.open gebruikt, voor cloudbestanden — ParcelFileDescriptor.open met Pipe voor streaming. De code moet toegangsfouten en het ontbreken van bestanden afhandelen.

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

Virtuele documenten beheren

DocumentProvider kan virtuele bestanden retourneren — documenten die niet als afzonderlijke bestanden op schijf bestaan. Een notitie uit de database kan bijvoorbeeld worden gepresenteerd als een virtuele PDF. Hiervoor wordt het MIME-type met de vlag FLAG_VIRTUAL_DOCUMENT gebruikt, en openDocument converteert de gegevens naar het gevraagde formaat voordat het wordt verzonden.

DocumentProvider in iOS: UIDocumentPickerViewController

iOS heeft een vergelijkbaar mechanisme — UIDocumentPickerViewController, dat ook een uniforme bestandsselectie-interface biedt. In iOS wordt de documentprovider echter geïmplementeerd via UIDocumentPickerDelegate en app-extensies (App Extensions) van het type Document Provider.

In tegenstelling tot Android DocumentsProvider vereist iOS UIDocumentPickerViewController geen aangepaste provider voor lokale bestanden — de systeemkiezer ondersteunt standaard iCloud Drive en lokale opslag. Clouddiensten van derden registreren zich via Document Provider extension met de Info.plist-sleutel NSExtensionFileProviderDocumentInterface.

Het belangrijkste verschil: in Android wordt DocumentProvider actief aangeroepen via SAF Intent en moet het zelf navigatie implementeren. In iOS gebruikt UIDocumentPickerViewController de ingebouwde systeembestandsbrowser en is de providerextensie alleen verantwoordelijk voor het leveren van inhoud op verzoek.