Storage Access Framework: шта је то, принципи рада и приступ датотекама

Шта је Storage Access Framework?

Storage Access Framework — је део Android SDK-а који пружа јединствени интерфејс за избор и креирање докумената кроз системски дијалог. SAF апстрахује физичку локацију датотека: апликација не зна одакле се датотека чита — са локалног диска, Google Drive-а или Dropbox-а.

Архитектура SAF-а укључује три компоненте: клијентску апликацију која покреће захтев, системски бирач — стандардни дијалог за избор датотеке, и DocumentProvider — провајдера садржаја који имплементира приступ датотекама одређеног складишта. Корисник види јединствени интерфејс без обзира на извор података.

SAF је доступан од Android 4.4 (API 19). Првобитно је оквир подржавао само документе, али је у Android 5.0 додата подршка за директоријуме кроз ACTION_OPEN_DOCUMENT_TREE. Од Android 10, SAF је постао препоручени начин приступа било којој датотеци изван app-specific storage-а.

Како ради SAF: системски бирач и URI

SAF покреће системски дијалог избора датотеке кроз Intent са акцијом ACTION_OPEN_DOCUMENT. Корисник види листу доступних извора: интерну меморију, Google Drive, Dropbox и друге регистроване провајдере. Након избора датотеке, систем враћа content URI са привременим правима приступа.

Content URI има формат content://com.android.externalstorage.documents/document/primary/Download/file.pdf. За разлику од file:// URI-ја, content URI не открива стварну путању до датотеке и ради преко DocumentProvider-а. Апликација чита датотеку кроз ContentResolver.openInputStream на основу добијеног URI-ја.

Системски бирач аутоматски подржава претрагу, сортирање и филтрирање датотека по MIME типовима. Програмер наводи потребне типове кроз Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), а бирач приказује само релевантне датотеке.

Животни циклус URI приступа

Подразумевано, URI важи до поновног покретања апликације или ресетовања уређаја. За дугорочни приступ, апликација захтева takePersistableUriPermission — ово омогућава читање датотеке при наредним покретањима без поновног избора кроз дијалог.

ACTION_OPEN_DOCUMENT и ACTION_CREATE_DOCUMENT

SAF пружа три главне акције за рад са датотекама: отварање, креирање и избор стабла фасцикли. ACTION_OPEN_DOCUMENT отвара системски бирач за избор постојеће датотеке. ACTION_CREATE_DOCUMENT креира нову датотеку — корисник уноси назив у дијалогу, а апликација добија URI за упис.

ACTION_OPEN_DOCUMENT_TREE омогућава избор целог директоријума и приступ свим датотекама у њему. Користи се у менаџерима датотека, апликацијама за прављење резервних копија и синхронизацију. Апликација добија URI директоријума и може рекурзивно да набраја садржај кроз DocumentFile.

За сваку акцију, MIME типови се наводе кроз EXTRA_MIME_TYPES. Може се навести више типова: "application/pdf", "image/*", "text/plain". Ако типови нису наведени, бирач приказује све датотеке.

Persistent URI permissions

Persistent URI permissions — SAF механизам који омогућава очување приступа датотеци након завршетка тренутне сесије. Без ове заставице, URI важи само до поновног покретања апликације. Апликација захтева заставицу FLAG_GRANT_PERSISTABLE_URI_PERMISSION заједно са READ и WRITE заставицама.

За чување дозвола користи се метода ContentResolver.takePersistableUriPermission. Систем чува URI у посебном регистру и обнавља приступ при следећем покретању апликације. Да би се проверило да ли апликација има трајни приступ URI-ју, користи се ContentResolver.persistedUriPermissions.

Корисник може опозвати сачуване дозволе кроз Подешавања → Апликације → Дозволе. Апликација треба да обрађује сценарио када приступ датотеци неочекивано нестане. Препоручује се провера приступа кроз ContentResolver.openInputStream пре почетка рада и правилно руковање SecurityException-ом.

Примери кода: избор датотеке кроз SAF

SAF се покреће кроз стандардни Intent. Код је минималан: креирајте Intent са ACTION_OPEN_DOCUMENT, наведите MIME типове и покрените кроз ActivityResultContracts.StartActivityForResult. Након избора датотеке, callback добија URI у data.data, који се затим користи за читање.

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)

Креирање датотеке кроз ACTION_CREATE_DOCUMENT

За упис нове датотеке користите ACTION_CREATE_DOCUMENT. Intent прима MIME тип и назив датотеке кроз EXTRA_TITLE. Након избора фасцикле и потврде, корисник враћа URI у који апликација уписује податке кроз ContentResolver.openOutputStream. Систем аутоматски креира датотеку на изабраној локацији.

SAF vs READ_EXTERNAL_STORAGE

SAF се разликује од традиционалног READ_EXTERNAL_STORAGE-а суштински другачијим приступом безбедности. Уместо захтевања приступа целој меморији "одједном", SAF захтева приступ само одређеној датотеци. Ово минимизира површину напада и повећава поверење корисника.

READ_EXTERNAL_STORAGE даје приступ свим датотекама на уређају, укључујући фотографије и документе других апликација. На Android 10+ овај приступ је ограничен. SAF, насупрот томе, пружа приступ само датотеци коју је изабрао корисник и захтева експлицитну потврду за сваку датотеку. За групни рад са медијима користите MediaStore, за појединачне документе — SAF.

Главни недостатак SAF-а је потреба за избором сваке датотеке понаособ. За масовне операције (резервне копије, синхронизација фасцикли) користи се ACTION_OPEN_DOCUMENT_TREE, који даје приступ свим датотекама у изабраном директоријуму. Решење зависи од сценарија: SAF је оптималан за избор од стране корисника, MediaStore — за програмски приступ медијима.