DocumentProvider — nedir, sağlayıcı oluşturma ve dosyalarla çalışma

DocumentProvider nedir?

DocumentsProvider, ContentProvider'ı genişleten ve bir uygulamanın sistem SAF arayüzü aracılığıyla diğer uygulamalara dosyalarını sağlamasına olanak tanıyan bir Android temel sınıfıdır. Sağlayıcı, kullanıcının belge seçme iletişim kutusunda gördüğü sanal bir dosya sistemi oluşturur.

Her sağlayıcı dosyaları kökler (roots) — üst düzey giriş noktaları halinde düzenler. Örneğin, Google Drive'ın “Sürücüm” ve “Benimle paylaşılan” kökleri vardır. Bir kök içinde sağlayıcı, her belgenin belirli bir MIME türüne, boyuta ve tarihlere sahip bir dosya veya dizin olduğu bir belge ağacı döndürür.

DocumentProvider, android.provider paketinin bir parçasıdır ve Android 4.4 (API 19) itibarıyla kullanılabilir. Sağlayıcı, bulut hizmetleri, parola yöneticileri, not alma uygulamaları ve dosyaları kendi biçiminde depolayan herhangi bir program tarafından kullanılır.

Özel DocumentProvider nasıl oluşturulur

Kendi DocumentProvider'ınızı oluşturmak, DocumentsProvider sınıfını genişletmek ve dört zorunlu yöntemi uygulamakla başlar. Sağlayıcı, dosyalar seçilirken sistem SAF seçicisinde görünen dosya yapısını tanımlar.

İlk yöntem queryRoots'dur ve Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY ve Root.COLUMN_FLAGS sütunlarına sahip bir imleç döndürür. Her kök şu bayrakları destekleyebilir: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH ve FLAG_SUPPORTS_IS_CHILD.

İkinci zorunlu yöntem queryChildDocuments'dır ve belirtilen bir URI'nin alt belgelerini döndürür. Bu yöntem, kullanıcı seçicide bir dizin açtığında çağrılır. Her belge şu sütunları içerir: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE ve COLUMN_LAST_MODIFIED.

DocumentsProvider'ın zorunlu yöntemleri

DocumentsProvider, seçici için dosya yapısını oluşturan dört yöntemin uygulanmasını gerektirir. Bunlar olmadan sağlayıcı çalışmaz — sistem SAF iletişim kutusu dosyaları görüntüleyemez.

• queryRoots — depolamaya kök giriş noktalarını döndürür. Her kök, imleçte bir kimlik, ad ve simge içeren bir satırla temsil edilir.
• queryDocument — kimliğine göre tek bir belge döndürür. Belirli bir dosya hakkında bilgi almak için kullanılır.
• queryChildDocuments — belirtilen üst dizin URI'si için alt belgeleri döndürür.
• openDocument — kimliğe göre bir belge açar ve okuma veya yazma için ParcelFileDescriptor döndürür.

Ek olarak, yeni dosyalar oluşturmak için createDocument, silmek için deleteDocument ve yeniden adlandırmak için renameDocument uygulanabilir. Bu yöntemler kökte FLAG_SUPPORTS_CREATE bayrağı gerektirir.

AndroidManifest'te sağlayıcıyı kaydetme

DocumentProvider, ek bir intent filtresi ve bayraklarla normal bir ContentProvider olarak AndroidManifest.xml dosyasına kaydedilir. Sağlayıcı, izin yoluyla doğrudan erişime karşı korunmalıdır — açık izinle android:exported="true" kullanılması önerilir.

<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'ın çağrı yapan uygulamaya geçici olarak erişim hakları vermesini sağlar. Authorities özniteliği benzersiz olmalıdır — genellikle .documents sonekiyle birlikte paket adı kullanılır. Kökleri yapılandırmak için bir XML kaynağıyla meta-data belirtilmesi de önerilir.

Kod örneği: DocumentsProvider uygulaması

DocumentsProvider uygulaması, openDocument yönteminden ParcelFileDescriptor döndürmeyi gerektirir. Yerel dosyalar için ParcelFileDescriptor.open kullanılır, bulut dosyaları için — akış için Pipe ile ParcelFileDescriptor.open kullanılır. Kod, erişim hatalarını ve eksik dosyaları işlemelidir.

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

Sanal belgeleri işleme

DocumentProvider sanal dosyalar döndürebilir — diskte ayrı dosyalar olarak bulunmayan belgeler. Örneğin, bir veritabanı notu sanal PDF olarak sunulabilir. Bu, FLAG_VIRTUAL_DOCUMENT bayrağıyla bir MIME türü kullanır ve openDocument, göndermeden önce verileri istenen biçime dönüştürür.

iOS'ta DocumentProvider: UIDocumentPickerViewController

iOS, benzer bir mekanizmaya sahiptir — UIDocumentPickerViewController, ayrıca birleşik bir dosya seçme arayüzü sağlar. Ancak iOS'ta belge sağlayıcı, UIDocumentPickerDelegate ve Document Provider türündeki Uzantılar (App Extensions) aracılığıyla uygulanır.

Android DocumentsProvider'ın aksine, iOS UIDocumentPickerViewController yerel dosyalar için özel bir sağlayıcı oluşturmayı gerektirmez — sistem seçicisi varsayılan olarak iCloud Drive ve yerel depolamayı destekler. Üçüncü taraf bulut hizmetleri, Info.plist anahtarı NSExtensionFileProviderDocumentInterface ile bir Document Provider uzantısı aracılığıyla kaydolur.

Temel fark: Android'de DocumentProvider, SAF Intent aracılığıyla aktif olarak çağrılır ve gezinmeyi kendisi uygulamalıdır. iOS'ta UIDocumentPickerViewController yerleşik bir sistem dosya tarayıcısı kullanır ve uzantı sağlayıcısı yalnızca istek üzerine içerik sağlamaktan sorumludur.