Storage Access Framework : définition, fonctionnement et accès aux fichiers dans Android

Qu'est-ce que Storage Access Framework ?

Storage Access Framework est une partie du SDK Android qui fournit une interface unifiée pour sélectionner et créer des documents via une boîte de dialogue système. SAF abstrait l'emplacement physique des fichiers : l'application ne sait pas d'où le fichier est lu — disque local, Google Drive ou Dropbox.

L'architecture SAF comprend trois composants : l'application cliente qui initie la requête, le sélecteur système — une boîte de dialogue standard de sélection de fichiers, et le DocumentProvider — un fournisseur de contenu qui implémente l'accès aux fichiers d'un stockage spécifique. L'utilisateur voit une interface unifiée quelle que soit la source de données.

SAF est disponible depuis Android 4.4 (API 19). Initialement, le framework ne prenait en charge que les documents, mais Android 5.0 a ajouté la prise en charge des répertoires via ACTION_OPEN_DOCUMENT_TREE. Depuis Android 10, SAF est devenu la méthode recommandée pour accéder à tout fichier en dehors du stockage spécifique à l'application.

Comment SAF fonctionne : sélecteur système et URI

SAF lance une boîte de dialogue de sélection de fichiers système via un Intent avec l'action ACTION_OPEN_DOCUMENT. L'utilisateur voit une liste des sources disponibles : stockage interne, Google Drive, Dropbox et autres fournisseurs enregistrés. Après avoir sélectionné un fichier, le système retourne un content URI avec des droits d'accès temporaires.

Le content URI a le format content://com.android.externalstorage.documents/document/primary/Download/file.pdf. Contrairement à un URI file://, le content URI ne révèle pas le chemin réel du fichier et fonctionne via DocumentProvider. L'application lit le fichier via ContentResolver.openInputStream en utilisant l'URI obtenu.

Le sélecteur système prend automatiquement en charge la recherche, le tri et le filtrage des fichiers par types MIME. Le développeur spécifie les types nécessaires via Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), et le sélecteur n'affiche que les fichiers pertinents.

Cycle de vie de l'accès URI

Par défaut, l'URI est valide jusqu'au redémarrage de l'application ou du dispositif. Pour un accès à long terme, l'application demande takePersistableUriPermission — cela permet de lire le fichier lors des lancements ultérieurs sans avoir à le re-sélectionner via la boîte de dialogue.

ACTION_OPEN_DOCUMENT et ACTION_CREATE_DOCUMENT

SAF fournit trois actions principales pour travailler avec les fichiers : ouvrir, créer et sélectionner une arborescence de dossiers. ACTION_OPEN_DOCUMENT ouvre le sélecteur système pour choisir un fichier existant. ACTION_CREATE_DOCUMENT crée un nouveau fichier — l'utilisateur saisit un nom dans la boîte de dialogue, et l'application reçoit un URI pour l'écriture.

ACTION_OPEN_DOCUMENT_TREE permet de sélectionner un répertoire entier et d'obtenir l'accès à tous les fichiers qu'il contient. Cela est utilisé dans les gestionnaires de fichiers, les applications de sauvegarde et de synchronisation. L'application reçoit un URI de répertoire et peut énumérer récursivement le contenu via DocumentFile.

Pour chaque action, les types MIME sont spécifiés via EXTRA_MIME_TYPES. Plusieurs types peuvent être spécifiés : "application/pdf", "image/*", "text/plain". Si aucun type n'est spécifié, le sélecteur affiche tous les fichiers.

Persistent URI permissions

Persistent URI permissions est un mécanisme de SAF qui permet de conserver l'accès à un fichier après la fin de la session en cours. Sans cet indicateur, l'URI n'est valide que jusqu'au redémarrage de l'application. L'application demande l'indicateur FLAG_GRANT_PERSISTABLE_URI_PERMISSION avec les indicateurs READ et WRITE.

Pour sauvegarder les autorisations, la méthode ContentResolver.takePersistableUriPermission est utilisée. Le système sauvegarde l'URI dans un registre spécial et restaure l'accès au prochain démarrage de l'application. Pour vérifier si l'application a un accès persistant à un URI, on utilise ContentResolver.persistedUriPermissions.

L'utilisateur peut révoquer les autorisations sauvegardées via Paramètres → Applications → Autorisations. L'application doit gérer le scénario où l'accès à un fichier est perdu de manière inattendue. Il est recommandé de vérifier l'accès via ContentResolver.openInputStream avant de commencer le travail et de traiter correctement SecurityException.

Exemples de code : sélection de fichier via SAF

SAF est lancé via un Intent standard. Le code est minimal : créer un Intent avec ACTION_OPEN_DOCUMENT, spécifier les types MIME et le lancer via ActivityResultContracts.StartActivityForResult. Après avoir sélectionné un fichier, le callback reçoit l'URI dans data.data, qui est ensuite utilisé pour la lecture.

val pickFile = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    result.data?.data?.let { uri ->
        val inputStream = contentResolver?.openInputStream(uri)
        // read from inputStream
    }
}

val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
    addCategory(Intent.CATEGORY_OPENABLE)
    setType("application/pdf")
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
}
pickFile.launch(intent)

Création de fichier via ACTION_CREATE_DOCUMENT

Pour écrire un nouveau fichier, utilisez ACTION_CREATE_DOCUMENT. L'Intent accepte le type MIME et le nom du fichier via EXTRA_TITLE. Après avoir sélectionné un dossier et confirmé, l'utilisateur retourne un URI dans lequel l'application écrit des données via ContentResolver.openOutputStream. Le système crée automatiquement le fichier à l'emplacement choisi.

SAF vs READ_EXTERNAL_STORAGE

SAF diffère du traditionnel READ_EXTERNAL_STORAGE par une approche fondamentalement différente de la sécurité. Au lieu de demander l'accès à tout le stockage en une fois, SAF demande l'accès uniquement à un fichier spécifique. Cela minimise la surface d'attaque et augmente la confiance de l'utilisateur.

READ_EXTERNAL_STORAGE accorde l'accès à tous les fichiers sur l'appareil, y compris les photos et documents d'autres applications. Sur Android 10+, cette approche est restreinte. SAF, en revanche, fournit l'accès uniquement au fichier sélectionné par l'utilisateur et nécessite une confirmation explicite pour chaque fichier. Pour les opérations par lots sur les médias, utilisez MediaStore ; pour les documents individuels, utilisez SAF.

Le principal inconvénient de SAF est la nécessité de sélectionner chaque fichier individuellement. Pour les opérations en masse (sauvegarde, synchronisation de dossiers), on utilise ACTION_OPEN_DOCUMENT_TREE, qui accorde l'accès à tous les fichiers du répertoire sélectionné. La solution dépend du scénario : SAF est optimal pour la sélection par l'utilisateur, MediaStore pour l'accès programmatique aux médias.