DocumentProvider — apa itu, membuat penyedia dan bekerja dengan file

Apa itu DocumentProvider?

DocumentsProvider — adalah kelas dasar Android yang mewarisi ContentProvider dan memungkinkan aplikasi menyediakan file-nya ke aplikasi lain melalui antarmuka sistem SAF. Penyedia menciptakan sistem file virtual yang dilihat pengguna di dialog pemilihan dokumen.

Setiap penyedia mengatur file dalam root (roots) — titik masuk tingkat atas. Misalnya, Google Drive memiliki root "Disk Saya" dan "Dibagikan dengan Saya". Di dalam root, penyedia mengembalikan pohon dokumen, di mana setiap dokumen adalah file atau direktori dengan tipe MIME, ukuran, dan tanggal tertentu.

DocumentProvider adalah bagian dari paket android.provider dan tersedia sejak Android 4.4 (API 19). Penyedia digunakan oleh layanan cloud, manajer kata sandi, aplikasi catatan, dan semua program yang menyimpan file dalam format mereka sendiri.

Cara Membuat DocumentProvider Kustom

Pembuatan DocumentProvider Anda sendiri dimulai dengan mewarisi kelas DocumentsProvider dan mengimplementasikan empat metode wajib. Penyedia menentukan struktur file yang ditampilkan di pemilih sistem SAF saat memilih file.

Metode pertama — queryRoots, yang mengembalikan kursor dengan kolom Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY dan Root.COLUMN_FLAGS. Setiap root dapat mendukung flag: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH dan FLAG_SUPPORTS_IS_CHILD.

Metode wajib kedua — queryChildDocuments, yang mengembalikan dokumen anak dari URI yang ditentukan. Metode ini dipanggil ketika pengguna membuka direktori di pemilih. Setiap dokumen berisi kolom: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE dan COLUMN_LAST_MODIFIED.

Metode Wajib DocumentsProvider

DocumentsProvider memerlukan implementasi empat metode yang membentuk struktur file untuk pemilih. Tanpa mereka, penyedia tidak akan berfungsi — dialog sistem SAF tidak akan dapat menampilkan file.

• queryRoots — mengembalikan titik masuk root ke penyimpanan. Setiap root diwakili oleh baris dalam kursor dengan ID, nama, dan ikon.
• queryDocument — mengembalikan satu dokumen berdasarkan ID-nya. Digunakan untuk mendapatkan informasi tentang file tertentu.
• queryChildDocuments — mengembalikan dokumen anak untuk URI direktori induk yang ditentukan.
• openDocument — membuka dokumen berdasarkan ID dan mengembalikan ParcelFileDescriptor untuk membaca atau menulis.

Selain itu, dapat diimplementasikan createDocument untuk membuat file baru, deleteDocument untuk menghapus, dan renameDocument untuk mengganti nama. Metode ini memerlukan flag FLAG_SUPPORTS_CREATE di root.

Pendaftaran Penyedia di AndroidManifest

DocumentProvider didaftarkan di AndroidManifest.xml sebagai ContentProvider biasa dengan intent-filter dan flag tambahan. Penyedia harus dilindungi dari akses langsung melalui permission — disarankan menggunakan android:exported="true" dengan permission eksplisit.

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

Flag grantUriPermissions memungkinkan SAF untuk sementara mendelegasikan hak akses ke aplikasi pemanggil. Atribut authorities harus unik — biasanya menggunakan nama paket dengan akhiran .documents. Disarankan juga untuk menentukan meta-data dengan sumber XML untuk konfigurasi root.

Contoh Kode: Implementasi DocumentsProvider

Implementasi DocumentsProvider memerlukan pengembalian ParcelFileDescriptor dari metode openDocument. Untuk file lokal digunakan ParcelFileDescriptor.open, untuk file cloud — ParcelFileDescriptor.open dengan Pipe untuk transmisi streaming. Kode harus menangani kesalahan akses dan ketiadaan file.

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)
    }
}

Menangani Dokumen Virtual

DocumentProvider dapat mengembalikan file virtual — dokumen yang tidak ada sebagai file terpisah di disk. Misalnya, catatan dari basis data dapat disajikan sebagai PDF virtual. Untuk ini, gunakan tipe MIME dengan flag FLAG_VIRTUAL_DOCUMENT, dan openDocument mengonversi data ke format yang diminta sebelum dikirim.

DocumentProvider di iOS: UIDocumentPickerViewController

iOS memiliki mekanisme serupa — UIDocumentPickerViewController, yang juga menyediakan antarmuka pemilihan file terpadu. Namun di iOS, penyedia dokumen diimplementasikan melalui UIDocumentPickerDelegate dan ekstensi aplikasi (App Extensions) dengan tipe Document Provider.

Tidak seperti Android DocumentsProvider, iOS UIDocumentPickerViewController tidak memerlukan pembuatan penyedia kustom untuk file lokal — pemilih sistem mendukung iCloud Drive dan penyimpanan lokal secara default. Layanan cloud pihak ketiga mendaftar melalui Document Provider extension dengan kunci Info.plist NSExtensionFileProviderDocumentInterface.

Perbedaan utama: di Android, DocumentProvider dipanggil secara aktif melalui SAF Intent dan harus mengimplementasikan navigasi sendiri. Di iOS, UIDocumentPickerViewController menggunakan penjelajah file sistem bawaan, dan ekstensi penyedia hanya bertanggung jawab untuk menyediakan konten berdasarkan permintaan.