Storage Access Framework: Was es ist, wie es funktioniert und Dateizugriff in Android

Was ist Storage Access Framework?

Storage Access Framework ist ein Teil des Android SDK, der eine einheitliche Schnittstelle zum Auswählen und Erstellen von Dokumenten über einen Systemdialog bereitstellt. SAF abstrahiert den physischen Speicherort der Dateien: Die App weiß nicht, woher die Datei gelesen wird — von der lokalen Festplatte, Google Drive oder Dropbox.

Die SAF-Architektur umfasst drei Komponenten: die Client-App, die die Anfrage initiiert, den System-Picker — einen Standard-Dateiauswahldialog, und den DocumentProvider — einen Content-Provider, der den Zugriff auf Dateien eines bestimmten Speichers implementiert. Der Benutzer sieht eine einheitliche Oberfläche unabhängig von der Datenquelle.

SAF ist seit Android 4.4 (API 19) verfügbar. Ursprünglich unterstützte das Framework nur Dokumente, aber Android 5.0 fügte Unterstützung für Verzeichnisse über ACTION_OPEN_DOCUMENT_TREE hinzu. Seit Android 10 ist SAF die empfohlene Methode für den Zugriff auf Dateien außerhalb des app-spezifischen Speichers.

Wie SAF funktioniert: System-Picker und URI

SAF startet einen System-Dateiauswahldialog über einen Intent mit der Aktion ACTION_OPEN_DOCUMENT. Der Benutzer sieht eine Liste verfügbarer Quellen: Interner Speicher, Google Drive, Dropbox und andere registrierte Anbieter. Nach der Auswahl einer Datei gibt das System einen content URI mit temporären Zugriffsrechten zurück.

Der content URI hat das Format content://com.android.externalstorage.documents/document/primary/Download/file.pdf. Im Gegensatz zu einem file:// URI gibt der content URI den tatsächlichen Dateipfad nicht preis und funktioniert über DocumentProvider. Die App liest die Datei über ContentResolver.openInputStream mit dem erhaltenen URI.

Der System-Picker unterstützt automatisch Suche, Sortierung und Filterung von Dateien nach MIME-Typen. Der Entwickler gibt die benötigten Typen über Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")) an, und der Picker zeigt nur relevante Dateien an.

Lebenszyklus des URI-Zugriffs

Standardmäßig ist der URI bis zum Neustart der App oder des Geräts gültig. Für den langfristigen Zugriff fordert die App takePersistableUriPermission an — dies ermöglicht das Lesen der Datei bei späteren Starts ohne erneute Auswahl über den Dialog.

ACTION_OPEN_DOCUMENT und ACTION_CREATE_DOCUMENT

SAF bietet drei Hauptaktionen für die Arbeit mit Dateien: Öffnen, Erstellen und Auswählen eines Ordnerbaums. ACTION_OPEN_DOCUMENT öffnet den System-Picker zur Auswahl einer vorhandenen Datei. ACTION_CREATE_DOCUMENT erstellt eine neue Datei — der Benutzer gibt einen Namen im Dialog ein, und die App erhält einen URI zum Schreiben.

ACTION_OPEN_DOCUMENT_TREE ermöglicht die Auswahl eines gesamten Verzeichnisses und den Zugriff auf alle darin enthaltenen Dateien. Dies wird in Dateimanagern, Backup-Apps und Synchronisationstools verwendet. Die App erhält einen Verzeichnis-URI und kann den Inhalt rekursiv über DocumentFile auflisten.

Für jede Aktion werden die MIME-Typen über EXTRA_MIME_TYPES angegeben. Es können mehrere Typen angegeben werden: "application/pdf", "image/*", "text/plain". Wenn keine Typen angegeben sind, zeigt der Picker alle Dateien an.

Persistent URI permissions

Persistent URI permissions ist ein SAF-Mechanismus, der den Zugriff auf eine Datei nach dem Ende der aktuellen Sitzung ermöglicht. Ohne dieses Flag ist der URI nur bis zum Neustart der App gültig. Die App fordert das Flag FLAG_GRANT_PERSISTABLE_URI_PERMISSION zusammen mit den Flags READ und WRITE an.

Zum Speichern der Berechtigungen wird die Methode ContentResolver.takePersistableUriPermission verwendet. Das System speichert den URI in einem speziellen Register und stellt den Zugriff beim nächsten App-Start wieder her. Um zu überprüfen, ob die App persistenten Zugriff auf einen URI hat, wird ContentResolver.persistedUriPermissions verwendet.

Der Benutzer kann gespeicherte Berechtigungen über Einstellungen → Apps → Berechtigungen widerrufen. Die App sollte das Szenario behandeln, in dem der Zugriff auf eine Datei unerwartet verloren geht. Es wird empfohlen, den Zugriff vor Arbeitsbeginn über ContentResolver.openInputStream zu überprüfen und SecurityException korrekt zu behandeln.

Codebeispiele: Dateiauswahl über SAF

SAF wird über einen standardmäßigen Intent gestartet. Der Code ist minimal: Erstellen Sie einen Intent mit ACTION_OPEN_DOCUMENT, geben Sie die MIME-Typen an und starten Sie ihn über ActivityResultContracts.StartActivityForResult. Nach der Auswahl einer Datei erhält der Callback den URI in data.data, der dann zum Lesen verwendet wird.

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)

Dateierstellung über ACTION_CREATE_DOCUMENT

Verwenden Sie zum Schreiben einer neuen Datei ACTION_CREATE_DOCUMENT. Der Intent akzeptiert den MIME-Typ und den Dateinamen über EXTRA_TITLE. Nach der Auswahl eines Ordners und der Bestätigung gibt der Benutzer einen URI zurück, in den die App Daten über ContentResolver.openOutputStream schreibt. Das System erstellt die Datei automatisch am gewählten Speicherort.

SAF vs READ_EXTERNAL_STORAGE

SAF unterscheidet sich vom traditionellen READ_EXTERNAL_STORAGE durch einen grundlegend anderen Ansatz zur Sicherheit. Anstatt auf einmal Zugriff auf den gesamten Speicher anzufordern, fordert SAF nur Zugriff auf eine bestimmte Datei an. Dies minimiert die Angriffsfläche und erhöht das Vertrauen des Benutzers.

READ_EXTERNAL_STORAGE gewährt Zugriff auf alle Dateien auf dem Gerät, einschließlich Fotos und Dokumente anderer Apps. Auf Android 10+ ist dieser Ansatz eingeschränkt. SAF hingegen gewährt nur Zugriff auf die vom Benutzer ausgewählte Datei und erfordert eine explizite Bestätigung für jede Datei. Für Batch-Medienoperationen verwenden Sie MediaStore, für einzelne Dokumente verwenden Sie SAF.

Der Hauptnachteil von SAF ist die Notwendigkeit, jede Datei einzeln auszuwählen. Für Massenoperationen (Backup, Ordnersynchronisation) wird ACTION_OPEN_DOCUMENT_TREE verwendet, der Zugriff auf alle Dateien im ausgewählten Verzeichnis gewährt. Die Lösung hängt vom Szenario ab: SAF ist optimal für die Benutzerauswahl, MediaStore für den programmgesteuerten Medienzugriff.