DocumentProvider — cos'è, creazione di un fornitore e lavoro con i file

Cos'è DocumentProvider?

DocumentsProvider è una classe base Android che estende ContentProvider, consentendo a un'applicazione di fornire i propri file ad altre applicazioni tramite l'interfaccia SAF di sistema. Il fornitore crea un file system virtuale che l'utente vede nella finestra di dialogo di selezione dei documenti.

Ogni fornitore organizza i file in radici (roots) — punti di ingresso di alto livello. Ad esempio, Google Drive ha le radici “Il mio Drive” e “Condivisi con me.” All'interno di una radice, il fornitore restituisce un albero di documenti, dove ogni documento è un file o una directory con un tipo MIME, dimensione e date specifici.

DocumentProvider fa parte del pacchetto android.provider ed è disponibile a partire da Android 4.4 (API 19). Il fornitore è utilizzato da servizi cloud, gestori di password, app per appunti e qualsiasi programma che memorizzi file in un formato proprietario.

Come creare un DocumentProvider personalizzato

Creare il proprio DocumentProvider inizia estendendo la classe DocumentsProvider e implementando quattro metodi obbligatori. Il fornitore definisce la struttura dei file che appare nel selettore SAF di sistema durante la selezione dei file.

Il primo metodo è queryRoots, che restituisce un cursore con le colonne Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY e Root.COLUMN_FLAGS. Ogni radice può supportare flag: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH e FLAG_SUPPORTS_IS_CHILD.

Il secondo metodo obbligatorio è queryChildDocuments, che restituisce i documenti figli di un URI specificato. Questo metodo viene chiamato quando l'utente apre una directory nel selettore. Ogni documento contiene le colonne: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE e COLUMN_LAST_MODIFIED.

Metodi obbligatori di DocumentsProvider

DocumentsProvider richiede l'implementazione di quattro metodi che formano la struttura dei file per il selettore. Senza di essi, il fornitore non funzionerà — la finestra di dialogo SAF di sistema non potrà visualizzare i file.

• queryRoots — restituisce i punti di ingresso radice all'archiviazione. Ogni radice è rappresentata da una riga nel cursore con un ID, nome e icona.
• queryDocument — restituisce un singolo documento tramite il suo ID. Utilizzato per ottenere informazioni su un file specifico.
• queryChildDocuments — restituisce i documenti figli per l'URI della directory padre specificata.
• openDocument — apre un documento tramite ID e restituisce un ParcelFileDescriptor per lettura o scrittura.

Inoltre, è possibile implementare createDocument per creare nuovi file, deleteDocument per eliminare e renameDocument per rinominare. Questi metodi richiedono il flag FLAG_SUPPORTS_CREATE nella radice.

Registrazione del fornitore in AndroidManifest

DocumentProvider viene registrato in AndroidManifest.xml come un normale ContentProvider con un filtro intent aggiuntivo e flag. Il fornitore deve essere protetto dall'accesso diretto tramite permessi — si consiglia di utilizzare android:exported="true" con permesso esplicito.

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

Il flag grantUriPermissions consente a SAF di delegare temporaneamente i diritti di accesso all'applicazione chiamante. L'attributo authorities deve essere unico — di solito si utilizza il nome del pacchetto con il suffisso .documents. Si consiglia inoltre di specificare metadati con una risorsa XML per configurare le radici.

Esempio di codice: implementazione di DocumentsProvider

Implementare DocumentsProvider richiede la restituzione di un ParcelFileDescriptor dal metodo openDocument. Per i file locali si utilizza ParcelFileDescriptor.open, per i file cloud — ParcelFileDescriptor.open con Pipe per lo streaming. Il codice deve gestire errori di accesso e file mancanti.

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

Gestione dei documenti virtuali

DocumentProvider può restituire file virtuali — documenti che non esistono come file separati sul disco. Ad esempio, una nota del database può essere presentata come PDF virtuale. Questo utilizza un tipo MIME con il flag FLAG_VIRTUAL_DOCUMENT, e openDocument converte i dati nel formato richiesto prima dell'invio.

DocumentProvider in iOS: UIDocumentPickerViewController

iOS ha un meccanismo simile — UIDocumentPickerViewController, che fornisce anch'esso un'interfaccia unificata di selezione dei file. Tuttavia, in iOS il fornitore di documenti viene implementato tramite UIDocumentPickerDelegate ed estensioni dell'app (App Extensions) di tipo Document Provider.

A differenza di Android DocumentsProvider, iOS UIDocumentPickerViewController non richiede la creazione di un fornitore personalizzato per i file locali — il selettore di sistema supporta iCloud Drive e l'archiviazione locale per impostazione predefinita. I servizi cloud di terze parti si registrano tramite un'estensione Document Provider con la chiave Info.plist NSExtensionFileProviderDocumentInterface.

La differenza principale: in Android, DocumentProvider viene chiamato attivamente tramite un Intent SAF e deve implementare la navigazione da solo. In iOS, UIDocumentPickerViewController utilizza un browser di file di sistema integrato e il fornitore di estensione è responsabile solo di fornire contenuti su richiesta.