Storage Access Framework: bu nədir, iş prinsipləri və fayllara giriş

Storage Access Framework nədir?

Storage Access Framework — bu, sistem dialoqu vasitəsilə sənədlərin seçilməsi və yaradılması üçün vahid interfeys təmin edən Android SDK-nın bir hissəsidir. SAF faylların fiziki yerini abstraksiya edir: proqram faylın hardan oxunduğunu bilmir — lokal diskdən, Google Drive-dan və ya Dropbox-dan.

SAF arxitekturası üç komponentdən ibarətdir: sorğunu başladan müştəri proqramı, standart fayl seçim dialoqu olan sistem seçicisi və konkret yaddaşın fayllarına girişi həyata keçirən kontent provayderi DocumentProvider. İstifadəçi məlumat mənbəyindən asılı olmayaraq vahid interfeys görür.

SAF Android 4.4 (API 19)-dan etibarən mövcuddur. Əvvəlcə freymvork yalnız sənədləri dəstəkləyirdi, lakin Android 5.0-də ACTION_OPEN_DOCUMENT_TREE vasitəsilə kataloqların dəstəyi əlavə edildi. Android 10-dan etibarən SAF app-specific storage xaricində istənilən fayla giriş üçün tövsiyə olunan üsul oldu.

SAF necə işləyir: sistem seçicisi və URI

SAF ACTION_OPEN_DOCUMENT hərəkəti ilə Intent vasitəsilə sistem fayl seçim dialoqunu işə salır. İstifadəçi mövcud mənbələrin siyahısını görür: daxili yaddaş, Google Drive, Dropbox və digər qeydiyyatdan keçmiş provayderlər. Fayl seçildikdən sonra sistem müvəqqəti giriş hüquqları ilə content URI qaytarır.

Content URI formatı content://com.android.externalstorage.documents/document/primary/Download/file.pdf şəklindədir. file:// URI-dən fərqli olaraq, content URI faylın real yolunu açıqlamır və DocumentProvider vasitəsilə işləyir. Proqram faylı alınmış URI üzrə ContentResolver.openInputStream vasitəsilə oxuyur.

Sistem seçicisi avtomatik olaraq faylların MIME növləri üzrə axtarış, çeşidləmə və filtrasiyasını dəstəkləyir. Tərtibatçı Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")) vasitəsilə lazımi növləri göstərir və seçici yalnız uyğun faylları göstərir.

URI girişinin həyat dövrü

Susmaya görə, URI proqram yenidən başladılana və ya cihaz yenidən yüklənənə qədər etibarlıdır. Uzunmüddətli giriş üçün proqram takePersistableUriPermission tələb edir — bu, dialoq vasitəsilə təkrar seçim etmədən faylı sonrakı işə salmalarda oxumağa imkan verir.

ACTION_OPEN_DOCUMENT və ACTION_CREATE_DOCUMENT

SAF fayllarla iş üçün üç əsas hərəkət təmin edir: açma, yaratma və qovluq ağacının seçimi. ACTION_OPEN_DOCUMENT mövcud faylı seçmək üçün sistem seçicisini açır. ACTION_CREATE_DOCUMENT yeni fayl yaradır — istifadəçi dialoqda ad daxil edir, proqram isə yazı üçün URI alır.

ACTION_OPEN_DOCUMENT_TREE bütün kataloqu seçməyə və oradakı bütün fayllara giriş əldə etməyə imkan verir. Bu, fayl menecerlərində, ehtiyat nüsxə və sinxronizasiya proqramlarında istifadə olunur. Proqram kataloqun URI-ni alır və DocumentFile vasitəsilə məzmunu rekursiv şəkildə sadalaya bilər.

Hər hərəkət üçün MIME növləri EXTRA_MIME_TYPES vasitəsilə göstərilir. Bir neçə növ göstərilə bilər: "application/pdf", "image/*", "text/plain". Növlər göstərilməzsə, seçici bütün faylları göstərir.

Persistent URI permissions

Persistent URI permissions — cari sessiya bitdikdən sonra fayla girişi saxlamağa imkan verən SAF mexanizmi. Bu bayraq olmadan URI yalnız proqram yenidən başladılana qədər etibarlıdır. Proqram READ və WRITE bayraqları ilə birlikdə FLAG_GRANT_PERSISTABLE_URI_PERMISSION bayrağını tələb edir.

Hüquqları saxlamaq üçün ContentResolver.takePersistableUriPermission metodu istifadə olunur. Sistem URI-ni xüsusi reyestrdə saxlayır və proqram növbəti dəfə işə salındıqda girişi bərpa edir. Proqramın URI-ə davamlı girişinin olub-olmadığını yoxlamaq üçün ContentResolver.persistedUriPermissions istifadə olunur.

İstifadəçi saxlanmış icazələri Parametrlər → Proqramlar → İcazələr vasitəsilə ləğv edə bilər. Proqram fayla girişin gözlənilmədən itdiyi ssenarini idarə etməlidir. İşə başlamazdan əvvəl girişi ContentResolver.openInputStream vasitəsilə yoxlamaq və SecurityException-ı düzgün idarə etmək tövsiyə olunur.

Kod nümunələri: SAF vasitəsilə fayl seçimi

SAF standart Intent vasitəsilə işə salınır. Kod minimaldır: ACTION_OPEN_DOCUMENT ilə Intent yaradın, MIME növlərini göstərin və ActivityResultContracts.StartActivityForResult vasitəsilə işə salın. Fayl seçildikdən sonra callback data.data-da URI alır, sonra oxuma üçün istifadə olunur.

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 vasitəsilə fayl yaradılması

Yeni fayl yazmaq üçün ACTION_CREATE_DOCUMENT istifadə edin. Intent MIME növünü və EXTRA_TITLE vasitəsilə fayl adını qəbul edir. Qovluq seçilib təsdiqləndikdən sonra istifadəçi URI qaytarır, proqram isə ContentResolver.openOutputStream vasitəsilə məlumatları yazır. Sistem seçilmiş yerdə avtomatik olaraq fayl yaradır.

SAF vs READ_EXTERNAL_STORAGE

SAF ənənəvi READ_EXTERNAL_STORAGE-dən təhlükəsizliyə prinsipial fərqli yanaşması ilə ayrılır. Bütün yaddaşa "bir dəfəyə" giriş tələb etmək əvəzinə, SAF yalnız konkret fayla giriş tələb edir. Bu, hücum səthini minimuma endirir və istifadəçi etibarını artırır.

READ_EXTERNAL_STORAGE cihazdakı bütün fayllara, o cümlədən digər proqramların foto və sənədlərinə giriş verir. Android 10+-da bu yanaşma məhdudlaşdırılmışdır. SAF isə yalnız istifadəçi tərəfindən seçilmiş fayla giriş təmin edir və hər fayl üçün açıq təsdiq tələb edir. Media ilə toplu iş üçün MediaStore-dan, tək sənədlər üçün SAF-dan istifadə edin.

SAF-ın əsas çatışmazlığı hər faylı ayrıca seçmək zərurətidir. Kütləvi əməliyyatlar (ehtiyat nüsxələmə, qovluq sinxronizasiyası) üçün seçilmiş kataloqda bütün fayllara giriş verən ACTION_OPEN_DOCUMENT_TREE istifadə olunur. Həll ssenaridən asılıdır: SAF istifadəçi seçimi üçün optimaldır, MediaStore — media-ya proqram girişi üçün.