Storage Access Framework: co to je, principy fungování a přístup k souborům

Co je Storage Access Framework?

Storage Access Framework — je součástí Android SDK, která poskytuje jednotné rozhraní pro výběr a vytváření dokumentů prostřednictvím systémového dialogu. SAF abstrahuje fyzické umístění souborů: aplikace neví, odkud se soubor čte — z lokálního disku, Google Drive nebo Dropboxu.

Architektura SAF zahrnuje tři komponenty: klientskou aplikaci, která iniciuje požadavek, systémový výběr — standardní dialog výběru souboru, a DocumentProvider — poskytovatele obsahu, který implementuje přístup k souborům konkrétního úložiště. Uživatel vidí jednotné rozhraní bez ohledu na zdroj dat.

SAF je k dispozici od Android 4.4 (API 19). Zpočátku framework podporoval pouze dokumenty, ale v Android 5.0 byla přidána podpora adresářů prostřednictvím ACTION_OPEN_DOCUMENT_TREE. Od Android 10 se SAF stal doporučeným způsobem přístupu k jakémukoli souboru mimo app-specific storage.

Jak SAF funguje: systémový výběr a URI

SAF spouští systémový dialog výběru souboru prostřednictvím Intent s akcí ACTION_OPEN_DOCUMENT. Uživatel vidí seznam dostupných zdrojů: interní úložiště, Google Drive, Dropbox a další registrované poskytovatele. Po výběru souboru systém vrátí content URI s dočasnými přístupovými právy.

Content URI má formát content://com.android.externalstorage.documents/document/primary/Download/file.pdf. Na rozdíl od file:// URI, content URI neodhaluje skutečnou cestu k souboru a funguje prostřednictvím DocumentProvider. Aplikace čte soubor pomocí ContentResolver.openInputStream na základě získaného URI.

Systémový výběr automaticky podporuje vyhledávání, řazení a filtrování souborů podle typů MIME. Vývojář zadá požadované typy pomocí Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), a výběr zobrazí pouze relevantní soubory.

Životní cyklus URI přístupu

Ve výchozím nastavení je URI platný do restartu aplikace nebo restartu zařízení. Pro dlouhodobý přístup aplikace požádá o takePersistableUriPermission — to umožňuje číst soubor při následujících spuštěních bez opětovného výběru prostřednictvím dialogu.

ACTION_OPEN_DOCUMENT a ACTION_CREATE_DOCUMENT

SAF poskytuje tři hlavní akce pro práci se soubory: otevření, vytvoření a výběr stromu složek. ACTION_OPEN_DOCUMENT otevře systémový výběr pro výběr existujícího souboru. ACTION_CREATE_DOCUMENT vytvoří nový soubor — uživatel zadá název v dialogu a aplikace obdrží URI pro zápis.

ACTION_OPEN_DOCUMENT_TREE umožňuje vybrat celý adresář a získat přístup ke všem souborům v něm. Používá se ve správcích souborů, zálohovacích a synchronizačních aplikacích. Aplikace obdrží URI adresáře a může rekurzivně procházet obsah prostřednictvím DocumentFile.

Pro každou akci jsou typy MIME zadány prostřednictvím EXTRA_MIME_TYPES. Lze zadat více typů: "application/pdf", "image/*", "text/plain". Pokud typy nejsou zadány, výběr zobrazí všechny soubory.

Persistent URI permissions

Persistent URI permissions — mechanismus SAF, který umožňuje zachovat přístup k souboru po skončení aktuální relace. Bez tohoto příznaku je URI platný pouze do restartu aplikace. Aplikace požádá o příznak FLAG_GRANT_PERSISTABLE_URI_PERMISSION spolu s příznaky READ a WRITE.

Pro zachování oprávnění se používá metoda ContentResolver.takePersistableUriPermission. Systém uloží URI do speciálního registru a obnoví přístup při příštím spuštění aplikace. Pro kontrolu, zda má aplikace trvalý přístup k URI, se používá ContentResolver.persistedUriPermissions.

Uživatel může odvolat uložená oprávnění prostřednictvím Nastavení → Aplikace → Oprávnění. Aplikace by měla zpracovávat scénář, kdy přístup k souboru neočekávaně zmizí. Doporučuje se kontrolovat přístup pomocí ContentResolver.openInputStream před zahájením práce a správně zpracovávat SecurityException.

Příklady kódu: výběr souboru přes SAF

SAF se spouští prostřednictvím standardního Intent. Kód je minimální: vytvořte Intent s ACTION_OPEN_DOCUMENT, zadejte typy MIME a spusťte přes ActivityResultContracts.StartActivityForResult. Po výběru souboru callback obdrží URI v data.data, který se poté použije pro čtení.

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)

Vytvoření souboru pomocí ACTION_CREATE_DOCUMENT

Pro zápis nového souboru použijte ACTION_CREATE_DOCUMENT. Intent přijímá typ MIME a název souboru prostřednictvím EXTRA_TITLE. Po výběru složky a potvrzení uživatel vrátí URI, do kterého aplikace zapíše data prostřednictvím ContentResolver.openOutputStream. Systém automaticky vytvoří soubor ve vybraném umístění.

SAF vs READ_EXTERNAL_STORAGE

SAF se liší od tradičního READ_EXTERNAL_STORAGE zásadně odlišným přístupem k zabezpečení. Místo žádosti o přístup k celému úložišti "najednou" SAF žádá o přístup pouze ke konkrétnímu souboru. To minimalizuje útočnou plochu a zvyšuje důvěru uživatele.

READ_EXTERNAL_STORAGE poskytuje přístup ke všem souborům na zařízení, včetně fotografií a dokumentů jiných aplikací. Na Android 10+ je tento přístup omezen. SAF naproti tomu poskytuje přístup pouze k souboru vybranému uživatelem a vyžaduje výslovné potvrzení pro každý soubor. Pro dávkovou práci s médii použijte MediaStore, pro jednotlivé dokumenty — SAF.

Hlavní nevýhodou SAF je nutnost vybírat každý soubor zvlášť. Pro hromadné operace (zálohování, synchronizace složek) se používá ACTION_OPEN_DOCUMENT_TREE, který poskytuje přístup ke všem souborům ve vybraném adresáři. Řešení závisí na scénáři: SAF je optimální pro výběr uživatelem, MediaStore — pro programový přístup k médiím.