Storage Access Framework: ano ito, mga prinsipyo ng paggana at pag-access sa mga file

Ano ang Storage Access Framework?

Storage Access Framework — ay isang bahagi ng Android SDK na nagbibigay ng pinag-isang interface para sa pagpili at paglikha ng mga dokumento sa pamamagitan ng system dialog. SAF ay nag-aabstrak ng pisikal na lokasyon ng mga file: hindi alam ng app kung saan binabasa ang file — mula sa lokal na disk, Google Drive o Dropbox.

Ang arkitektura ng SAF ay may kasamang tatlong bahagi: client app na nagpapasimula ng kahilingan, system picker — karaniwang dialog ng pagpili ng file, at DocumentProvider — content provider na nagpapatupad ng access sa mga file ng isang partikular na imbakan. Ang user ay nakakakita ng pinag-isang interface anuman ang pinagmulan ng data.

Ang SAF ay magagamit mula sa Android 4.4 (API 19). Sa simula, ang framework ay sumusuporta lamang sa mga dokumento, ngunit sa Android 5.0 idinagdag ang suporta para sa mga direktoryo sa pamamagitan ng ACTION_OPEN_DOCUMENT_TREE. Mula sa Android 10, ang SAF ay naging inirerekomendang paraan ng pag-access sa anumang file sa labas ng app-specific storage.

Paano gumagana ang SAF: system picker at URI

SAF ay naglulunsad ng system dialog ng pagpili ng file sa pamamagitan ng Intent na may aksyong ACTION_OPEN_DOCUMENT. Ang user ay nakakakita ng listahan ng mga magagamit na mapagkukunan: panloob na imbakan, Google Drive, Dropbox at iba pang nakarehistrong provider. Pagkatapos pumili ng file, ang system ay nagbabalik ng content URI na may pansamantalang karapatan sa pag-access.

Ang content URI ay may format na content://com.android.externalstorage.documents/document/primary/Download/file.pdf. Hindi tulad ng file:// URI, ang content URI ay hindi nagsisiwalat ng tunay na landas ng file at gumagana sa pamamagitan ng DocumentProvider. Binabasa ng app ang file sa pamamagitan ng ContentResolver.openInputStream batay sa natanggap na URI.

Ang system picker ay awtomatikong sumusuporta sa paghahanap, pag-uuri at pag-filter ng mga file ayon sa mga uri ng MIME. Tinutukoy ng developer ang mga kinakailangang uri sa pamamagitan ng Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), at ang picker ay nagpapakita lamang ng mga kaugnay na file.

Lifecycle ng URI access

Bilang default, ang URI ay may bisa hanggang sa i-restart ang app o i-reboot ang device. Para sa pangmatagalang access, ang app ay humihiling ng takePersistableUriPermission — ito ay nagpapahintulot na basahin ang file sa mga susunod na startup nang hindi pumipili muli sa pamamagitan ng dialog.

ACTION_OPEN_DOCUMENT at ACTION_CREATE_DOCUMENT

SAF ay nagbibigay ng tatlong pangunahing aksyon para sa pagtatrabaho sa mga file: pagbubukas, paglikha at pagpili ng tree ng folder. ACTION_OPEN_DOCUMENT ay nagbubukas ng system picker para sa pagpili ng umiiral na file. ACTION_CREATE_DOCUMENT ay lumilikha ng bagong file — ang user ay naglalagay ng pangalan sa dialog, at ang app ay tumatanggap ng URI para sa pagsulat.

ACTION_OPEN_DOCUMENT_TREE ay nagpapahintulot na pumili ng isang buong direktoryo at makakuha ng access sa lahat ng file sa loob nito. Ito ay ginagamit sa mga file manager, backup at synchronization app. Ang app ay tumatanggap ng URI ng direktoryo at maaaring recursively na maglista ng nilalaman sa pamamagitan ng DocumentFile.

Para sa bawat aksyon, ang mga uri ng MIME ay tinutukoy sa pamamagitan ng EXTRA_MIME_TYPES. Maaaring tukuyin ang maraming uri: "application/pdf", "image/*", "text/plain". Kung hindi tinukoy ang mga uri, ipinapakita ng picker ang lahat ng file.

Persistent URI permissions

Persistent URI permissions — mekanismo ng SAF na nagpapahintulot na mapanatili ang access sa file pagkatapos ng kasalukuyang session. Kung wala ang bandilang ito, ang URI ay may bisa lamang hanggang sa i-restart ang app. Ang app ay humihiling ng bandilang FLAG_GRANT_PERSISTABLE_URI_PERMISSION kasama ng READ at WRITE bandila.

Para sa pagpapanatili ng mga karapatan, ginagamit ang metodong ContentResolver.takePersistableUriPermission. Ang system ay nag-iimbak ng URI sa isang espesyal na rehistro at nagpapanumbalik ng access sa susunod na paglunsad ng app. Upang suriin kung ang app ay may persistent access sa URI, ginagamit ang ContentResolver.persistedUriPermissions.

Ang user ay maaaring mag-withdraw ng mga naka-save na pahintulot sa pamamagitan ng Settings → Apps → Permissions. Ang app ay dapat humawak ng senaryo kapag ang access sa file ay biglang nawala. Inirerekomenda na suriin ang access sa pamamagitan ng ContentResolver.openInputStream bago magsimula ng trabaho at maayos na pangasiwaan ang SecurityException.

Mga halimbawa ng code: pagpili ng file sa pamamagitan ng SAF

SAF ay inilulunsad sa pamamagitan ng karaniwang Intent. Ang code ay minimal: lumikha ng Intent na may ACTION_OPEN_DOCUMENT, tukuyin ang mga uri ng MIME at ilunsad sa pamamagitan ng ActivityResultContracts.StartActivityForResult. Pagkatapos pumili ng file, ang callback ay tumatanggap ng URI sa data.data, na pagkatapos ay ginagamit para sa pagbasa.

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)

Paglikha ng file sa pamamagitan ng ACTION_CREATE_DOCUMENT

Para sa pagsulat ng bagong file, gamitin ang ACTION_CREATE_DOCUMENT. Ang Intent ay tumatanggap ng uri ng MIME at pangalan ng file sa pamamagitan ng EXTRA_TITLE. Pagkatapos pumili ng folder at kumpirmahin, ang user ay nagbabalik ng URI kung saan ang app ay nagsusulat ng data sa pamamagitan ng ContentResolver.openOutputStream. Awtomatikong lumilikha ang system ng file sa napiling lokasyon.

SAF vs READ_EXTERNAL_STORAGE

SAF ay naiiba mula sa tradisyonal na READ_EXTERNAL_STORAGE sa pamamagitan ng pangunahing ibang diskarte sa seguridad. Sa halip na humingi ng access sa buong imbakan “sa isang pagkakataon”, ang SAF ay humihingi lamang ng access sa isang partikular na file. Ito ay nagpapaliit sa ibabaw ng pag-atake at nagpapataas ng tiwala ng user.

READ_EXTERNAL_STORAGE ay nagbibigay ng access sa lahat ng file sa device, kabilang ang mga larawan at dokumento ng ibang mga app. Sa Android 10+ ang diskarteng ito ay limitado. Ang SAF, sa kabaligtaran, ay nagbibigay lamang ng access sa file na pinili ng user at nangangailangan ng tahasang kumpirmasyon para sa bawat file. Para sa batch work sa media, gamitin ang MediaStore; para sa indibidwal na mga dokumento, gamitin ang SAF.

Ang pangunahing kahinaan ng SAF ay ang pangangailangan na pumili ng bawat file nang hiwalay. Para sa maramihang operasyon (backup, pag-sync ng folder), ginagamit ang ACTION_OPEN_DOCUMENT_TREE na nagbibigay ng access sa lahat ng file sa napiling direktoryo. Ang solusyon ay depende sa senaryo: SAF ay optimal para sa pagpili ng user, MediaStore — para sa programmatic access sa media.