Storage Access Framework: ce este, principii de funcționare și acces la fișiere

Ce este Storage Access Framework?

Storage Access Framework — este o parte a Android SDK care oferă o interfață unificată pentru selectarea și crearea documentelor prin dialogul sistem. SAF abstractizează locația fizică a fișierelor: aplicația nu știe de unde se citește fișierul — de pe discul local, Google Drive sau Dropbox.

Arhitectura SAF include trei componente: aplicația client care inițiază cererea, selectorul sistem — dialogul standard de selectare a fișierului, și DocumentProvider — furnizorul de conținut care implementează accesul la fișierele unui anumit depozit. Utilizatorul vede o interfață unificată indiferent de sursa datelor.

SAF este disponibil începând cu Android 4.4 (API 19). Inițial framework-ul suporta doar documente, dar în Android 5.0 a fost adăugat suportul pentru directoare prin ACTION_OPEN_DOCUMENT_TREE. Din Android 10, SAF a devenit modul recomandat de acces la orice fișier din afara app-specific storage.

Cum funcționează SAF: selectorul sistem și URI

SAF lansează dialogul sistem de selectare a fișierului prin Intent cu acțiunea ACTION_OPEN_DOCUMENT. Utilizatorul vede o listă de surse disponibile: memoria internă, Google Drive, Dropbox și alți furnizori înregistrați. După selectarea fișierului, sistemul returnează un content URI cu drepturi temporare de acces.

Content URI are formatul content://com.android.externalstorage.documents/document/primary/Download/file.pdf. Spre deosebire de URI-ul file://, content URI nu dezvăluie calea reală a fișierului și funcționează prin DocumentProvider. Aplicația citește fișierul prin ContentResolver.openInputStream pe baza URI-ului primit.

Selectorul sistem suportă automat căutarea, sortarea și filtrarea fișierelor după tipurile MIME. Dezvoltatorul specifică tipurile necesare prin Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), iar selectorul afișează doar fișierele relevante.

Ciclul de viață al URI-ului de acces

Implicit, URI-ul este valabil până la repornirea aplicației sau repornirea dispozitivului. Pentru acces pe termen lung, aplicația solicită takePersistableUriPermission — aceasta permite citirea fișierului la pornirile ulterioare fără reselectarea prin dialog.

ACTION_OPEN_DOCUMENT și ACTION_CREATE_DOCUMENT

SAF oferă trei acțiuni principale pentru lucrul cu fișiere: deschidere, creare și selectare a arborelui de dosare. ACTION_OPEN_DOCUMENT deschide selectorul sistem pentru selectarea unui fișier existent. ACTION_CREATE_DOCUMENT creează un fișier nou — utilizatorul introduce numele în dialog, iar aplicația primește URI-ul pentru scriere.

ACTION_OPEN_DOCUMENT_TREE permite selectarea unui director întreg și accesul la toate fișierele din acesta. Este utilizat în managerii de fișiere, aplicațiile de backup și sincronizare. Aplicația primește URI-ul directorului și poate enumera recursiv conținutul prin DocumentFile.

Pentru fiecare acțiune, tipurile MIME se specifică prin EXTRA_MIME_TYPES. Se pot specifica mai multe tipuri: "application/pdf", "image/*", "text/plain". Dacă tipurile nu sunt specificate, selectorul afișează toate fișierele.

Persistent URI permissions

Persistent URI permissions — mecanism SAF care permite păstrarea accesului la fișier după încheierea sesiunii curente. Fără acest indicator, URI-ul este valabil doar până la repornirea aplicației. Aplicația solicită indicatorul FLAG_GRANT_PERSISTABLE_URI_PERMISSION împreună cu indicatorii READ și WRITE.

Pentru păstrarea permisiunilor se utilizează metoda ContentResolver.takePersistableUriPermission. Sistemul stochează URI-ul într-un registru special și restabilește accesul la următoarea pornire a aplicației. Pentru a verifica dacă aplicația are acces persistent la URI, se utilizează ContentResolver.persistedUriPermissions.

Utilizatorul poate revoca permisiunile salvate prin Setări → Aplicații → Permisiuni. Aplicația trebuie să gestioneze scenariul în care accesul la fișier dispare brusc. Se recomandă verificarea accesului prin ContentResolver.openInputStream înainte de începerea lucrului și gestionarea corectă a SecurityException.

Exemple de cod: selectarea fișierului prin SAF

SAF se lansează prin Intent standard. Codul este minim: creați un Intent cu ACTION_OPEN_DOCUMENT, specificați tipurile MIME și lansați prin ActivityResultContracts.StartActivityForResult. După selectarea fișierului, callback-ul primește URI-ul în data.data, care apoi este utilizat pentru citire.

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)

Crearea fișierului prin ACTION_CREATE_DOCUMENT

Pentru scrierea unui fișier nou, utilizați ACTION_CREATE_DOCUMENT. Intent primește tipul MIME și numele fișierului prin EXTRA_TITLE. După selectarea dosarului și confirmare, utilizatorul returnează URI-ul în care aplicația scrie datele prin ContentResolver.openOutputStream. Sistemul creează automat fișierul în locația selectată.

SAF vs READ_EXTERNAL_STORAGE

SAF se deosebește de READ_EXTERNAL_STORAGE tradițional printr-o abordare fundamental diferită a securității. În loc să solicite acces la întreaga memorie "dintr-o dată", SAF solicită acces doar la un anumit fișier. Aceasta minimizează suprafața de atac și sporește încrederea utilizatorului.

READ_EXTERNAL_STORAGE oferă acces la toate fișierele de pe dispozitiv, inclusiv fotografii și documente ale altor aplicații. Pe Android 10+ această abordare este limitată. SAF, dimpotrivă, oferă acces doar la fișierul selectat de utilizator și necesită confirmare explicită pentru fiecare fișier. Pentru lucrul în lot cu media, utilizați MediaStore, pentru documente individuale — SAF.

Principalul dezavantaj al SAF este necesitatea selectării fiecărui fișier separat. Pentru operații în masă (backup, sincronizare dosare) se utilizează ACTION_OPEN_DOCUMENT_TREE, care oferă acces la toate fișierele din directorul selectat. Soluția depinde de scenariu: SAF este optim pentru selectarea de către utilizator, MediaStore — pentru accesul programatic la media.