DocumentProvider — qu'est-ce que c'est, création d'un fournisseur et travail avec les fichiers

Qu'est-ce que DocumentProvider ?

DocumentsProvider est une classe de base Android qui étend ContentProvider, permettant à une application de fournir ses fichiers à d'autres applications via l'interface SAF du système. Le fournisseur crée un système de fichiers virtuel que l'utilisateur voit dans la boîte de dialogue de sélection de documents.

Chaque fournisseur organise les fichiers en racines (roots) — points d'entrée de haut niveau. Par exemple, Google Drive a les racines «Mon Drive» et «Partagé avec moi.» Dans une racine, le fournisseur retourne une arborescence de documents, où chaque document est un fichier ou un répertoire avec un type MIME, une taille et des dates spécifiques.

DocumentProvider fait partie du package android.provider et est disponible depuis Android 4.4 (API 19). Le fournisseur est utilisé par les services cloud, les gestionnaires de mots de passe, les applications de notes et tout programme stockant des fichiers dans son propre format.

Comment créer un DocumentProvider personnalisé

Créer votre propre DocumentProvider commence par étendre la classe DocumentsProvider et implémenter quatre méthodes obligatoires. Le fournisseur définit la structure de fichiers qui apparaît dans le sélecteur SAF du système lors de la sélection de fichiers.

La première méthode est queryRoots, qui retourne un curseur avec les colonnes Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY et Root.COLUMN_FLAGS. Chaque racine peut prendre en charge des indicateurs : FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH et FLAG_SUPPORTS_IS_CHILD.

La deuxième méthode obligatoire est queryChildDocuments, qui retourne les documents enfants d'une URI spécifiée. Cette méthode est appelée lorsque l'utilisateur ouvre un répertoire dans le sélecteur. Chaque document contient les colonnes : Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE et COLUMN_LAST_MODIFIED.

Méthodes obligatoires de DocumentsProvider

DocumentsProvider nécessite l'implémentation de quatre méthodes qui forment la structure de fichiers pour le sélecteur. Sans elles, le fournisseur ne fonctionnera pas — la boîte de dialogue SAF du système ne pourra pas afficher les fichiers.

• queryRoots — retourne les points d'entrée racine vers le stockage. Chaque racine est représentée par une ligne dans le curseur avec un ID, un nom et une icône.
• queryDocument — retourne un seul document par son ID. Utilisé pour obtenir des informations sur un fichier spécifique.
• queryChildDocuments — retourne les documents enfants pour l'URI du répertoire parent spécifié.
• openDocument — ouvre un document par ID et retourne un ParcelFileDescriptor pour la lecture ou l'écriture.

En complément, on peut implémenter createDocument pour créer de nouveaux fichiers, deleteDocument pour supprimer et renameDocument pour renommer. Ces méthodes nécessent l'indicateur FLAG_SUPPORTS_CREATE dans la racine.

Enregistrement du fournisseur dans AndroidManifest

DocumentProvider est enregistré dans AndroidManifest.xml comme un ContentProvider normal avec un filtre d'intent et des indicateurs supplémentaires. Le fournisseur doit être protégé contre l'accès direct via une permission — il est recommandé d'utiliser android:exported="true" avec une permission explicite.

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

L'indicateur grantUriPermissions permet à SAF de déléguer temporairement les droits d'accès à l'application appelante. L'attribut authorities doit être unique — généralement, le nom du package avec le suffixe .documents est utilisé. Il est également recommandé de spécifier des métadonnées avec une ressource XML pour configurer les racines.

Exemple de code : implémentation de DocumentsProvider

Implémenter DocumentsProvider nécessite de retourner un ParcelFileDescriptor depuis la méthode openDocument. Pour les fichiers locaux, on utilise ParcelFileDescriptor.open, pour les fichiers cloud — ParcelFileDescriptor.open avec Pipe pour le streaming. Le code doit gérer les erreurs d'accès et les fichiers manquants.

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

Gestion des documents virtuels

DocumentProvider peut retourner des fichiers virtuels — des documents qui n'existent pas en tant que fichiers séparés sur le disque. Par exemple, une note de base de données peut être présentée comme un PDF virtuel. Cela utilise un type MIME avec l'indicateur FLAG_VIRTUAL_DOCUMENT, et openDocument convertit les données dans le format demandé avant l'envoi.

DocumentProvider dans iOS : UIDocumentPickerViewController

iOS dispose d'un mécanisme similaire — UIDocumentPickerViewController, qui fournit également une interface unifiée de sélection de fichiers. Cependant, dans iOS, le fournisseur de documents est implémenté via UIDocumentPickerDelegate et les extensions d'application (App Extensions) de type Document Provider.

Contrairement à Android DocumentsProvider, iOS UIDocumentPickerViewController ne nécessite pas la création d'un fournisseur personnalisé pour les fichiers locaux — le sélecteur système prend en charge iCloud Drive et le stockage local par défaut. Les services cloud tiers s'enregistrent via une extension Document Provider avec la clé Info.plist NSExtensionFileProviderDocumentInterface.

La principale différence : dans Android, DocumentProvider est appelé activement via un Intent SAF et doit implémenter lui-même la navigation. Dans iOS, UIDocumentPickerViewController utilise un navigateur de fichiers système intégré, et le fournisseur d'extension est uniquement responsable de la fourniture de contenu sur demande.