DocumentProvider — bu nima, provayder yaratish va fayllar bilan ishlash

DocumentProvider nima?

DocumentsProvider — ContentProvider dan meros oladigan va ilovaga o'z fayllarini SAF tizim interfeysi orqali boshqa ilovalarga taqdim etishga imkon beradigan asosiy Android klassidir. Provayder foydalanuvchi hujjat tanlash dialogida ko'radigan virtual fayl tizimini yaratadi.

Har bir provayder fayllarni ildizlar (roots) — yuqori darajadagi kirish nuqtalariga tartibga soladi. Masalan, Google Drive „Mening diskim" va „Men bilan ulashilgan" ildizlariga ega. Ildiz ichida provayder har bir hujjat ma'lum MIME turi, hajmi va sanalari bo'lgan fayl yoki katalog bo'lgan hujjat daraxtini qaytaradi.

DocumentProvider android.provider paketiga kiradi va Android 4.4 (API 19) dan boshlab mavjud. Provayder bulut xizmatlari, parol menejerlari, eslatma ilovalari va fayllarni o'z formatida saqlaydigan barcha dasturlar tomonidan ishlatiladi.

Maxsus DocumentProvider qanday yaratiladi

Yaratish o'z DocumentProvider ingizni DocumentsProvider klassidan meros olish va to'rtta majburiy metodni amalga oshirish bilan boshlanadi. Provayder fayl tanlashda SAF tizim tanlovchisida ko'rsatiladigan fayl tuzilmasini belgilaydi.

Birinchi metod — queryRoots, Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY va Root.COLUMN_FLAGS ustunlari bilan kursor qaytaradi. Har bir ildiz FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH va FLAG_SUPPORTS_IS_CHILD bayroqlarini qo'llab-quvvatlashi mumkin.

Ikkinchi majburiy metod — queryChildDocuments, belgilangan URI ning pastki hujjatlarini qaytaradi. Bu metod foydalanuvchi tanlovchida katalogni ochganda chaqiriladi. Har bir hujjat ustunlarni o'z ichiga oladi: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE va COLUMN_LAST_MODIFIED.

DocumentsProvider ning majburiy metodlari

DocumentsProvider tanlovchi uchun fayl tuzilmasini shakllantiradigan to'rtta metodni amalga oshirishni talab qiladi. Ular bo'lmasa provayder ishlamaydi — tizim SAF dialogi fayllarni ko'rsata olmaydi.

• queryRoots — saqlash joyiga ildiz kirish nuqtalarini qaytaradi. Har bir ildiz ID, nom va belgi bilan kursorda qator bilan ifodalanadi.
• queryDocument — ID si bo'yicha bitta hujjatni qaytaradi. Muayyan fayl haqida ma'lumot olish uchun ishlatiladi.
• queryChildDocuments — belgilangan ota katalog URI si uchun pastki hujjatlarni qaytaradi.
• openDocument — ID si bo'yicha hujjatni ochadi va o'qish yoki yozish uchun ParcelFileDescriptor qaytaradi.

Qo'shimcha ravishda createDocument (yangi fayllar yaratish), deleteDocument (o'chirish) va renameDocument (nomini o'zgartirish) amalga oshirilishi mumkin. Bu metodlar ildizda FLAG_SUPPORTS_CREATE bayrog'ini talab qiladi.

AndroidManifest da provayderni ro'yxatdan o'tkazish

DocumentProvider AndroidManifest.xml da qo'shimcha intent-filter va bayroqlar bilan oddiy ContentProvider sifatida ro'yxatdan o'tkaziladi. Provayder to'g'ridan-to'g'ri kirishdan permission orqali himoyalanishi kerak — aniq permission bilan android:exported="true" ishlatish tavsiya etiladi.

<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 bayrog'i SAF ga chaqiruvchi ilovaga vaqtinchalik kirish huquqlarini berishga imkon beradi. Authorities atributi noyob bo'lishi kerak — odatda .documents qo'shimchasi bilan paket nomi ishlatiladi. Ildizlarni sozlash uchun XML resursi bilan meta-data ko'rsatish ham tavsiya etiladi.

Kod namunasi: DocumentsProvider amalga oshirilishi

Amalga oshirish DocumentsProvider openDocument metodidan ParcelFileDescriptor qaytarishni talab qiladi. Mahalliy fayllar uchun ParcelFileDescriptor.open, bulut fayllari uchun stream uzatish uchun ParcelFileDescriptor.open bilan Pipe ishlatiladi. Kod kirish xatolari va fayl yo'qligini boshqarishi kerak.

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 hujjatlarni boshqarish

DocumentProvider virtual fayllarni — diskda alohida fayl sifatida mavjud bo'lmagan hujjatlarni qaytarishi mumkin. Masalan, ma'lumotlar bazasidagi eslatma virtual PDF sifatida taqdim etilishi mumkin. Buning uchun FLAG_VIRTUAL_DOCUMENT bayrog'i bilan MIME turi ishlatiladi va openDocument yuborishdan oldin ma'lumotlarni kerakli formatga o'zgartiradi.

iOS da DocumentProvider: UIDocumentPickerViewController

iOS o'xshash mexanizmga ega — UIDocumentPickerViewController, u ham yagona fayl tanlash interfeysini taqdim etadi. Biroq iOS da hujjat provayderi UIDocumentPickerDelegate va Document Provider turi bilan ilova kengaytmalari (App Extensions) orqali amalga oshiriladi.

Android DocumentsProvider dan farqli o'laroq, iOS UIDocumentPickerViewController mahalliy fayllar uchun maxsus provayder yaratishni talab qilmaydi — tizim tanlovchisi iCloud Drive va mahalliy saqlashni sukut bo'yicha qo'llab-quvvatlaydi. Uchinchi tomon bulut xizmatlari Info.plist kaliti NSExtensionFileProviderDocumentInterface bilan Document Provider extension orqali ro'yxatdan o'tadi.

Asosiy farq: Android da DocumentProvider faol chaqiriladi SAF Intent orqali va navigatsiyani o'zi amalga oshirishi kerak. iOS da UIDocumentPickerViewController o'rnatilgan tizim fayl brauzeridan foydalanadi va provayder kengaytmasi faqat so'rov bo'yicha kontent taqdim etish uchun javobgardir.