DocumentProvider — bu nədir, provayder yaratmaq və fayllarla iş

DocumentProvider nədir?

DocumentsProvider — ContentProvider-dən miras alan və proqrama öz fayllarını SAF sistem interfeysi vasitəsilə digər proqramlara təqdim etməyə imkan verən əsas Android sinifidir. Provayder istifadəçinin sənəd seçim dialoqunda gördüyü virtual fayl sistemi yaradır.

Hər bir provayder faylları köklərə (roots) — yuxarı səviyyəli giriş nöqtələrinə təşkil edir. Məsələn, Google Drive “Mənim diskim” və “Mənimlə paylaşılan” köklərinə malikdir. Kök daxilində provayder hər bir sənədin müəyyən MIME növü, ölçüsü və tarixləri olan fayl və ya qovluq olduğu sənəd ağacını qaytarır.

DocumentProvider android.provider paketinə daxildir və Android 4.4-dən (API 19) etibarən mövcuddur. Provayder bulud xidmətləri, parol menecerləri, qeyd proqramları və faylları öz formatında saxlayan bütün proqramlar tərəfindən istifadə olunur.

Xüsusi DocumentProvider necə yaradılır

Yaradılması öz DocumentProvider-inizin DocumentsProvider sinifindən miras almaqla və dörd məcburi metodu tətbiq etməklə başlayır. Provayder fayl seçimi zamanı SAF sistem seçicisində göstərilən fayl strukturunu müəyyən edir.

Birinci metod — queryRoots, Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY və Root.COLUMN_FLAGS sütunları ilə kursor qaytarır. Hər bir kök FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH və FLAG_SUPPORTS_IS_CHILD bayraqlarını dəstəkləyə bilər.

İkinci məcburi metod — queryChildDocuments, göstərilən URI-nin alt sənədlərini qaytarır. Bu metod istifadəçi seçicidə qovluğu açdıqda çağırılır. Hər bir sənəd sütunları ehtiva edir: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE və COLUMN_LAST_MODIFIED.

DocumentsProvider-in məcburi metodları

DocumentsProvider seçici üçün fayl strukturunu formalaşdıran dörd metodun tətbiqini tələb edir. Onlar olmadan provayder işləməyəcək — sistem SAF dialoqu faylları göstərə bilməyəcək.

• queryRoots — yaddaşa kök giriş nöqtələrini qaytarır. Hər bir kök ID, ad və ikon ilə kursorda sətirlə təmsil olunur.
• queryDocument — ID-sinə görə bir sənədi qaytarır. Müəyyən fayl haqqında məlumat almaq üçün istifadə olunur.
• queryChildDocuments — göstərilən ana qovluq URI-si üçün alt sənədləri qaytarır.
• openDocument — ID-sinə görə sənədi açır və oxumaq və ya yazmaq üçün ParcelFileDescriptor qaytarır.

Əlavə olaraq createDocument (yeni fayl yaratmaq), deleteDocument (siləmək) və renameDocument (ad dəyişdirmək) tətbiq edilə bilər. Bu metodlar kökdə FLAG_SUPPORTS_CREATE bayrağı tələb edir.

AndroidManifest-də provayderin qeydiyyatı

DocumentProvider AndroidManifest.xml-də əlavə intent-filter və bayraqlarla adi ContentProvider kimi qeydiyyatdan keçirilir. Provayder birbaşa girişdən permission vasitəsilə qorunmalıdır — açıq permission ilə android:exported="true" istifadə etmək tövsiyyə olunur.

<provider
    android:name=".provider.CustomDocumentProvider"
    android:authorities="com.example.app.documents"
    android:exported="true"
    android:grantUriPermissions="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action
            android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
    <meta-data
        android:name="android.content.documents.roots"
        android:resource="@xml/file_paths" />
</provider>

grantUriPermissions bayrağı SAF-a zəng edən proqrama müvəqqəti giriş hüquqları verməyə imkan verir. Authorities atributu unikal olmalıdır — adətən .documents suffiksi ilə paket adı istifadə olunur. Kökləri konfiqurasiya etmək üçün XML resursu ilə meta-data da göstərmək tövsiyyə olunur.

Kod nümunəsi: DocumentsProvider tətbiqi

Tətbiqi DocumentsProvider openDocument metodundan ParcelFileDescriptor qaytarmağı tələb edir. Yerli fayllar üçün ParcelFileDescriptor.open, bulud faylları üçün stream ötürülməsi üçün ParcelFileDescriptor.open ilə Pipe istifadə olunur. Kod giriş səhvlərini və faylın olmamasını idarə etməlidir.

class CustomDocumentProvider : DocumentsProvider() {

    override fun queryRoots(): Cursor {
        val matrix = MatrixCursor(Root.COLUMNS)
        matrix.newRow().add(Root.COLUMN_ROOT_ID, "local")
            .add(Root.COLUMN_TITLE, "My Files")
            .add(Root.COLUMN_SUMMARY, "Local documents")
            .add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE)
        return matrix
    }

    override fun openDocument(
        documentId: String, flags: Int, cursor: CancellationSignal?
    ): ParcelFileDescriptor {
        val file = File(context.filesDir, documentId)
        val accessMode = ParcelFileDescriptor.parseMode(flags)
        return ParcelFileDescriptor.open(file, accessMode)
    }
}

Virtual sənədlərin idarə edilməsi

DocumentProvider virtual faylları — diskdə ayrıca fayl kimi mövcud olmayan sənədləri qaytara bilər. Məsələn, verilənlər bazasındakı qeyd virtual PDF kimi təqdim edilə bilər. Bunun üçün FLAG_VIRTUAL_DOCUMENT bayrağı ilə MIME növü istifadə olunur və openDocument göndərmədən əvvəl məlumatları tələb olunan formata çevirir.

iOS-də DocumentProvider: UIDocumentPickerViewController

iOS oxşar mexanizmə malikdir — UIDocumentPickerViewController, o da vahid fayl seçim interfeysini təmin edir. Lakin iOS-da sənəd provayderi UIDocumentPickerDelegate və Document Provider növü ilə proqram genişləndirmələri (App Extensions) vasitəsilə tətbiq edilir.

Android DocumentsProvider-dən fərqli olaraq, iOS UIDocumentPickerViewController yerli fayllar üçün xüsusi provayder yaradılmasını tələb etmir — sistem seçicisi iCloud Drive və yerli yaddaşı defolt olaraq dəstəkləyir. Üçüncü tərəf bulud xidmətləri Info.plist açarı NSExtensionFileProviderDocumentInterface ilə Document Provider extension vasitəsilə qeydiyyatdan keçir.

Əsas fərq: Android-də DocumentProvider aktiv şəkildə çağırılır SAF Intent vasitəsilə və naviqasiyanı özü tətbiq etməlidir. iOS-da UIDocumentPickerViewController daxili sistem fayl brauzerindən istifadə edir və provayder genişləndirməsi yalnız tələb əsasında məzmun təqdim etməyə cavabdehdir.