DocumentProvider — co to jest, tworzenie dostawcy i praca z plikami

Co to jest DocumentProvider?

DocumentsProvider — to podstawowa klasa Androida dziedzicząca po ContentProvider, która pozwala aplikacji udostępniać swoje pliki innym aplikacjom przez systemowy interfejs SAF. Dostawca tworzy wirtualny system plików widoczny dla użytkownika w oknie wyboru dokumentów.

Każdy dostawca organizuje pliki w korzenie (roots) — punkty wejścia najwyższego poziomu. Na przykład Google Drive ma korzenie „Mój dysk” i „Udostępnione mi”. Wewnątrz korzenia dostawca zwraca drzewo dokumentów, gdzie każdy dokument to plik lub katalog z określonym typem MIME, rozmiarem i datami.

DocumentProvider wchodzi w skład pakietu android.provider i jest dostępny od Androida 4.4 (API 19). Dostawca jest używany przez usługi w chmurze, menedżery haseł, aplikacje notatek i wszelkie programy przechowujące pliki we własnym formacie.

Jak stworzyć niestandardowy DocumentProvider

Tworzenie własnego DocumentProvider zaczyna się od dziedziczenia klasy DocumentsProvider i implementacji czterech obowiązkowych metod. Dostawca określa strukturę plików wyświetlaną w systemowym selektorze SAF przy wyborze plików.

Pierwsza metoda — queryRoots, która zwraca kursor z kolumnami Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY i Root.COLUMN_FLAGS. Każdy korzeń może obsługiwać flagi: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH i FLAG_SUPPORTS_IS_CHILD.

Druga obowiązkowa metoda — queryChildDocuments, zwracająca dokumenty podrzędne dla określonego URI. Ta metoda jest wywoływana, gdy użytkownik otwiera katalog w selektorze. Każdy dokument zawiera kolumny: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE i COLUMN_LAST_MODIFIED.

Obowiązkowe metody DocumentsProvider

DocumentsProvider wymaga implementacji czterech metod, które tworzą strukturę plików dla selektora. Bez nich dostawca nie będzie działać — systemowy dialog SAF nie będzie mógł wyświetlić plików.

• queryRoots — zwraca korzeniowe punkty wejścia do magazynu. Każdy korzeń jest reprezentowany przez wiersz w kursorze z ID, nazwą i ikoną.
• queryDocument — zwraca jeden dokument po jego ID. Używany do uzyskania informacji o konkretnym pliku.
• queryChildDocuments — zwraca dokumenty podrzędne dla określonego URI katalogu nadrzędnego.
• openDocument — otwiera dokument po ID i zwraca ParcelFileDescriptor do odczytu lub zapisu.

Dodatkowo można zaimplementować createDocument do tworzenia nowych plików, deleteDocument do usuwania i renameDocument do zmiany nazwy. Te metody wymagają flagi FLAG_SUPPORTS_CREATE w korzeniu.

Rejestracja dostawcy w AndroidManifest

DocumentProvider jest rejestrowany w AndroidManifest.xml jako zwykły ContentProvider z dodatkowym intent-filter i flagami. Dostawca musi być chroniony przed bezpośrednim dostępem przez permission — zaleca się użycie android:exported="true" z jawnym permission.

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

Flaga grantUriPermissions pozwala SAF tymczasowo delegować prawa dostępu wywołującej aplikacji. Atrybut authorities musi być unikalny — zwykle używa się nazwy pakietu z sufiksem .documents. Zaleca się również określenie meta-data z zasobem XML do konfiguracji korzeni.

Przykład kodu: implementacja DocumentsProvider

Implementacja DocumentsProvider wymaga zwrócenia ParcelFileDescriptor z metody openDocument. Dla plików lokalnych używa się ParcelFileDescriptor.open, dla chmurowych — ParcelFileDescriptor.open z Pipe do przesyłania strumieniowego. Kod musi obsługiwać błędy dostępu i braku plików.

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

Obsługa wirtualnych dokumentów

DocumentProvider może zwracać wirtualne pliki — dokumenty, które nie istnieją jako osobne pliki na dysku. Na przykład notatka z bazy danych może być przedstawiona jako wirtualny PDF. W tym celu używa się typu MIME z flagą FLAG_VIRTUAL_DOCUMENT, a openDocument konwertuje dane do wymaganego formatu przed wysłaniem.

DocumentProvider w iOS: UIDocumentPickerViewController

iOS ma podobny mechanizm — UIDocumentPickerViewController, który również zapewnia jednolity interfejs wyboru plików. Jednak w iOS dostawca dokumentów jest implementowany przez UIDocumentPickerDelegate i rozszerzenia aplikacji (App Extensions) z typem Document Provider.

W przeciwieństwie do Android DocumentsProvider, iOS UIDocumentPickerViewController nie wymaga tworzenia niestandardowego dostawcy dla plików lokalnych — systemowy selektor obsługuje iCloud Drive i lokalne magazyny domyślnie. Zewnętrzne usługi w chmurze rejestrują się przez Document Provider extension z kluczem Info.plist NSExtensionFileProviderDocumentInterface.

Główna różnica: w Android DocumentProvider jest aktywnie wywoływany przez SAF Intent i musi sam zaimplementować nawigację. W iOS UIDocumentPickerViewController używa wbudowanej systemowej przeglądarki plików, a rozszerzenie dostawcy odpowiada tylko za dostarczanie treści na żądanie.