Storage Access Framework: wat is het, werkingsprincipes en toegang tot bestanden

Wat is Storage Access Framework?

Storage Access Framework — is een onderdeel van de Android SDK dat een uniforme interface biedt voor het selecteren en maken van documenten via het systeemdialoogvenster. SAF abstraheert de fysieke locatie van bestanden: de app weet niet waar het bestand wordt gelezen — van de lokale schijf, Google Drive of Dropbox.

De architectuur van SAF omvat drie componenten: de client-app die het verzoek initieert, de systeemkiezer — het standaard dialoogvenster voor bestandsselectie, en DocumentProvider — een contentprovider die toegang tot bestanden van een specifieke opslag implementeert. De gebruiker ziet een uniforme interface, ongeacht de gegevensbron.

SAF is beschikbaar vanaf Android 4.4 (API 19). Aanvankelijk ondersteunde het framework alleen documenten, maar in Android 5.0 werd ondersteuning voor mappen toegevoegd via ACTION_OPEN_DOCUMENT_TREE. Vanaf Android 10 is SAF de aanbevolen manier geworden voor toegang tot elk bestand buiten de app-specific storage.

Hoe SAF werkt: systeemkiezer en URI

SAF start het systeemdialoogvenster voor bestandsselectie via een Intent met de actie ACTION_OPEN_DOCUMENT. De gebruiker ziet een lijst met beschikbare bronnen: intern geheugen, Google Drive, Dropbox en andere geregistreerde providers. Na het selecteren van het bestand retourneert het systeem een content URI met tijdelijke toegangsrechten.

Content URI heeft het formaat content://com.android.externalstorage.documents/document/primary/Download/file.pdf. In tegenstelling tot file:// URI, onthult content URI niet het werkelijke pad naar het bestand en werkt het via DocumentProvider. De app leest het bestand via ContentResolver.openInputStream op basis van de verkregen URI.

De systeemkiezer ondersteunt automatisch zoeken, sorteren en filteren van bestanden op MIME-typen. De ontwikkelaar geeft de benodigde typen op via Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), en de kiezer toont alleen relevante bestanden.

Levenscyclus van URI-toegang

Standaard is de URI geldig tot het herstarten van de app of het opnieuw opstarten van het apparaat. Voor langdurige toegang vraagt de app takePersistableUriPermission aan — dit maakt het mogelijk het bestand bij volgende starts te lezen zonder opnieuw te selecteren via het dialoogvenster.

ACTION_OPEN_DOCUMENT en ACTION_CREATE_DOCUMENT

SAF biedt drie hoofdacties voor het werken met bestanden: openen, maken en selecteren van een mappenboom. ACTION_OPEN_DOCUMENT opent de systeemkiezer voor het selecteren van een bestaand bestand. ACTION_CREATE_DOCUMENT maakt een nieuw bestand — de gebruiker voert de naam in het dialoogvenster in en de app ontvangt een URI om naar te schrijven.

ACTION_OPEN_DOCUMENT_TREE maakt het mogelijk een volledige map te selecteren en toegang te krijgen tot alle bestanden erin. Dit wordt gebruikt in bestandsbeheerders, back-up- en synchronisatie-apps. De app ontvangt de URI van de map en kan de inhoud recursief doorlopen via DocumentFile.

Voor elke actie worden MIME-typen opgegeven via EXTRA_MIME_TYPES. Er kunnen meerdere typen worden opgegeven: "application/pdf", "image/*", "text/plain". Als er geen typen worden opgegeven, toont de kiezer alle bestanden.

Persistent URI permissions

Persistent URI permissions — een SAF-mechanisme dat het mogelijk maakt de toegang tot een bestand te behouden na afloop van de huidige sessie. Zonder deze vlag is de URI alleen geldig tot het herstarten van de app. De app vraagt de vlag FLAG_GRANT_PERSISTABLE_URI_PERMISSION aan samen met de READ- en WRITE-vlaggen.

Voor het behouden van rechten wordt de methode ContentResolver.takePersistableUriPermission gebruikt. Het systeem bewaart de URI in een speciaal register en herstelt de toegang bij de volgende start van de app. Om te controleren of de app persistente toegang tot een URI heeft, wordt ContentResolver.persistedUriPermissions gebruikt.

De gebruiker kan opgeslagen machtigingen intrekken via Instellingen → Apps → Machtigingen. De app moet het scenario afhandelen waarin de toegang tot het bestand onverwacht verdwijnt. Het wordt aanbevolen de toegang te controleren via ContentResolver.openInputStream voordat u begint met werken en SecurityException correct af te handelen.

Codevoorbeelden: bestand selecteren via SAF

SAF wordt gestart via een standaard Intent. De code is minimaal: maak een Intent met ACTION_OPEN_DOCUMENT, geef MIME-typen op en start via ActivityResultContracts.StartActivityForResult. Na het selecteren van het bestand ontvangt de callback de URI in data.data, die vervolgens wordt gebruikt om te lezen.

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)

Bestand maken via ACTION_CREATE_DOCUMENT

Voor het schrijven van een nieuw bestand gebruikt u ACTION_CREATE_DOCUMENT. De Intent accepteert het MIME-type en de bestandsnaam via EXTRA_TITLE. Na het selecteren van een map en bevestiging retourneert de gebruiker een URI waar de app gegevens naartoe schrijft via ContentResolver.openOutputStream. Het systeem maakt automatisch het bestand aan op de geselecteerde locatie.

SAF vs READ_EXTERNAL_STORAGE

SAF verschilt van traditionele READ_EXTERNAL_STORAGE door een fundamenteel andere benadering van beveiliging. In plaats van toegang tot de hele opslag “in één keer” aan te vragen, vraagt SAF alleen toegang tot een specifiek bestand. Dit minimaliseert het aanvalsoppervlak en verhoogt het gebruikersvertrouwen.

READ_EXTERNAL_STORAGE geeft toegang tot alle bestanden op het apparaat, inclusief foto’s en documenten van andere apps. Op Android 10+ is deze benadering beperkt. SAF daarentegen biedt alleen toegang tot het door de gebruiker geselecteerde bestand en vereist expliciete bevestiging voor elk bestand. Gebruik MediaStore voor batchverwerking van media en SAF voor afzonderlijke documenten.

Het belangrijkste nadeel van SAF is dat elk bestand afzonderlijk moet worden geselecteerd. Voor bulkbewerkingen (back-ups, mapsynchronisatie) wordt ACTION_OPEN_DOCUMENT_TREE gebruikt, dat toegang geeft tot alle bestanden in de geselecteerde map. De oplossing hangt af van het scenario: SAF is optimaal voor gebruikersselectie, MediaStore voor programmatische toegang tot media.