Storage Access Framework: mi ez, működési elvek és hozzáférés fájlokhoz

Mi az a Storage Access Framework?

Storage Access Framework — az Android SDK része, amely egységes interfészt biztosít a dokumentumok kiválasztásához és létrehozásához a rendszer párbeszédpaneljén keresztül. A SAF elvonatkoztatja a fájlok fizikai helyét: az alkalmazás nem tudja, honnan olvassa a fájlt — a helyi lemezről, Google Drive-ról vagy Dropboxból.

A SAF architektúrája három összetevőből áll: a kliens alkalmazásból, amely elindítja a kérést, a rendszerválasztóból — a szabványos fájlkiválasztási párbeszédpanelből, és a DocumentProviderből — a tartalomszolgáltatóból, amely egy adott tároló fájljaihoz való hozzáférést valósítja meg. A felhasználó egységes interfészt lát, függetlenül az adatforrástól.

A SAF Android 4.4 (API 19) óta érhető el. Kezdetben a keretrendszer csak dokumentumokat támogatott, de az Android 5.0-ban hozzáadták a könyvtárak támogatását az ACTION_OPEN_DOCUMENT_TREE-n keresztül. Az Android 10-től kezdve a SAF az ajánlott módszer bármely fájl elérésére az app-specific storage-on kívül.

Hogyan működik a SAF: rendszerválasztó és URI

A SAF elindítja a rendszer fájlkiválasztási párbeszédpaneljét egy Intent segítségével, ACTION_OPEN_DOCUMENT művelettel. A felhasználó látja az elérhető források listáját: belső tároló, Google Drive, Dropbox és más regisztrált szolgáltatók. A fájl kiválasztása után a rendszer visszaad egy content URI-t ideiglenes hozzáférési jogosultságokkal.

A content URI formátuma content://com.android.externalstorage.documents/document/primary/Download/file.pdf. A file:// URI-val ellentétben a content URI nem fedi fel a fájl valódi útvonalát, és a DocumentProvideren keresztül működik. Az alkalmazás a ContentResolver.openInputStream segítségével olvassa a fájlt a kapott URI alapján.

A rendszerválasztó automatikusan támogatja a fájlok keresését, rendezését és szűrését MIME típusok szerint. A fejlesztő megadja a szükséges típusokat az Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")) segítségével, és a választó csak a releváns fájlokat jeleníti meg.

Az URI hozzáférés életciklusa

Alapértelmezésben az URI az alkalmazás újraindításáig vagy az eszköz és az újraindításáig érvényes. Hosszú távú hozzáféréshez az alkalmazás takePersistableUriPermission-t kér — ez lehetővé teszi a fájl olvasását a következő indításoknál anélkül, hogy újra ki kellene választani a párbeszédpanelen keresztül.

ACTION_OPEN_DOCUMENT és ACTION_CREATE_DOCUMENT

A SAF három fő műveletet biztosít a fájlokkal való munkához: megnyitás, létrehozás és mappafa kiválasztása. Az ACTION_OPEN_DOCUMENT megnyitja a rendszerválasztót egy létező fájl kiválasztásához. Az ACTION_CREATE_DOCUMENT új fájlt hoz létre — a felhasználó beírja a nevet a párbeszédpanelba, és az alkalmazás URI-t kap az íráshoz.

Az ACTION_OPEN_DOCUMENT_TREE lehetővé teszi egy teljes könyvtár kiválasztását és hozzáférést az összes benne lévő fájlhoz. Fájlkezelőkben, biztonsági mentési és szinkronizációs alkalmazásokban használják. Az alkalmazás megkapja a könyvtár URI-ját, és rekurzívan listázhatja a tartalmat a DocumentFile segítségével.

Minden művelethez a MIME típusokat az EXTRA_MIME_TYPES segítségével adjuk meg. Több típus is megadható: "application/pdf", "image/*", "text/plain". Ha nincsenek típusok megadva, a választó az összes fájlt megjeleníti.

Persistent URI permissions

Persistent URI permissions — SAF mechanizmus, amely lehetővé teszi a fájlhoz való hozzáférés megtartását a jelenlegi munkamenet befejezése után. E zászló nélkül az URI csak az alkalmazás újraindításáig érvényes. Az alkalmazás az FLAG_GRANT_PERSISTABLE_URI_PERMISSION zászlót kéri a READ és WRITE zászlókkal együtt.

A jogosultságok megtartásához a ContentResolver.takePersistableUriPermission metódust használjuk. A rendszer eltárolja az URI-t egy speciális nyilvántartásban, és visszaállítja a hozzáférést az alkalmazás következő indításakor. Annak ellenőrzéséhez, hogy az alkalmazásnak van-e tartós hozzáférése az URI-hoz, a ContentResolver.persistedUriPermissions használható.

A felhasználó visszavonhatja a mentett engedélyeket a Beállítások → Alkalmazások → Engedélyek menün keresztül. Az alkalmazásnak kezelnie kell azt a forgatókönyvet, amikor a fájlhoz való hozzáférés váratlanul megszűnik. Javasolt a hozzáférés ellenőrzése a ContentResolver.openInputStream segítségével a munka megkezdése előtt, és a SecurityException megfelelő kezelése.

Kódpéldák: fájl kiválasztása SAF-on keresztül

A SAF szabványos Intent segítségével indítható el. A kód minimális: hozzon létre egy Intentet ACTION_OPEN_DOCUMENT művelettel, adja meg a MIME típusokat, és indítsa el az ActivityResultContracts.StartActivityForResult segítségével. A fájl kiválasztása után a visszahívás megkapja az URI-t a data.data-ban, amelyet aztán olvasáshoz használ.

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)

Fájl létrehozása ACTION_CREATE_DOCUMENT segítségével

Új fájl írásához használja az ACTION_CREATE_DOCUMENT műveletet. Az Intent elfogadja a MIME típust és a fájlnevet az EXTRA_TITLE segítségével. A mappa kiválasztása és megerősítése után a felhasználó visszaad egy URI-t, amelybe az alkalmazás a ContentResolver.openOutputStream segítségével írja az adatokat. A rendszer automatikusan létrehozza a fájlt a kiválasztott helyen.

SAF vs READ_EXTERNAL_STORAGE

A SAF alapvetően különbözik a hagyományos READ_EXTERNAL_STORAGE-tól a biztonsághoz való hozzáállásában. Ahelyett, hogy "egy csapásra" kérne hozzáférést a teljes tárolóhoz, a SAF csak egy adott fájlhoz kér hozzáférést. Ez minimalizálja a támadási felületet és növeli a felhasználói bizalmat.

A READ_EXTERNAL_STORAGE hozzáférést biztosít az eszköz összes fájljához, beleértve más alkalmazások fényképeit és dokumentumait. Android 10+ rendszeren ez a megközelítés korlátozott. Ezzel szemben a SAF csak a felhasználó által kiválasztott fájlhoz biztosít hozzáférést, és minden fájlhoz kifejezett megerősítést igényel. Kötegelt médiakezeléshez használja a MediaStore-t, egyedi dokumentumokhoz a SAF-ot.

A SAF fő hátránya, hogy minden fájlt külön kell kiválasztani. Tömeges műveletekhez (biztonsági mentés, mappa szinkronizálás) az ACTION_OPEN_DOCUMENT_TREE használható, amely hozzáférést biztosít a kiválasztott könyvtár összes fájljához. A megoldás a forgatókönyvtől függ: a SAF optimális a felhasználó általi kiválasztáshoz, a MediaStore pedig a programozott médiahozzáféréshez.