DocumentProvider — o que é, criação de provedor e trabalho com arquivos

O que é DocumentProvider?

DocumentsProvider é uma classe base do Android que estende ContentProvider, permitindo que um aplicativo forneça seus arquivos a outros aplicativos através da interface SAF do sistema. O provedor cria um sistema de arquivos virtual que o usuário vê no diálogo de seleção de documentos.

Cada provedor organiza os arquivos em raízes (roots) — pontos de entrada de alto nível. Por exemplo, o Google Drive tem as raízes “Meu Drive” e “Compartilhado comigo.” Dentro de uma raiz, o provedor retorna uma árvore de documentos, onde cada documento é um arquivo ou diretório com um tipo MIME, tamanho e datas específicos.

DocumentProvider faz parte do pacote android.provider e está disponível a partir do Android 4.4 (API 19). O provedor é usado por serviços em nuvem, gerenciadores de senhas, aplicativos de notas e qualquer programa que armazene arquivos em seu próprio formato.

Como criar um DocumentProvider personalizado

Criar seu próprio DocumentProvider começa estendendo a classe DocumentsProvider e implementando quatro métodos obrigatórios. O provedor define a estrutura de arquivos que aparece no seletor SAF do sistema ao selecionar arquivos.

O primeiro método é queryRoots, que retorna um cursor com as colunas Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY e Root.COLUMN_FLAGS. Cada raiz pode suportar flags: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH e FLAG_SUPPORTS_IS_CHILD.

O segundo método obrigatório é queryChildDocuments, que retorna os documentos filhos de um URI especificado. Este método é chamado quando o usuário abre um diretório no seletor. Cada documento contém as colunas: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE e COLUMN_LAST_MODIFIED.

Métodos obrigatórios do DocumentsProvider

DocumentsProvider requer a implementação de quatro métodos que formam a estrutura de arquivos para o seletor. Sem eles, o provedor não funcionará — o diálogo SAF do sistema não conseguirá exibir arquivos.

• queryRoots — retorna os pontos de entrada raiz ao armazenamento. Cada raiz é representada por uma linha no cursor com um ID, nome e ícone.
• queryDocument — retorna um único documento pelo seu ID. Usado para obter informações sobre um arquivo específico.
• queryChildDocuments — retorna documentos filhos para o URI do diretório pai especificado.
• openDocument — abre um documento por ID e retorna um ParcelFileDescriptor para leitura ou escrita.

Adicionalmente, podem ser implementados createDocument para criar novos arquivos, deleteDocument para excluir e renameDocument para renomear. Estes métodos requerem a flag FLAG_SUPPORTS_CREATE na raiz.

Registro do provedor no AndroidManifest

DocumentProvider é registrado no AndroidManifest.xml como um ContentProvider normal com um filtro de intent e flags adicionais. O provedor deve ser protegido do acesso direto através de permissão — recomenda-se usar android:exported="true" com permissão explícita.

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

A flag grantUriPermissions permite que o SAF delegue temporariamente os direitos de acesso ao aplicativo solicitante. O atributo authorities deve ser único — geralmente usa-se o nome do pacote com o sufixo .documents. Também é recomendado especificar meta-data com um recurso XML para configurar as raízes.

Exemplo de código: implementação do DocumentsProvider

Implementar o DocumentsProvider requer retornar um ParcelFileDescriptor do método openDocument. Para arquivos locais usa-se ParcelFileDescriptor.open, para arquivos em nuvem — ParcelFileDescriptor.open com Pipe para transmissão em fluxo. O código deve tratar erros de acesso e arquivos ausentes.

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

Manipulação de documentos virtuais

DocumentProvider pode retornar arquivos virtuais — documentos que não existem como arquivos separados no disco. Por exemplo, uma nota de banco de dados pode ser apresentada como um PDF virtual. Isso usa um tipo MIME com a flag FLAG_VIRTUAL_DOCUMENT, e openDocument converte os dados para o formato solicitado antes do envio.

DocumentProvider no iOS: UIDocumentPickerViewController

iOS tem um mecanismo similar — UIDocumentPickerViewController, que também fornece uma interface unificada de seleção de arquivos. No entanto, no iOS o provedor de documentos é implementado através de UIDocumentPickerDelegate e Extensões de Aplicativo (App Extensions) do tipo Document Provider.

Ao contrário do Android DocumentsProvider, o iOS UIDocumentPickerViewController não requer criar um provedor personalizado para arquivos locais — o seletor do sistema suporta iCloud Drive e armazenamento local por padrão. Serviços em nuvem de terceiros se registram através de uma extensão Document Provider com a chave Info.plist NSExtensionFileProviderDocumentInterface.

A principal diferença: no Android, DocumentProvider é chamado ativamente através de um Intent SAF e deve implementar a navegação por si só. No iOS, UIDocumentPickerViewController usa um navegador de arquivos do sistema integrado, e o provedor de extensão é responsável apenas por fornecer conteúdo sob demanda.