Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

Criação de um Provedor de Conteúdo

O provedor de conteúdo gerencia o acesso a um repositório central de dados. Implementa-se um provedor como uma ou mais classes em um aplicativo do Android, em conjunto com elementos no arquivo de manifesto. Uma das classes implementa uma subclasse ContentProvider, que é a interface entre o provedor e outros aplicativos. Embora provedores de conteúdo se destinem a disponibilizar dados a outros aplicativos, naturalmente é possível ter atividades no aplicativo que permitam ao usuário consultar e modificar os dados gerenciados pelo provedor.

O restante deste tópico é uma lista básica de etapas para a criação de um provedor de conteúdo e uma lista de APIs para usar.

Antes de começar a criar

Antes de começar a criar um provedor, faça o seguinte:

  1. Avalie se você precisa de um provedor de conteúdo. É necessário criar um provedor de conteúdo para fornecer um ou mais dos recursos a seguir:
    • Oferecer dados ou arquivos complexos a outros aplicativos.
    • Permitir que usuários copiem dados complexos do seu aplicativo para outros aplicativos.
    • Fornecer sugestões de pesquisa personalizada usando a estrutura de pesquisa.

    Não é necessário um provedor para usar um banco de dados SQLite se o uso for inteiramente dentro do próprio aplicativo.

  2. Se você ainda não tiver feito isso, leia o tópico Fundamentos do provedor de conteúdo para saber mais sobre provedores.

A seguir, siga estas etapas para criar seu provedor:

  1. Projete o armazenamento bruto dos dados. Os provedores de conteúdo oferecem dados de duas maneiras:
    Dados de arquivo
    Dados que normalmente transitam em arquivos, como fotos, áudio ou vídeos. Armazene os arquivos no espaço privado do seu aplicativo. Em resposta a uma solicitação de um arquivo por outro aplicativo, o provedor pode oferecer um identificador para o arquivo.
    Dados "estruturados"
    Dados que normalmente transitam em um banco de dados, uma matriz ou estrutura similar. Armazene os dados de forma compatível com tabelas de linhas e colunas. Cada linha representa uma entidade, como uma pessoa ou um item em um inventário. Cada coluna representa alguns dados da entidade, como o nome da pessoa ou o preço do item. Um modo comum de armazenar esse tipo de dados é em um banco de dados SQLite, mas é possível usar qualquer tipo de armazenamento persistente. Para saber mais sobre os tipos de armazenamento disponíveis no sistema Android, consulte a seção Projeto de armazenamento de dados.
  2. Defina uma implementação sólida da classe ContentProvider e seus métodos obrigatórios. Essa classe é a interface entre seus dados e o restante do sistema Android. Para obter mais informações sobre essa classe, consulte a seção Implementação da classe ContentProvider.
  3. Defina a string de autoridade do provedor, as URIs de conteúdo e os nomes de coluna. Se você deseja que o aplicativo do provedor processe intents, defina também ações de intent, dados extras e sinalizadores. Também defina as permissões necessárias para aplicativos que queiram acessar seus dados. Deve-se considerar definir todos esses valores como constantes em uma classe de contrato separada; posteriormente, será possível expor essa classe a outros desenvolvedores. Para obter mais informações sobre URIs de conteúdo, consulte a seção Projeto de URIs de conteúdo. Para obter mais informações sobre intents, consulte a seção Intents e acesso a dados.
  4. Adicione outras partes opcionais, como dados de exemplo ou uma implementação de AbstractThreadedSyncAdapter que possa sincronizar dados entre o provedor e os dados com base em nuvem.

Projeto de armazenamento de dados

Os provedores de conteúdo são a interface para dados salvos em um formato estruturado. Antes de criar a interface, é preciso decidir como armazenar os dados. É possível armazená-los da forma que quiser e, em seguida, projetar a interface para ler e gravar os dados conforme o necessário.

Estas são algumas das tecnologias de armazenamento de dados disponíveis no Android:

  • O sistema Android contém uma API de banco de dados SQLite que os provedores do Android usam para armazenar dados orientados a tabela. A classe SQLiteOpenHelper ajuda a criar bancos de dados e a classe SQLiteDatabase é a classe de base para acessar bancos de dados.

    Lembre-se de que não é necessário usar nenhum banco de dados para implementar o repositório. Um provedor aparece externamente como um conjunto de tabelas, semelhante a um banco de dados relacional, mas isso não é um requisito para a implementação interna do provedor.

  • Para armazenar dados de arquivos, o Android tem diversas APIs orientadas a arquivo. Para saber mais sobre armazenamento de arquivos, leia o tópico Armazenamento de dados. Se você estiver projetando um provedor que oferece dados relacionados a mídia como música ou vídeos, é possível ter um provedor que combine dados de tabela e de arquivos.
  • Para trabalhar com dados em rede, use classes em java.net e em android.net. É possível, também, sincronizar dados em rede com um armazenamento local de dados, como um banco de dados, e, em seguida, fornecer os dados na forma de tabelas ou arquivos. O exemplo de aplicativo Exemplo de adaptador de sincronização demonstra o tipo de sincronização.

Considerações para projetar dados

Eis algumas dicas para projetar a estrutura de dados do seu provedor:

  • Os dados de tabela sempre devem ter uma coluna de "chave principal" que o provedor mantém como um valor numérico exclusivo para cada linha. É possível usar esse valor para vincular a linha a linhas relacionadas em outras tabelas (usando-o como uma "chave externa"). Embora seja possível usar qualquer nome para essa coluna, é melhor usar BaseColumns._ID porque a vinculação dos resultados de uma consulta de provedor com uma ListView requer que uma das colunas tenha o nome _ID.
  • Se você deseja fornecer imagens bitmap ou outras partes muito grandes de dados orientados a arquivo, armazene os dados em um arquivo e, em seguida, forneça-o indiretamente em vez de armazená-lo diretamente em uma tabela. Ao fazer isso, será necessário informar aos usuários do provedor que eles precisam usar um método de arquivo ContentResolver para acessar os dados.
  • Use objeto grande binário (BLOB) como tipo de dados para armazenar dados que variam em tamanho ou que tenham estrutura variável. Por exemplo, é possível usar uma coluna de BLOB para armazenar um buffer de protocolo ou uma estrutura JSON.

    Pode-se usar um BLOB para implementar uma tabela independente de esquema. Nesse tipo de tabela, define-se uma coluna de chave principal, uma coluna de tipo MIME e uma ou mais colunas genéricas como BLOB. O significado dos dados nas colunas BLOB é indicado pelo valor na coluna de tipo MIME. Isso permite o armazenamento de diferentes tipos de linha na mesma tabela. A tabela de "dados" ContactsContract.Data do Provedor de contatos é um exemplo de uma tabela independente de esquema.

Projeto de URIs de conteúdo

URI de conteúdo é uma URI que identifica dados em um provedor. URIs de conteúdo contêm o nome simbólico de todo o provedor (sua autoridade) e um nome que aponta para uma tabela ou arquivo (um caminho). Parte do ID opcional aponta para uma linha individual em uma tabela. Cada método de acesso aos dados ContentProvider tem uma URI de conteúdo como um argumento. Isso permite determinar a tabela, a linha ou o arquivo a acessar.

Os conceitos básicos de URIs de conteúdo são escritos no tópico Fundamentos do provedor de conteúdo.

Projeto de uma autoridade

Os provedores normalmente têm uma única autoridade, que serve como seu nome interno do Android. Para evitar conflitos com outros provedores, deve-se usar a propriedade de domínio da internet (ao contrário) como a base da autoridade do provedor. Em virtude de essa recomendação ser verdadeira para nomes de pacote do Android, é possível definir a autoridade do provedor como uma extensão do nome do pacote que contém o provedor. Por exemplo, se o nome do pacote do Android for com.example.<appname>, deve-se atribuir ao provedor a autoridade com.example.<appname>.provider.

Projeto de uma estrutura de caminho

Desenvolvedores normalmente criam URIs de conteúdo a partir da autoridade anexando caminhos que apontam para tabelas individuais. Por exemplo, se você tiver duas tabelas (tabela1 e tabela2), combine a autoridade do exemplo anterior para produzir as URIs de conteúdo com.example.<appname>.provider/table1 e com.example.<appname>.provider/table2. Caminhos não se limitam a um único segmento e não precisam ter uma tabela para cada nível do caminho.

Identificação de IDs de URIs de conteúdo

Por convenção, provedores fornecem acesso a uma linha exclusiva em uma tabela aceitando uma URI de conteúdo com um valor de ID para a linha no fim da URI. Também por convenção, provedores combinam o valor do ID com a coluna _ID da tabela e realizam o acesso solicitado na linha correspondente.

Essa convenção facilita um padrão comum de projeto para aplicativos que acessam um provedor. O aplicativo realiza uma consulta no provedor e exibe o Cursor resultante em uma ListView usando um CursorAdapter. A definição de CursorAdapter requer que uma das colunas no Cursor seja _ID

Em seguida, o usuário seleciona uma das linhas exibidas na IU para visualizar ou modificar os dados. O aplicativo tem a linha correspondente do Cursor apoiando a ListView, obtém o valor _ID para essa linha, anexa-o à URI de conteúdo e envia a solicitação de acesso ao provedor. O provedor, então, pode realizar a consulta ou modificação na exata linha que o usuário selecionou.

Padrões de URI de conteúdo

Para ajudar a escolher que ação tomar para uma URI de conteúdo recebida, a API do provedor contém a classe de conveniência UriMatcher, que mapeia "padrões" de URI de conteúdo como valores de número inteiro. É possível usar os valores de número inteiro em uma declaração switch que escolha a ação desejada para a URI de conteúdo ou URIs que atendam ao padrão determinado.

Um padrão de URI de conteúdo corresponde a URIs de conteúdo que usam caracteres especiais:

  • *: Corresponde a uma string de qualquer caractere válido de qualquer comprimento.
  • #: Corresponde a uma string de caracteres numéricos de qualquer comprimento.

Como um exemplo de projeto e codificação da identificação de URIs de conteúdo, considere um provedor com a autoridade com.example.app.provider que reconheça as URIs de conteúdo que apontam para tabelas:

  • content://com.example.app.provider/table1: Uma tabela chamada table1.
  • content://com.example.app.provider/table2/dataset1: Uma tabela chamada dataset1.
  • content://com.example.app.provider/table2/dataset2: Uma tabela chamada dataset2.
  • content://com.example.app.provider/table3: Uma tabela chamada table3.

O provedor também reconhecerá essas URIs de conteúdo se elas tiverem um ID de linha anexado, como content://com.example.app.provider/table3/1 para a linha identificada por 1 em table3.

Os seguintes padrões de URI de conteúdo seriam possíveis:

content://com.example.app.provider/*
Corresponde a qualquer URI de conteúdo no provedor.
content://com.example.app.provider/table2/*:
Corresponde a uma URI de conteúdo das tabelas dataset1 e dataset2, mas não a URIs de conteúdo de table1 nem table3.
content://com.example.app.provider/table3/#: Corresponde a uma URI de conteúdo para linhas exclusivas em table3, como content://com.example.app.provider/table3/6 da linha identificada por 6.

O snippet de código a seguir mostra como funcionam os métodos em UriMatcher. Esse código identifica URIs para toda uma tabela, diferentemente das URIs para uma linha exclusiva, usando o padrão de URI de conteúdo content://<authority>/<path> para tabelas e content://<authority>/<path>/<id> para linhas exclusivas.

O método addURI() mapeia uma autoridade e um caminho como um valor de número inteiro. O método match() retorna o valor inteiro de uma URI. Uma declaração switch escolhe entre consultar a tabela inteira e consultar um único registro:

public class ExampleProvider extends ContentProvider {
...
    // Creates a UriMatcher object.
    private static final UriMatcher sUriMatcher = new UriMatcher(UriMatcher.NO_MATCH);

    static {
        /*
         * The calls to addURI() go here, for all of the content URI patterns that the provider
         * should recognize. For this snippet, only the calls for table 3 are shown.
         */

        /*
         * Sets the integer value for multiple rows in table 3 to 1. Notice that no wildcard is used
         * in the path
         */
        sUriMatcher.addURI("com.example.app.provider", "table3", 1);

        /*
         * Sets the code for a single row to 2. In this case, the "#" wildcard is
         * used. "content://com.example.app.provider/table3/3" matches, but
         * "content://com.example.app.provider/table3 doesn't.
         */
        sUriMatcher.addURI("com.example.app.provider", "table3/#", 2);
    }
...
    // Implements ContentProvider.query()
    public Cursor query(
        Uri uri,
        String[] projection,
        String selection,
        String[] selectionArgs,
        String sortOrder) {
...
        /*
         * Choose the table to query and a sort order based on the code returned for the incoming
         * URI. Here, too, only the statements for table 3 are shown.
         */
        switch (sUriMatcher.match(uri)) {


            // If the incoming URI was for all of table3
            case 1:

                if (TextUtils.isEmpty(sortOrder)) sortOrder = "_ID ASC";
                break;

            // If the incoming URI was for a single row
            case 2:

                /*
                 * Because this URI was for a single row, the _ID value part is
                 * present. Get the last path segment from the URI; this is the _ID value.
                 * Then, append the value to the WHERE clause for the query
                 */
                selection = selection + "_ID = " uri.getLastPathSegment();
                break;

            default:
            ...
                // If the URI is not recognized, you should do some error handling here.
        }
        // call the code to actually do the query
    }

Outra classe, ContentUris, fornece métodos convenientes para trabalhar com a parte id das URIs de conteúdo. As classes Uri e Uri.Builder contêm métodos convenientes para analisar objetos Uri existentes e criar novos.

Implementação da classe ContentProvider

A instância ContentProvider gerencia o acesso a um conjunto de dados estruturado lidando com solicitações de outros aplicativos. Todas as formas de acesso ocasionalmente chamam ContentResolver que, em seguida, chama um método concreto de ContentProvider para obter acesso.

Métodos obrigatórios

A classe abstrata ContentProvider define seis métodos abstratos que devem ser implementados como parte das subclasses concretas. Todos esses métodos, exceto onCreate(), são chamados por um aplicativo cliente que está tentando acessar seu provedor de conteúdo:

query()
Recupere dados do provedor. Use os argumentos para selecionar a tabela para consultar as linhas e colunas a retornar e a ordem de classificação do resultado. Retorne os dados como um objeto Cursor.
insert()
Insira uma nova linha no provedor. Use os argumentos para selecionar a tabela de destino e obter os valores de coluna a usar. Retorne uma URI de conteúdo para a linha recentemente inserida.
update()
Atualize as linhas existentes no provedor. Use os argumentos para selecionar a tabela e linhas para atualizar e obter os valores de coluna atualizados. Retorne o número de linhas atualizadas.
delete()
Exclua linhas do provedor. Use os argumentos para selecionar a tabela e as linhas a excluir. Retorne o número de linhas excluídas.
getType()
Retorne o tipo MIME correspondente a uma URI de conteúdo. Esse método é descrito com mais detalhes na seção Implementação de tipos MIME do Provedor de Conteúdo.
onCreate()
Inicialize o provedor. O sistema Android chama esse método imediatamente após criar o provedor. Observe que o provedor não é criado até que um objeto ContentResolver tente acessá-lo.

Observe que esses métodos têm a mesma assinatura dos métodos ContentResolver de mesmo nome.

A implementação desses métodos deve levar em conta o seguinte:

  • Todos esses métodos, exceto onCreate(), podem ser chamados por diversos encadeamentos simultaneamente, portanto, devem ter encadeamento seguro. Para saber mais sobre vários encadeamentos, consulte o tópico Processos e encadeamentos.
  • Evite realizar longas operações em onCreate(). Adie tarefas de inicialização até que sejam realmente necessárias. A seção Implementação do método onCreate() aborda o assunto mais detalhadamente.
  • Embora seja preciso implementar esses métodos, o código não precisa fazer nada além de retornar o tipo de dados esperado. Por exemplo, você pode querer evitar que outros aplicativos insiram dados em algumas tabelas. Para tanto, pode-se ignorar a chamada de insert() e retornar 0.

Implementação do método query()

O método ContentProvider.query() precisa retornar um objeto Cursor ou, se falhar, gerar uma Exception. Se você estiver usando um banco de dados SQLite como armazenamento de dados, pode simplesmente retornar o Cursor retornado por um dos métodos query() da classe SQLiteDatabase. Se a consulta não corresponder a nenhuma linha, deve-se retornar uma instância de Cursor cujo método getCount() retorne 0. Retorne null somente se ocorrer um erro interno durante o processo de consulta.

Se você não estiver usando um banco de dados SQLite como modo de armazenamento de dados, use uma das subclasses concretas de Cursor. Por exemplo, a classe MatrixCursor implementa um cursor em que cada linha é uma matriz de Object. Com essa classe, use addRow() para adicionar uma nova linha.

Lembre-se de que o sistema Android deve ser capaz de se comunicar com Exception entre limites de processo. O Android pode fazer isso para as exceções a seguir, que podem ser úteis para processar erros de consulta:

Implementação do método insert()

O método insert() adiciona uma nova linha à tabela apropriada usando os valores no argumento ContentValues. Se um nome de coluna não estiver no argumento ContentValues, talvez seja necessário fornecer um valor padrão para ele tanto no código do provedor quanto no esquema do banco de dados.

Esse método deve retornar a URI de conteúdo da nova linha. Para construir isso, anexe o valor _ID da nova linha (ou outra chave principal) à URI de conteúdo da tabela usando withAppendedId().

Implementação do método delete()

O método delete() não precisa excluir linhas fisicamente do armazenamento de dados. Se você estiver usando um adaptador de sincronização com o provedor, considere marcar uma linha excluída com um sinalizador "excluir" em vez de removê-la totalmente. O adaptador de sincronização pode verificar se há linhas excluídas e removê-las do servidor antes de excluí-las do provedor.

Implementação do método update()

O método update() usa o mesmo argumento ContentValues usado por insert() e os mesmos argumentos selection e selectionArgs usados por delete() e ContentProvider.query(). Isso deve permitir a reutilização do código entre esses métodos.

Implementação do método onCreate()

O sistema Android chama onCreate() quando inicia o provedor. Nesse método, devem-se realizar apenas tarefas de inicialização de execução rápida e adiar a criação do banco de dados e o carregamento dos dados até que o provedor receba efetivamente uma solicitação de acesso aos dados. Se houver tarefas longas em onCreate(), a inicialização do provedor ficará lenta. Consequentemente, isso diminuirá a rapidez da resposta do provedor a outros aplicativos.

Por exemplo, se você está usando um banco de dados SQLite, é possível criar um novo objeto SQLiteOpenHelper em ContentProvider.onCreate() e, em seguida, criar as tabelas SQL na primeira vez em que o banco de dados for aberto. Para facilitar isso, a primeira vez que chamar getWritableDatabase(), ele automaticamente chamará o método SQLiteOpenHelper.onCreate()

Os dois snippets a seguir demonstram a interação entre ContentProvider.onCreate() e SQLiteOpenHelper.onCreate(). O primeiro snippet é a implementação de ContentProvider.onCreate().

public class ExampleProvider extends ContentProvider

    /*
     * Defines a handle to the database helper object. The MainDatabaseHelper class is defined
     * in a following snippet.
     */
    private MainDatabaseHelper mOpenHelper;

    // Defines the database name
    private static final String DBNAME = "mydb";

    // Holds the database object
    private SQLiteDatabase db;

    public boolean onCreate() {

        /*
         * Creates a new helper object. This method always returns quickly.
         * Notice that the database itself isn't created or opened
         * until SQLiteOpenHelper.getWritableDatabase is called
         */
        mOpenHelper = new MainDatabaseHelper(
            getContext(),        // the application context
            DBNAME,              // the name of the database)
            null,                // uses the default SQLite cursor
            1                    // the version number
        );

        return true;
    }

    ...

    // Implements the provider's insert method
    public Cursor insert(Uri uri, ContentValues values) {
        // Insert code here to determine which table to open, handle error-checking, and so forth

        ...

        /*
         * Gets a writeable database. This will trigger its creation if it doesn't already exist.
         *
         */
        db = mOpenHelper.getWritableDatabase();
    }
}

O próximo snippet é a implementação de SQLiteOpenHelper.onCreate(), inclusive uma classe auxiliar:

...
// A string that defines the SQL statement for creating a table
private static final String SQL_CREATE_MAIN = "CREATE TABLE " +
    "main " +                       // Table's name
    "(" +                           // The columns in the table
    " _ID INTEGER PRIMARY KEY, " +
    " WORD TEXT"
    " FREQUENCY INTEGER " +
    " LOCALE TEXT )";
...
/**
 * Helper class that actually creates and manages the provider's underlying data repository.
 */
protected static final class MainDatabaseHelper extends SQLiteOpenHelper {

    /*
     * Instantiates an open helper for the provider's SQLite data repository
     * Do not do database creation and upgrade here.
     */
    MainDatabaseHelper(Context context) {
        super(context, DBNAME, null, 1);
    }

    /*
     * Creates the data repository. This is called when the provider attempts to open the
     * repository and SQLite reports that it doesn't exist.
     */
    public void onCreate(SQLiteDatabase db) {

        // Creates the main table
        db.execSQL(SQL_CREATE_MAIN);
    }
}

Implementação de tipos MIME de ContentProvider

A classe ContentProvider tem dois métodos para retornar tipos MIME:

getType()
Um dos métodos obrigatórios que devem ser implementados em qualquer provedor.
getStreamTypes()
Um método que deve ser implementado se o provedor fornecer arquivos.

Tipos MIME para tabelas

O método getType() retorna uma String em formato MIME que descreve o tipo de dados retornado pelo argumento da URI de conteúdo. O argumento Uri pode ser um padrão em vez de uma URI específica; nesse caso, deve-se retornar o tipo de dados associado a URIs de conteúdo que correspondam ao padrão.

Para tipos de dados comuns como texto, HTML ou JPEG, getType() deve retornar o tipo MIME padrão daqueles dados. Há uma lista completa desse tipos de padrão no site de Tipos de mídia MIME IANA.

Para obter URIs de conteúdo que apontam para uma linha ou linhas de dados de tabela, getType() deve retornar um tipo MIME no formato MIME específico do fornecedor do Android:

  • Parte do tipo: vnd
  • Parte do subtipo:
    • Se um padrão de URI se destinar a uma única linha: android.cursor.item/
    • Se um padrão de URI se destinar a mais de uma linha: android.cursor.dir/
  • Parte específica do provedor: vnd.<name>.<type>

    Fornecem-se <name> e o <type>. O valor <name> deve ser globalmente exclusivo e o <type> deve ser exclusivo para o padrão de URI correspondente. Uma boa escolha para <name> é o nome da empresa ou alguma parte do nome do pacote do Android do seu aplicativo. Uma boa escolha para <type> é uma string que identifique a tabela associada à URI.

Por exemplo, se a autoridade de um provedor for com.example.app.provider e ele expuser uma tabela chamada table1, o tipo MIME de diversas linhas em table1 será:

vnd.android.cursor.dir/vnd.com.example.provider.table1

Para uma única linha de table1, o tipo MIME será:

vnd.android.cursor.item/vnd.com.example.provider.table1

Tipos MIME para arquivos

Se o provedor oferecer arquivos, implemente getStreamTypes(). O método retorna uma matriz String de tipos MIME para os arquivos que o provedor pode retornar de uma dada URI de conteúdo É preciso filtrar os tipos MIME oferecidos pelo argumento do filtro de tipo MIME para retornar somente os tipos MIME que o cliente quer processar.

Por exemplo, considere um provedor que ofereça imagens de foto como arquivos em formatos .jpg, .gif e .png. Se um aplicativo chama ContentResolver.getStreamTypes() com a string de filtro image/* (algo que seja uma "imagem"), o método ContentProvider.getStreamTypes() deve retornar a matriz:

{ "image/jpeg", "image/png", "image/gif"}

Se o aplicativo estiver interessado apenas em arquivos .jpg, ele pode chamar ContentResolver.getStreamTypes() com a string de filtro *\/jpeg e ContentProvider.getStreamTypes() deve retornar:

{"image/jpeg"}

Se o provedor não oferecer nenhum tipo MIME solicitado na string de filtro, getStreamTypes() deverá retornar null.

Implementação de uma classe de contrato

Uma classe de contrato é uma classe public final que contém definições de constantes para os nomes de coluna das URIs, dos tipos MIME e de outros metadados que pertencem ao provedor. A classe estabelece um contrato entre o provedor e outros aplicativos, garantindo que o provedor possa ser corretamente acessado mesmo se houver mudanças nos valores atuais de URIs, nomes de coluna etc.

As classes de contrato também ajudam os desenvolvedores porque normalmente suas constantes têm nomes mnemônicos e, por isso, os desenvolvedores têm menos chance de usar valores incorretos para nomes de coluna ou URIs. Já que é uma classe, ela pode conter documentação Javadoc. Ambientes de desenvolvimento integrados, como o Android Studio, podem preencher automaticamente o nome de constantes da classe de contrato e exibir Javadoc para elas.

Os desenvolvedores não podem acessar o arquivo de classe da classe de contrato do aplicativo, mas podem compilá-lo estaticamente no aplicativo a partir de um arquivo .jar que você fornece.

A classe ContactsContract e classes aninhadas são exemplos de classes de contrato.

Implementação de permissões do Provedor de Conteúdo

Permissões e acesso, para todos os aspectos do sistema Android, são descritos detalhadamente no tópico Permissões e segurança. O tópico Armazenamento de dados também descreve segurança e permissões em vigor para diversos tipos de armazenamento. Em resumo, os pontos importantes são:

  • Por padrão, arquivos de dados armazenados no armazenamento interno do dispositivo são privados em relação ao aplicativo e ao provedor.
  • Os bancos de dados SQLiteDatabase criados são privados em relação ao aplicativo e ao provedor.
  • Por padrão, arquivos de dados salvos em armazenamentos externos são públicos e legíveis para todos. Não é possível usar um provedor de conteúdo para restringir o acesso a arquivos em um armazenamento externo porque outros aplicativos podem usar outras chamadas de API para lê-los e gravar neles.
  • O método que chama a abertura ou criação de arquivos ou bancos de dados SQLite no armazenamento interno do seu dispositivo pode fornecer acesso de leitura e gravação a todos os outros aplicativos. Se você usar um arquivo ou banco de dados interno como o repositório do provedor e conceder-lhe acesso "legível para todos" ou "gravável por todos", as permissões definidas para o provedor no manifesto não protegerão os dados. O acesso padrão de arquivos e bancos de dados no armazenamento interno é "privado" e, para o repositório do provedor, não é recomendável alterar isso.

Se você deseja usar permissões do provedor de conteúdo para controlar o acesso aos dados, deve armazená-los em arquivos internos, bancos de dados SQLite ou em "nuvem" (por exemplo, em um servidor remoto) e mantê-los privados em relação ao aplicativo.

Implementação de permissões

Todos os aplicativos podem ler ou gravar no provedor, mesmo que os dados em questão sejam privados porque, por padrão, o provedor não tem permissões definidas. Para mudar isso, defina permissões do provedor no arquivo de manifesto por meio de atributos ou elementos filhos do elemento <provider>. É possível definir permissões que se apliquem a todo o provedor, a determinadas tabelas, a registros específicos ou a todos os três.

As permissões são definidas para o provedor com um ou mais elementos <permission> no arquivo de manifesto. Para tornar a permissão exclusiva para o provedor, use escopo de estilo Java para o atributo android:name. Por exemplo, nomeie a permissão de leitura com.example.app.provider.permission.READ_PROVIDER.

A lista a seguir descreve o escopo de permissões do provedor, começando com as permissões que se aplicam a todo o provedor e seguindo para as mais específicas. Permissões mais específicas têm precedência sobre as de escopo maior:

Única permissão de leitura e gravação no nível do provedor
Uma permissão que controla os acessos de leitura e gravação a todo o provedor, especificada com o atributo android:permission do elemento <provider>.
Permissões de leitura e gravação separadas no nível do provedor
Uma permissão de leitura e uma permissão de gravação para todo o provedor. São especificadas com os atributos android:readPermission e android:writePermission do elemento <provider>. Elas têm precedência sobre a permissão exigida por android:permission.
Permissão no nível do caminho
Permissão de leitura, gravação ou leitura/gravação para uma URI de conteúdo no provedor. Especifica-se cada URI que se deseja controlar com um elemento filho <path-permission> do elemento <provider>. Para cada URI de conteúdo, pode-se especificar uma permissão de leitura/gravação, uma permissão de leitura, uma permissão de gravação ou as três. As permissões de leitura e gravação têm precedência sobre a permissão de leitura/gravação. Além disso, permissões no nível do caminho têm precedência sobre permissões no nível do provedor.
Permissão temporária
Nível de permissão que concede acesso temporário a um aplicativo mesmo que ele não tenha as permissões normalmente exigidas. O recurso de acesso temporário reduz o número de permissões que um aplicativo deve solicitar no manifesto. Ao ativar permissões temporárias, os únicos aplicativos que precisam de permissões "permanentes" para seu provedor são os que têm acesso contínuo a todos os dados.

Considere as permissões necessárias para implementar um provedor e um aplicativo de e-mail ao permitir que um aplicativo visualizador de imagens externas exiba anexos de fotos do provedor. Para conceder o acesso necessário ao visualizador de imagens sem as permissões exigidas, configure permissões temporárias das URIs de conteúdo de fotos. Projete o aplicativo de e-mail para que, quando o usuário quiser exibir uma foto, o aplicativo envie um intent com a URI de conteúdo da foto e sinalizadores de permissão para o visualizador de imagens. O visualizador de imagens poderá, então, consultar o provedor de e-mail para recuperar a foto mesmo que ele não tenha a permissão normal de leitura para o provedor.

Para ativar permissões temporárias, defina o atributo android:grantUriPermissions do elemento <provider> ou adicione um ou mais elementos filhos <grant-uri-permission> ao elemento <provider>. Se forem usadas permissões temporárias, será necessário chamar Context.revokeUriPermission() sempre que você remover suporte a URI de conteúdo do provedor e a URI de conteúdo será associada a uma permissão temporária.

O valor do atributo determina o nível de acessibilidade do provedor. Se o atributo estiver definido como true, o sistema concederá permissão temporária a todo o provedor, sobrepondo todas as outras permissões exigidas pelas permissões no nível do provedor ou no nível do caminho.

Se esse sinalizador estiver definido como false, será necessário adicionar elementos filhos <grant-uri-permission> ao elemento <provider>. Cada elemento filho especifica a URI ou URIs de conteúdo para as quais o acesso temporário é concedido.

Para delegar o acesso temporário a um aplicativo, o intent deve conter os sinalizadores FLAG_GRANT_READ_URI_PERMISSION, FLAG_GRANT_WRITE_URI_PERMISSION ou ambos. Eles são definidos com o método setFlags().

Se o atributo android:grantUriPermissions não estiver presente, presume-se que ele seja false.

O elemento <provider>

Como os componentes Activity e Service, a subclasse de ContentProvider deve ser definida no arquivo de manifesto do aplicativo pelo elemento <provider>. O sistema Android obtém as seguintes informações do elemento:

Autoridade (android:authorities)
Nomes simbólicos que identificam todo o provedor dentro do sistema. Esse atributo é descrito com mais detalhes na seção Projeto de URIs de conteúdo.
Nome da classe do provedor ( android:name )
A classe que implementa ContentProvider. Essa classe é abordada com mais detalhes na seção Implementação da classe ContentProvider.
Permissões
Atributos que especificam as permissões que outros aplicativos precisam ter para acessar os dados do provedor:

As permissões e os atributos correspondentes são abordados com mais detalhes na seção Implementação de permissões do Provedor de conteúdo.

Atributos de início e controle
Esses atributos determinam como e quando o sistema Android inicia o provedor, as características do processo do provedor e outras configurações de tempo de execução:
  • android:enabled: Sinalizador que permite ao sistema iniciar o provedor.
  • android:exported: Sinalizador que permite a outros aplicativos usarem esse provedor.
  • android:initOrder: A ordem em que esse provedor deve ser iniciado, relativa a outros provedores no mesmo processo.
  • android:multiProcess: Sinalizador que permite ao sistema iniciar o provedor no mesmo processo que o cliente chama.
  • android:process: O nome do processo em que o provedor deve ser executado.
  • android:syncable: Sinalizador que indica que os dados do provedor devem ser sincronizados com os dados em um servidor.

Os atributos estão totalmente documentados no tópico do guia de desenvolvimento do elemento <provider>.

Atributos informacionais
Um ícone e um rótulo opcionais para o provedor:
  • android:icon: Um recurso desenhável contendo um ícone para o provedor. O ícone aparece próximo ao rótulo do provedor na lista de aplicativos em Settings > Apps > All.
  • android:label: Um rótulo informacional que descreve o provedor, seus dados ou ambos. O rótulo aparece na lista de aplicativos em Settings > Apps > All.

Os atributos estão totalmente documentados no tópico do guia de desenvolvimento do elemento <provider>.

Intents e acesso a dados

Os aplicativos podem acessar um provedor de conteúdo indiretamente com uma Intent. O aplicativo não chama nenhum método de ContentResolver nem de ContentProvider. Em vez disso, ele envia um intent que inicia uma atividade que, em geral, é parte do aplicativo do próprio provedor. A atividade de destino é responsável pela recuperação e exibição dos dados na IU. Dependendo da ação no intent, a atividade de destino também pode solicitar ao usuário que realize modificações nos dados do provedor. Um intent também pode conter dados "extras" que a atividade de destino exibe na IU; o usuário terá, então, a opção de alterar esses dados antes de usá-los para modificar os dados no provedor.

Pode ser necessário usar acesso de intents para ajudar a garantir a integridade dos dados. O provedor pode depender de ter dados inseridos, atualizados e excluídos de acordo com a lógica de negócio rigorosamente definida. Se for o caso, a permissão para que outros aplicativos modifiquem os dados diretamente pode levar à invalidação dos dados. Se você deseja que os desenvolvedores usem o acesso via intents, certifique-se de documentá-lo minuciosamente. Explique por que o acesso via intents pela IU do aplicativo é melhor do que tentar modificar os dados com códigos.

O processamento dos intents recebidas com a intenção de modificar os dados do provedor não é diferente de processar outros intents. Para saber mais sobre o uso de intents, leia o tópico Intents e filtros de intents.