O Provedor de contatos é um componente avançado e flexível do Android que gerencia o repositório central de dados sobre pessoas no dispositivo. O Provedor de contatos é a fonte de dados que você vê no aplicativo de contatos do dispositivo. Também é possível acessar os dados no próprio aplicativo e transferir dados entre o dispositivo e serviços on-line. O provedor acomoda uma ampla variedade de fontes de dados e tenta gerenciar o máximo de dados possível para cada pessoa, o que torna a organização complexa. Por isso, a API do provedor inclui um conjunto extensivo de classes e interfaces de contrato que facilitam a recuperação e a modificação de dados.
Este guia descreve o seguinte:
- A estrutura básica do provedor.
- Como recuperar dados por um provedor.
- Como modificar dados no provedor.
- Como criar um adaptador de sincronização para sincronizar dados do servidor com o Provedor de contatos.
Este guia considera que o leitor conhece os fundamentos sobre provedores de conteúdo do Android. Para saber mais sobre provedores de conteúdo do Android, leia o guia Fundamentos do provedor de conteúdo.
Organização do Provedor de contatos
O Provedor de contatos é um componente do provedor de conteúdo do Android. Ele mantém três tipos de dados sobre uma pessoa, cada um deles correspondente a uma tabela oferecida pelo provedor, conforme ilustrado na figura 1:
![](https://developer.android.com/static/images/providers/contacts_structure.png?authuser=6&hl=pt)
Figura 1. Estrutura da tabela do Provedor de Contatos.
As três tabelas são comumente identificadas pelo nome de suas classes de contrato. As classes definem constantes para URIs de conteúdo e nomes e valores de colunas usados pelas tabelas:
-
ContactsContract.Contacts
tabela - As linhas representam pessoas diferentes, com base em agregações de linhas de contatos brutos.
-
ContactsContract.RawContacts
tabela - Linhas contendo um resumo dos dados de uma pessoa, específicos a uma conta e um tipo de usuário.
-
ContactsContract.Data
tabela - Linhas contendo os detalhes dos contatos brutos, como endereços de e-mail ou números de telefone.
As outras tabelas representadas por classes de contrato em ContactsContract
são tabelas auxiliares que o Provedor de contatos usa para gerenciar as operações ou oferecer suporte
a funções específicas nos contatos do dispositivo ou em aplicativos de telefonia.
Contatos brutos
Os contatos brutos representam os dados de uma pessoa provenientes de um tipo e um nome de conta únicos. Como o Provedor de contatos permite mais de um serviço on-line como fonte de dados de uma pessoa, ele permite vários contatos brutos para a mesma pessoa. Vários contatos brutos também permitem que um usuário combine os dados de uma pessoa de mais de uma conta com o mesmo tipo.
A maioria dos dados de um contato bruto não é armazenada na tabela ContactsContract.RawContacts
. Em vez disso, ele é armazenado em uma ou mais
linhas na tabela ContactsContract.Data
. Cada linha de dados tem uma coluna
Data.RAW_CONTACT_ID
que
contém o valor RawContacts._ID
da
linha mãe ContactsContract.RawContacts
.
Colunas importantes de contatos brutos
As colunas importantes da tabela ContactsContract.RawContacts
estão
listadas na tabela 1. Leia as observações que se seguem após a tabela:
Tabela 1. Importantes colunas de contatos brutos.
Nome da coluna | Uso | Observações |
---|---|---|
ACCOUNT_NAME
|
Nome da conta para o tipo de conta que é a fonte desse contato bruto.
Por exemplo, o nome de uma Conta do Google é um dos endereços do Gmail do proprietário do dispositivo. Consulte a próxima entrada de ACCOUNT_TYPE para mais informações.
|
O formato desse nome é específico deste tipo de conta. Não é necessariamente um endereço de e-mail. |
ACCOUNT_TYPE
|
O tipo de conta que é a fonte desse contato bruto. Por exemplo, o tipo de conta de uma Conta do Google é com.google . Sempre qualifique seu tipo de conta com um identificador de domínio para um domínio que você possui ou controla. Isso garante que seu tipo de conta seja exclusivo.
|
Um tipo de conta que oferece dados de contatos geralmente tem um adaptador de sincronização associado que sincroniza com o Provedor de contatos. |
DELETED
|
O flag "excluído" de um contato bruto. | Essa sinalização permite que o Provedor de contatos mantenha a linha internamente até que os adaptadores de sincronização possam excluí-la dos servidores e, em seguida, excluí-la do repositório. |
Observações
Veja a seguir observações importantes sobre a tabela ContactsContract.RawContacts
:
-
O nome de um contato bruto não é armazenado na linha dele em
ContactsContract.RawContacts
. Em vez disso, é armazenada na tabelaContactsContract.Data
, em uma linhaContactsContract.CommonDataKinds.StructuredName
. Um contato bruto tem apenas uma linha desse tipo na tabelaContactsContract.Data
. -
Cuidado:para usar os dados da sua conta em uma linha de contato bruto, ela precisa
ser registrada com o
AccountManager
. Para fazer isso, solicite que os usuários adicionem o tipo e o nome da conta à lista de contas. Se você não fizer isso, o Provedor de contatos vai excluir automaticamente a linha do contato bruto.Por exemplo, se você quiser que seu app mantenha dados de contatos do serviço baseado na Web com o domínio
com.example.dataservice
e a conta do usuário para o serviço forbecky.sharp@dataservice.example.com
, o usuário precisará primeiro adicionar o "tipo" (com.example.dataservice
) e o "nome" da conta (becky.smart@dataservice.example.com
) antes que o app possa adicionar linhas de contato bruto. Você pode explicar esse requisito ao usuário na documentação ou solicitar que ele adicione o tipo e o nome ou ambos. Tipos e nomes de conta são descritos em mais detalhes na próxima seção.
Fontes de dados de contatos brutos
Para entender como os contatos brutos funcionam, considere a usuária "Emily Dickinson", que tem estas três contas de usuário definidas no dispositivo:
emily.dickinson@gmail.com
emilyd@gmail.com
- Conta do Twitter "belle_of_amherst"
Este usuário ativou a opção Sincronizar contatos para as três contas nas configurações de Contas.
Suponha que Emily Dickinson abra uma janela do navegador, faça login no Gmail como
emily.dickinson@gmail.com
, abra
Contatos e adicione "Thomas Higginson". Mais tarde, ela faz login no Gmail como
emilyd@gmail.com
e envia um e-mail para "Thomas Higginson", o que o adiciona automaticamente
como um contato. Ela também segue "colonel_tom" (código do Twitter de Thomas Higginson) no
Twitter.
O Provedor de contatos cria três contatos brutos como resultado desse trabalho:
-
Um contato bruto de "Thomas Higginson" associado a
emily.dickinson@gmail.com
. O tipo de conta do usuário é Google. -
Um segundo contato bruto de "Thomas Higginson" associado a
emilyd@gmail.com
. O tipo da conta de usuário também é do Google. Há um segundo contato bruto, mesmo que o nome seja idêntico a um nome anterior, porque a pessoa foi adicionada a uma conta de usuário diferente. - Um terceiro contato bruto para "Thomas Higginson" associado a "belle_of_amherst". O tipo de conta de usuário é Twitter.
Dados
Conforme observado anteriormente, os dados de um contato bruto são armazenados em uma linha ContactsContract.Data
vinculada ao valor _ID
do contato bruto. Isso permite que um único contato bruto tenha várias instâncias do mesmo
tipo de dados, como endereços de e-mail ou números de telefone. Por exemplo, se
"Thomas Higginson" para emilyd@gmail.com
(a linha de contato bruto de Thomas Higginson
associada à Conta do Google emilyd@gmail.com
) tiver um endereço de e-mail residencial
thigg@gmail.com
e um endereço de e-mail comercial
thomas.higginson@gmail.com
, o Provedor de contatos armazenará as duas linhas de endereço
de e-mail e as vinculará ao contato bruto.
Diferentes tipos de dados são armazenados nessa única tabela. As linhas de nome de exibição,
número de telefone, e-mail, endereço postal, foto e detalhes do site são encontradas na
tabela ContactsContract.Data
. Para ajudar a gerenciar isso, a
tabela ContactsContract.Data
tem algumas colunas com nomes descritivos
e outras com nomes genéricos. O conteúdo de uma coluna de nome descritivo tem o mesmo significado, independentemente do tipo de dados da linha, enquanto o conteúdo de uma coluna de nome genérico tem significados diferentes dependendo do tipo de dados.
Nomes descritivos de colunas
Veja alguns exemplos de nomes descritivos de colunas:
-
RAW_CONTACT_ID
-
O valor da coluna
_ID
do contato bruto para esses dados. -
MIMETYPE
-
O tipo de dados armazenados nessa linha, expressos como um tipo MIME personalizado. O Provedor de contatos
usa os tipos MIME definidos nas subclasses de
ContactsContract.CommonDataKinds
. Esses tipos MIME são de código aberto e podem ser usados por qualquer aplicativo ou adaptador de sincronização que funcione com o Provedor de contatos. -
IS_PRIMARY
- Se esse tipo de linha de dados puder ocorrer mais de uma vez em um contato bruto, a coluna
IS_PRIMARY
sinalizará a linha de dados que contém os dados principais do tipo. Por exemplo, se o usuário tocar e manter pressionado um número de telefone de um contato e selecionar Definir padrão, a linhaContactsContract.Data
que contém esse número terá a colunaIS_PRIMARY
definida como um valor diferente de zero.
Nomes de colunas genéricas
Há 15 colunas genéricas chamadas de DATA1
a DATA15
que estão disponíveis no geral e outras quatro colunas genéricas de SYNC1
a SYNC4
que só precisam ser usadas por adaptadores de sincronização. As constantes de nome de coluna genérica sempre funcionam, independente do tipo de dados que a linha contenha.
A coluna DATA1
está indexada. O Provedor de contatos sempre usa essa coluna para
os dados que o provedor espera serem os alvos mais frequentes de uma consulta. Por exemplo,
em uma linha de e-mail, essa coluna contém o endereço de e-mail real.
Por convenção, a coluna DATA15
é reservada para armazenar dados de BLOBs (Binary Large Object), como miniaturas de fotos.
Nomes de coluna de tipo específico
Para facilitar o trabalho com as colunas para um tipo específico de linha, o Provedor de contatos
também fornece constantes de nome de coluna de tipos específicos, definidas em subclasses de
ContactsContract.CommonDataKinds
. As constantes simplesmente dão um
nome de constante diferente ao mesmo nome de coluna, o que ajuda a acessar os dados em uma linha de um
tipo específico.
Por exemplo, a classe ContactsContract.CommonDataKinds.Email
define constantes de nome de coluna de tipos específicos para uma linha ContactsContract.Data
que tem o tipo MIME Email.CONTENT_ITEM_TYPE
. A classe contém a constante ADDRESS
para a coluna de endereço de e-mail. O valor real de ADDRESS
é "data1", que é igual ao nome genérico da coluna.
Cuidado:não adicione seus próprios dados personalizados à
tabela ContactsContract.Data
usando uma linha que tenha um dos tipos
MIME predefinidos do provedor. Caso contrário, há o risco de perda de dados ou mau funcionamento do provedor. Por exemplo, não adicione uma linha com o tipo MIME Email.CONTENT_ITEM_TYPE
que contenha um nome de usuário em vez de um endereço de e-mail na coluna DATA1
. Se usar um tipo MIME personalizado para a linha, você poderá definir os próprios nomes de coluna de tipo específico e usar as colunas como quiser.
A Figura 2 mostra como colunas descritivas e colunas de dados aparecem em uma linha ContactsContract.Data
e como os nomes de colunas de tipo específico se sobrepõem aos nomes de colunas genéricas.
![Como nomes de coluna de tipo específico mapeiam nomes de coluna genéricos](https://developer.android.com/static/images/providers/data_columns.png?authuser=6&hl=pt)
Figura 2. Nomes de coluna de tipo específico e nomes de coluna genérica.
Classes de nome de coluna de tipo específico
A tabela 2 lista as classes de nome de coluna de tipo específico mais usadas:
Tabela 2. Classes de nome de coluna de tipo específico
Classes de mapeamento | Tipo de dados | Observações |
---|---|---|
ContactsContract.CommonDataKinds.StructuredName |
São os dados de nome do contato bruto associados a essa linha de dados. | Os contatos brutos têm somente uma dessas linhas. |
ContactsContract.CommonDataKinds.Photo |
É a foto principal do contato bruto associada a essa linha de dados. | Os contatos brutos têm somente uma dessas linhas. |
ContactsContract.CommonDataKinds.Email |
É um endereço de e-mail do contato bruto associado a essa linha de dados. | Os contatos brutos podem ter diversos endereços de e-mail. |
ContactsContract.CommonDataKinds.StructuredPostal |
É um endereço postal do contato bruto associado a essa linha de dados. | Os contatos brutos podem ter diversos endereços postais. |
ContactsContract.CommonDataKinds.GroupMembership |
É um identificador que vincula o contato bruto a um dos grupos no Provedor de contatos. | Grupos são um recurso opcional de um tipo e um nome de conta. Eles são descritos em mais detalhes na seção Grupos de contatos. |
Contatos
O Provedor de contatos combina as linhas de contato bruto entre todos os tipos e nomes de conta para formar um contato. Isso facilita a exibição e a modificação de todos os dados de uma pessoa coletados pelo usuário. O Provedor de contatos gerencia a criação de linhas de novos contatos e a agregação de contatos brutos a uma linha de contato existente. Nem os aplicativos nem os adaptadores de sincronização têm permissão para adicionar contatos, e algumas colunas em uma linha de contato são somente leitura.
Observação:se você tentar adicionar um contato ao Provedor de contatos com um
insert()
, vai encontrar
uma exceção UnsupportedOperationException
. Se você tentar atualizar uma coluna
listada como "somente leitura", a atualização será ignorada.
O Provedor de contatos cria um novo contato em resposta à adição de um novo contato bruto que não corresponde a nenhum contato existente. O provedor também faz isso se os dados de um contato bruto existente mudam de modo a não corresponder mais ao contato a que estavam anexados anteriormente. Se um aplicativo ou adaptador de sincronização criar um novo contato bruto que corresponda a um contato já existente, o novo contato bruto será agregado ao contato existente.
O Provedor de contatos vincula uma linha de contato às linhas de contato bruto com a coluna _ID
da linha do contato na tabela Contacts
. A coluna CONTACT_ID
da tabela de contatos brutos
ContactsContract.RawContacts
contém valores _ID
para
a linha de contatos associada a cada linha de contatos brutos.
A tabela ContactsContract.Contacts
também tem a coluna LOOKUP_KEY
, que é um link "permanente" para a linha do contato. Como o Provedor de contatos mantém contatos automaticamente, ele pode alterar o valor de _ID
da linha de um contato em resposta a uma agregação ou sincronização. Mesmo que isso aconteça, o URI de conteúdo CONTENT_LOOKUP_URI
combinado com o LOOKUP_KEY
do contato ainda apontará para a linha do contato. Assim, você poderá usar LOOKUP_KEY
para manter links para contatos "favoritos" e assim por diante. Essa coluna tem um formato próprio que não
está relacionado ao formato da coluna _ID
.
A figura 3 mostra como as três tabelas principais se relacionam entre si.
![Principais tabelas do Provedor de contatos](https://developer.android.com/static/images/providers/contacts_tables.png?authuser=6&hl=pt)
Figura 3. Contatos, contatos brutos e relacionamentos da tabela de detalhes.
Cuidado : se você publicar seu app na Google Play Store ou se ele estiver em um dispositivo com o Android 10 (API de nível 29) ou mais recente, lembre-se de que um conjunto limitado de campos e métodos de dados de contatos está obsoleto.
Nas condições mencionadas, o sistema limpa periodicamente todos os valores gravados nestes campos de dados:
-
ContactsContract.ContactOptionsColumns.LAST_TIME_CONTACTED
-
ContactsContract.ContactOptionsColumns.TIMES_CONTACTED
-
ContactsContract.DataUsageStatColumns.LAST_TIME_USED
-
ContactsContract.DataUsageStatColumns.TIMES_USED
As APIs usadas para definir os campos de dados citados acima também estão obsoletas:
Além disso, os campos a seguir não retornam mais os contatos frequentes. Alguns desses campos influenciam a classificação de contatos somente quando eles fazem parte de um tipo de dados específico.
-
ContactsContract.Contacts.CONTENT_FREQUENT_URI
-
ContactsContract.Contacts.CONTENT_STREQUENT_URI
-
ContactsContract.Contacts.CONTENT_STREQUENT_FILTER_URI
-
CONTENT_FILTER_URI
(afeta apenas os tipos de dados E-mail, Telefone, Chamável e Contactable ) -
ENTERPRISE_CONTENT_FILTER_URI
(afeta apenas os tipos de dados E-mail, Telefone e Chamável)
Caso seus apps estejam acessando ou atualizando esses campos ou APIs, use métodos alternativos. Por exemplo, é possível atender a determinados casos de uso com provedores de conteúdo particular ou outros dados armazenados no seu app ou sistemas de back-end.
Para verificar se a funcionalidade do app não é afetada por essa mudança, limpe esses campos de dados manualmente. Para fazer isso, execute o seguinte comando ADB em um dispositivo com Android 4.1 (API de nível 16) ou mais recente:
adb shell content delete \ --uri content://com.android.contacts/contacts/delete_usage
Dados de adaptadores de sincronização
Os usuários inserem dados de contatos diretamente no dispositivo, mas os dados também fluem para o Provedor de
contatos de serviços da Web por adaptadores de sincronização, que automatizam
a transferência de dados entre o dispositivo e os serviços. Adaptadores de sincronização são executados em segundo plano sob o controle do sistema e chamam métodos ContentResolver
para gerenciar dados.
No Android, o serviço Web com que um adaptador de sincronização trabalha é identificado por um tipo de conta. Cada adaptador de sincronização funciona com um tipo de conta, mas é compatível com vários nomes de conta para o tipo em questão. Os tipos e nomes de conta são descritos brevemente na seção Fontes de dados de contatos brutos. As definições a seguir oferecem mais detalhes e descrevem como o tipo e o nome da conta se relacionam com adaptadores de sincronização e serviços.
- Tipo de conta
-
Identifica um serviço em que o usuário armazenou dados. Na maioria das vezes, o usuário precisa
autenticar com o serviço. Por exemplo, Contatos do Google é um tipo de conta, identificado
pelo código
google.com
. Esse valor corresponde ao tipo de conta usado peloAccountManager
. - Nome da conta
- Identifica uma conta ou login específico de um tipo de conta. As contas dos Contatos do Google são as mesmas das Contas do Google, que têm um endereço de e-mail como nome da conta. Outros serviços podem usar um nome de usuário com só uma palavra ou código numérico.
Os tipos de conta não precisam ser exclusivos. Um usuário pode configurar várias contas do Contatos do Google e fazer o download dos dados delas para o Provedor de contatos. Isso pode acontecer se o usuário tiver um conjunto de contatos pessoais para um nome de conta pessoal e outro para um de trabalho. Os nomes das contas geralmente são exclusivos. Juntos, eles identificam um fluxo de dados específico entre o Provedor de contatos e um serviço externo.
Se você quiser transferir os dados do serviço para o Provedor de contatos, precisará criar seu próprio adaptador de sincronização. Isso é descrito com mais detalhes na seção Adaptadores de sincronização do Provedor de contatos.
A Figura 4 mostra como o Provedor de contatos se encaixa no fluxo de dados sobre pessoas. Na caixa marcada "adaptadores de sincronização", cada adaptador é rotulado pelo tipo de conta.
![Fluxo de dados sobre pessoas](https://developer.android.com/static/images/providers/ContactsDataFlow.png?authuser=6&hl=pt)
Figura 4. Fluxo de dados do Provedor de Contatos.
Permissões necessárias
Os aplicativos que querem acessar o Provedor de contatos precisam solicitar as seguintes permissões:
- Acesso de leitura a uma ou mais tabelas
-
READ_CONTACTS
, especificado emAndroidManifest.xml
com o elemento<uses-permission>
como<uses-permission android:name="android.permission.READ_CONTACTS">
. - Acesso de gravação a uma ou mais tabelas
-
WRITE_CONTACTS
, especificado emAndroidManifest.xml
com o elemento<uses-permission>
como<uses-permission android:name="android.permission.WRITE_CONTACTS">
.
Essas permissões não se estendem aos dados do perfil do usuário. O perfil do usuário e as permissões necessárias são discutidos na próxima seção, O perfil de usuário.
Lembre-se de que os dados de contatos do usuário são pessoais e confidenciais. Os usuários estão preocupados com a privacidade e não querem que aplicativos coletem dados sobre eles ou os contatos deles. Se não for óbvio o motivo da necessidade de permissão para acessar os dados de contato dele, eles podem atribuir avaliações baixas ao seu app ou simplesmente se recusar a instalá-lo.
O perfil do usuário
A tabela ContactsContract.Contacts
tem uma única linha que contém
dados de perfil do usuário do dispositivo. Esses dados descrevem o user
do dispositivo em vez
de um dos contatos do usuário. A linha de contatos do perfil é vinculada a uma linha de
contatos brutos para cada sistema que usa um perfil.
Cada linha de contato bruto de perfil pode ter diversas linhas de dados. Constantes de acesso ao perfil do usuário estão disponíveis na classe ContactsContract.Profile
.
O acesso ao perfil do usuário exige permissões especiais. Além das permissões
READ_CONTACTS
e
WRITE_CONTACTS
necessárias para ler e gravar, o acesso
ao perfil de usuário requer as permissões android.Manifest.permission#READ_PROFILE e
android.Manifest.permission#WRITE_PROFILE para acesso de leitura e gravação,
respectivamente.
Lembre-se de que o perfil do usuário deve ser considerado confidencial. A permissão android.Manifest.permission#READ_PROFILE permite acessar os dados de identificação pessoal do usuário do dispositivo. Informe ao usuário por que você precisa de permissões de acesso ao perfil do usuário na descrição do aplicativo.
Para recuperar a linha de contato que contém o perfil do usuário, chame ContentResolver.query()
. Defina o URI de conteúdo como
CONTENT_URI
e não forneça nenhum
critério de seleção. Você também pode usar esse URI de conteúdo como base para recuperar
contatos brutos ou dados do perfil. Por exemplo, esse snippet recupera dados do perfil:
Kotlin
// Sets the columns to retrieve for the user profile projection = arrayOf( ContactsContract.Profile._ID, ContactsContract.Profile.DISPLAY_NAME_PRIMARY, ContactsContract.Profile.LOOKUP_KEY, ContactsContract.Profile.PHOTO_THUMBNAIL_URI ) // Retrieves the profile from the Contacts Provider profileCursor = contentResolver.query( ContactsContract.Profile.CONTENT_URI, projection, null, null, null )
Java
// Sets the columns to retrieve for the user profile projection = new String[] { Profile._ID, Profile.DISPLAY_NAME_PRIMARY, Profile.LOOKUP_KEY, Profile.PHOTO_THUMBNAIL_URI }; // Retrieves the profile from the Contacts Provider profileCursor = getContentResolver().query( Profile.CONTENT_URI, projection , null, null, null);
Observação:se você recuperar várias linhas de contato e quiser determinar se uma delas
é o perfil de usuário, teste a coluna
IS_USER_PROFILE
da linha. Essa coluna é definida como "1" se o contato for o perfil de usuário.
Metadados do Provedor de contatos
O Provedor de contatos gerencia dados que acompanham o estado dos dados de contatos no
repositório. Esses metadados sobre o repositório são armazenados em vários locais, incluindo as linhas da tabela de contatos brutos, dados e contatos, a tabela ContactsContract.Settings
e a tabela ContactsContract.SyncState
. A tabela a seguir mostra o efeito de cada um desses metadados:
Tabela 3. Metadados no Provedor de Contatos
Tabela | Coluna | Valores | Significado |
---|---|---|---|
ContactsContract.RawContacts |
DIRTY |
"0": não mudou desde a última sincronização. |
Marca contatos brutos que foram alterados no dispositivo e precisam ser sincronizados com o
servidor. O valor é definido automaticamente pelo Provedor de contatos quando os apps
Android atualizam uma linha.
Adaptadores de sincronização que modificam o contato bruto ou as tabelas de dados precisam sempre anexar a string |
“1” - modificado desde a última sincronização; precisa ser sincronizado com o servidor. | |||
ContactsContract.RawContacts |
VERSION |
É o número da versão dessa linha. | O Provedor de contatos incrementa esse valor automaticamente sempre que a linha ou os dados relacionados a ela mudam. |
ContactsContract.Data |
DATA_VERSION |
É o número da versão dessa linha. | O Provedor de contatos incrementa esse valor automaticamente sempre que a linha de dados é alterada. |
ContactsContract.RawContacts |
SOURCE_ID |
Um valor de string que identifica exclusivamente esse contato bruto para a conta em que foi criado. |
Quando um adaptador de sincronização cria um novo contato bruto, essa coluna precisa ser definida como o ID exclusivo do servidor para o contato bruto. Quando um app Android cria um novo
contato bruto, o app precisa deixar essa coluna vazia. Isso sinaliza ao adaptador de sincronização que ele precisa criar um novo contato bruto no servidor e receber um valor para o SOURCE_ID .
Em particular, o código de origem precisa ser exclusivo para cada tipo de conta e estável entre as sincronizações:
|
ContactsContract.Groups |
GROUP_VISIBLE |
“0” - os contatos nesse grupo não devem ser visíveis em IUs do aplicativo Android. | Essa coluna se destina à compatibilidade com servidores que permitem que um usuário oculte contatos em determinados grupos. |
“1” - os contatos nesse grupo podem ficar visíveis nas IUs do aplicativo. | |||
ContactsContract.Settings |
UNGROUPED_VISIBLE |
“0”: para essa conta e esse tipo de conta, os contatos que não pertencem a um grupo são invisíveis nas IUs do aplicativo Android. |
Por padrão, os contatos serão invisíveis se nenhum dos contatos brutos pertencer a um grupo.
A associação a um grupo de um contato bruto é indicada por uma ou mais
linhas ContactsContract.CommonDataKinds.GroupMembership
na tabela ContactsContract.Data .
Ao definir essa sinalização na linha da tabela ContactsContract.Settings
para um tipo de conta e uma conta, é possível forçar a visibilidade de contatos sem grupos.
Esse sinalizador serve para mostrar contatos de servidores que não usam grupos.
|
“1”: para essa conta e esse tipo de conta, os contatos que não pertencem a um grupo são visíveis nas IUs do aplicativo. | |||
ContactsContract.SyncState |
(todos) | Use essa tabela para armazenar metadados do seu adaptador de sincronização. | Com essa tabela, é possível armazenar o estado de sincronização e outros dados relacionados à sincronização de maneira persistente no dispositivo. |
Acesso ao Provedor de contatos
Esta seção descreve as diretrizes para acessar dados do Provedor de contatos, com foco no seguinte:
- Consultas de entidade.
- Modificação em lote.
- Recuperação e modificação com intents.
- Integridade dos dados.
A realização de modificações usando um adaptador de sincronização também é abordada com mais detalhes na seção Adaptadores de sincronização do Provedor de contatos.
Consultas de entidades
Como as tabelas do Provedor de contatos são organizadas em uma hierarquia, muitas vezes é útil recuperar uma linha e todas as linhas "filhas" vinculadas a ela. Por exemplo, para exibir todas as informações de uma pessoa, recupere todas as linhas ContactsContract.RawContacts
de uma única linha ContactsContract.Contacts
ou todas as linhas ContactsContract.CommonDataKinds.Email
de uma única linha ContactsContract.RawContacts
. Para facilitar isso, o Provedor
de contatos oferece construções de entidade, que atuam como mesclagens de banco de dados entre
tabelas.
Uma entidade é como uma tabela composta de colunas selecionadas de uma tabela pai e uma tabela filha.
Ao consultar uma entidade, você fornece uma projeção e critérios de pesquisa com base nas colunas
disponíveis da entidade. O resultado é um Cursor
que contém uma linha para cada linha recuperada da tabela filha. Por exemplo, se você consultar ContactsContract.Contacts.Entity
em busca de um nome de contato e todas as linhas ContactsContract.CommonDataKinds.Email
de todos os contatos brutos por esse nome, receberá um Cursor
contendo uma linha para cada linha ContactsContract.CommonDataKinds.Email
.
As entidades simplificam as consultas. Usando uma entidade, é possível recuperar todos os dados de um contato ou contato bruto de uma vez, em vez de precisar consultar primeiro a tabela pai para receber um ID e, em seguida, ter que consultar a tabela filha com esse ID. Além disso, o Provedor de contatos processa uma consulta em uma entidade em uma única transação, o que garante que os dados recuperados sejam consistentes internamente.
Observação: uma entidade geralmente não contém todas as colunas da tabela pai e
da filha. Se você tentar trabalhar com um nome de coluna que não esteja na lista de constantes de nomes de coluna da entidade, receberá uma Exception
.
O snippet a seguir mostra como recuperar todas as linhas de contato bruto de um contato. O snippet
é parte de um aplicativo maior que tem duas atividades: "principal" e "de detalhes". A atividade principal
mostra uma lista de linhas de contato. Quando o usuário seleciona uma, a atividade envia o ID correspondente para a atividade
de detalhes. A atividade de detalhes usa ContactsContract.Contacts.Entity
para mostrar todas as linhas de dados de todos os contatos brutos associados ao contato
selecionado.
Esse snippet foi retirado da atividade de "detalhes":
Kotlin
... /* * Appends the entity path to the URI. In the case of the Contacts Provider, the * expected URI is content://com.google.contacts/#/entity (# is the ID value). */ contactUri = Uri.withAppendedPath( contactUri, ContactsContract.Contacts.Entity.CONTENT_DIRECTORY ) // Initializes the loader identified by LOADER_ID. loaderManager.initLoader( LOADER_ID, // The identifier of the loader to initialize null, // Arguments for the loader (in this case, none) this // The context of the activity ) // Creates a new cursor adapter to attach to the list view cursorAdapter = SimpleCursorAdapter( this, // the context of the activity R.layout.detail_list_item, // the view item containing the detail widgets mCursor, // the backing cursor fromColumns, // the columns in the cursor that provide the data toViews, // the views in the view item that display the data 0) // flags // Sets the ListView's backing adapter. rawContactList.adapter = cursorAdapter ... override fun onCreateLoader(id: Int, args: Bundle?): Loader<Cursor> { /* * Sets the columns to retrieve. * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. * DATA1 contains the first column in the data row (usually the most important one). * MIMETYPE indicates the type of data in the data row. */ val projection: Array<String> = arrayOf( ContactsContract.Contacts.Entity.RAW_CONTACT_ID, ContactsContract.Contacts.Entity.DATA1, ContactsContract.Contacts.Entity.MIMETYPE ) /* * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw * contact collated together. */ val sortOrder = "${ContactsContract.Contacts.Entity.RAW_CONTACT_ID} ASC" /* * Returns a new CursorLoader. The arguments are similar to * ContentResolver.query(), except for the Context argument, which supplies the location of * the ContentResolver to use. */ return CursorLoader( applicationContext, // The activity's context contactUri, // The entity content URI for a single contact projection, // The columns to retrieve null, // Retrieve all the raw contacts and their data rows. null, // sortOrder // Sort by the raw contact ID. ) }
Java
... /* * Appends the entity path to the URI. In the case of the Contacts Provider, the * expected URI is content://com.google.contacts/#/entity (# is the ID value). */ contactUri = Uri.withAppendedPath( contactUri, ContactsContract.Contacts.Entity.CONTENT_DIRECTORY); // Initializes the loader identified by LOADER_ID. getLoaderManager().initLoader( LOADER_ID, // The identifier of the loader to initialize null, // Arguments for the loader (in this case, none) this); // The context of the activity // Creates a new cursor adapter to attach to the list view cursorAdapter = new SimpleCursorAdapter( this, // the context of the activity R.layout.detail_list_item, // the view item containing the detail widgets mCursor, // the backing cursor fromColumns, // the columns in the cursor that provide the data toViews, // the views in the view item that display the data 0); // flags // Sets the ListView's backing adapter. rawContactList.setAdapter(cursorAdapter); ... @Override public Loader<Cursor> onCreateLoader(int id, Bundle args) { /* * Sets the columns to retrieve. * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. * DATA1 contains the first column in the data row (usually the most important one). * MIMETYPE indicates the type of data in the data row. */ String[] projection = { ContactsContract.Contacts.Entity.RAW_CONTACT_ID, ContactsContract.Contacts.Entity.DATA1, ContactsContract.Contacts.Entity.MIMETYPE }; /* * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw * contact collated together. */ String sortOrder = ContactsContract.Contacts.Entity.RAW_CONTACT_ID + " ASC"; /* * Returns a new CursorLoader. The arguments are similar to * ContentResolver.query(), except for the Context argument, which supplies the location of * the ContentResolver to use. */ return new CursorLoader( getApplicationContext(), // The activity's context contactUri, // The entity content URI for a single contact projection, // The columns to retrieve null, // Retrieve all the raw contacts and their data rows. null, // sortOrder); // Sort by the raw contact ID. }
Quando o carregamento é concluído, LoaderManager
invoca um callback para onLoadFinished()
. Um dos argumentos de entrada desse método é uma Cursor
com os resultados da consulta. No seu app, você pode receber os
dados desse Cursor
para mostrá-lo ou trabalhar com ele.
Modificação em lote
Sempre que possível, insira, atualize e exclua dados no Provedor de contatos em
"modo de lote", criando um ArrayList
de
objetos ContentProviderOperation
e chamando
applyBatch()
. Como o Provedor de contatos executa todas as operações em um applyBatch()
em uma única transação, as modificações nunca deixam o repositório de contatos em um estado inconsistente. Uma modificação em lote também facilita a inserção de um contato bruto e os dados detalhados
ao mesmo tempo.
Observação:para modificar um único contato bruto, envie uma intent ao aplicativo de contatos do dispositivo em vez de fazer a modificação no app. Isso é descrito em mais detalhes na seção Recuperação e modificação com intents.
Pontos de rendimento
Uma modificação em lote que contém um grande número de operações pode bloquear outros processos,
resultando em uma experiência geral ruim para o usuário. Para organizar todas as modificações que você quer realizar no menor número possível de listas separadas e, ao mesmo tempo, evitar que elas bloqueiem o sistema, defina pontos de rendimento para uma ou mais operações.
Um ponto de rendimento é um objeto ContentProviderOperation
que tem o valor
isYieldAllowed()
definido como
true
. Quando o Provedor de contatos encontra um ponto de rendimento, ele pausa o trabalho para
permitir que outros processos sejam executados e encerra a transação atual. Quando o provedor for iniciado novamente, ele
continuará com a próxima operação no ArrayList
e iniciará uma nova
transação.
Os pontos de rendimento resultam em mais de uma transação por chamada para
applyBatch()
. Por isso, é preciso definir um ponto de rendimento para a última operação de um conjunto de linhas relacionadas.
Por exemplo, defina um ponto de rendimento para a última operação de um conjunto que adicione
linhas de contato bruto e linhas de dados associados a ele, ou para a última operação para um conjunto de linhas relacionadas
a um único contato.
Os pontos de rendimento também são uma unidade de operação atômica. Todos os acessos entre dois pontos de rendimento terão êxito ou falha como uma única unidade. Se você não definir pontos de rendimento, a menor operação atômica será todo o lote de operações. Ao usar pontos de rendimento, você evita que as operações prejudiquem o desempenho do sistema e, ao mesmo tempo, garante que um subconjunto de operações seja atômico.
Referências de retorno da modificação
Ao inserir uma nova linha de contato bruto e as linhas de dados associadas como um conjunto de objetos ContentProviderOperation
, é necessário vincular as linhas de dados à linha de contato bruto, inserindo o valor _ID
do contato bruto como o valor RAW_CONTACT_ID
. No entanto, esse
valor não está disponível ao criar o ContentProviderOperation
para a linha de dados, porque você ainda não aplicou
ContentProviderOperation
à linha do contato bruto. Para contornar esse problema,
a classe ContentProviderOperation.Builder
tem o método
withValueBackReference()
.
Esse método permite inserir ou modificar uma coluna com o resultado de uma operação anterior.
O método withValueBackReference()
tem dois argumentos:
-
key
- A chave de um par de chave-valor. O valor desse argumento precisa ser o nome de uma coluna na tabela que você está modificando.
-
previousResult
-
O índice baseado em 0 de um valor na matriz de objetos
ContentProviderResult
deapplyBatch()
. À medida que as operações em lote são aplicadas, o resultado de cada operação é armazenado em uma matriz intermediária de resultados. O valorpreviousResult
é o índice de um desses resultados, que é recuperado e armazenado com o valorkey
. Isso permite inserir um novo registro de contato bruto e recuperar o valor_ID
e, em seguida, fazer uma "referência de retorno" ao valor ao adicionar uma linhaContactsContract.Data
.Toda a matriz de resultados é criada quando você chama
applyBatch()
pela primeira vez, com tamanho igual ao tamanho doArrayList
dos objetosContentProviderOperation
fornecidos. No entanto, todos os elementos na matriz de resultados são definidos comonull
, e se você tentar fazer uma referência de retorno a um resultado de uma operação que ainda não foi aplicada,withValueBackReference()
vai gerar umaException
.
Os snippets a seguir mostram como inserir um novo contato bruto e dados em lote. Eles incluem o código que estabelece um ponto de rendimento e usam uma referência de retorno.
O primeiro snippet recupera dados de contato da IU. Nesse momento, o usuário já selecionou a conta a que o novo contato bruto deve ser adicionado.
Kotlin
// Creates a contact entry from the current UI values, using the currently-selected account. private fun createContactEntry() { /* * Gets values from the UI */ val name = contactNameEditText.text.toString() val phone = contactPhoneEditText.text.toString() val email = contactEmailEditText.text.toString() val phoneType: String = contactPhoneTypes[mContactPhoneTypeSpinner.selectedItemPosition] val emailType: String = contactEmailTypes[mContactEmailTypeSpinner.selectedItemPosition]
Java
// Creates a contact entry from the current UI values, using the currently-selected account. protected void createContactEntry() { /* * Gets values from the UI */ String name = contactNameEditText.getText().toString(); String phone = contactPhoneEditText.getText().toString(); String email = contactEmailEditText.getText().toString(); int phoneType = contactPhoneTypes.get( contactPhoneTypeSpinner.getSelectedItemPosition()); int emailType = contactEmailTypes.get( contactEmailTypeSpinner.getSelectedItemPosition());
O próximo snippet cria uma operação para inserir a linha de contato bruto na tabela ContactsContract.RawContacts
:
Kotlin
/* * Prepares the batch operation for inserting a new raw contact and its data. Even if * the Contacts Provider does not have any data for this person, you can't add a Contact, * only a raw contact. The Contacts Provider will then add a Contact automatically. */ // Creates a new array of ContentProviderOperation objects. val ops = arrayListOf<ContentProviderOperation>() /* * Creates a new raw contact with its account type (server type) and account name * (user's account). Remember that the display name is not stored in this row, but in a * StructuredName data row. No other data is required. */ var op: ContentProviderOperation.Builder = ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.name) .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.type) // Builds the operation and adds it to the array of operations ops.add(op.build())
Java
/* * Prepares the batch operation for inserting a new raw contact and its data. Even if * the Contacts Provider does not have any data for this person, you can't add a Contact, * only a raw contact. The Contacts Provider will then add a Contact automatically. */ // Creates a new array of ContentProviderOperation objects. ArrayList<ContentProviderOperation> ops = new ArrayList<ContentProviderOperation>(); /* * Creates a new raw contact with its account type (server type) and account name * (user's account). Remember that the display name is not stored in this row, but in a * StructuredName data row. No other data is required. */ ContentProviderOperation.Builder op = ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType()) .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName()); // Builds the operation and adds it to the array of operations ops.add(op.build());
Em seguida, o código cria linhas de dados para as linhas de nome de exibição, telefone e e-mail.
Cada objeto do builder de operações usa
withValueBackReference()
para receber o
RAW_CONTACT_ID
. Os pontos de referência de volta para o objeto ContentProviderResult
da primeira operação, que adiciona a linha de contato bruto e retorna o novo valor _ID
. Como resultado, cada linha de dados é automaticamente vinculada por RAW_CONTACT_ID
à nova linha ContactsContract.RawContacts
a que pertence.
O objeto ContentProviderOperation.Builder
que adiciona a linha de e-mail é sinalizado com withYieldAllowed()
, que define um ponto de rendimento:
Kotlin
// Creates the display name for the new raw contact, as a StructuredName data row. op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * withValueBackReference sets the value of the first argument to the value of * the ContentProviderResult indexed by the second argument. In this particular * call, the raw contact ID column of the StructuredName data row is set to the * value of the result returned by the first operation, which is the one that * actually adds the raw contact row. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to StructuredName .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) // Sets the data row's display name to the name in the UI. .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name) // Builds the operation and adds it to the array of operations ops.add(op.build()) // Inserts the specified phone number and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Phone .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // Sets the phone number and type .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType) // Builds the operation and adds it to the array of operations ops.add(op.build()) // Inserts the specified email and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Email .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) // Sets the email address and type .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType) /* * Demonstrates a yield point. At the end of this insert, the batch operation's thread * will yield priority to other threads. Use after every set of operations that affect a * single contact, to avoid degrading performance. */ op.withYieldAllowed(true) // Builds the operation and adds it to the array of operations ops.add(op.build())
Java
// Creates the display name for the new raw contact, as a StructuredName data row. op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * withValueBackReference sets the value of the first argument to the value of * the ContentProviderResult indexed by the second argument. In this particular * call, the raw contact ID column of the StructuredName data row is set to the * value of the result returned by the first operation, which is the one that * actually adds the raw contact row. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to StructuredName .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) // Sets the data row's display name to the name in the UI. .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name); // Builds the operation and adds it to the array of operations ops.add(op.build()); // Inserts the specified phone number and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Phone .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // Sets the phone number and type .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType); // Builds the operation and adds it to the array of operations ops.add(op.build()); // Inserts the specified email and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Email .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) // Sets the email address and type .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType); /* * Demonstrates a yield point. At the end of this insert, the batch operation's thread * will yield priority to other threads. Use after every set of operations that affect a * single contact, to avoid degrading performance. */ op.withYieldAllowed(true); // Builds the operation and adds it to the array of operations ops.add(op.build());
O último snippet mostra a chamada para applyBatch()
que insere as novas linhas de contato bruto e de dados.
Kotlin
// Ask the Contacts Provider to create a new contact Log.d(TAG, "Selected account: ${mSelectedAccount.name} (${mSelectedAccount.type})") Log.d(TAG, "Creating contact: $name") /* * Applies the array of ContentProviderOperation objects in batch. The results are * discarded. */ try { contentResolver.applyBatch(ContactsContract.AUTHORITY, ops) } catch (e: Exception) { // Display a warning val txt: String = getString(R.string.contactCreationFailure) Toast.makeText(applicationContext, txt, Toast.LENGTH_SHORT).show() // Log exception Log.e(TAG, "Exception encountered while inserting contact: $e") } }
Java
// Ask the Contacts Provider to create a new contact Log.d(TAG,"Selected account: " + selectedAccount.getName() + " (" + selectedAccount.getType() + ")"); Log.d(TAG,"Creating contact: " + name); /* * Applies the array of ContentProviderOperation objects in batch. The results are * discarded. */ try { getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); } catch (Exception e) { // Display a warning Context ctx = getApplicationContext(); CharSequence txt = getString(R.string.contactCreationFailure); int duration = Toast.LENGTH_SHORT; Toast toast = Toast.makeText(ctx, txt, duration); toast.show(); // Log exception Log.e(TAG, "Exception encountered while inserting contact: " + e); } }
As operações em lote também permitem implementar controle de simultaneidade otimista, um método de aplicar transações de modificação sem precisar bloquear o repositório subjacente. Para usar esse método, aplique a transação e verifique se há outras modificações que possam ter sido feitas ao mesmo tempo. Se você descobrir que ocorreu uma modificação inconsistente, reverta a transação e tente novamente.
O controle de simultaneidade otimista é útil para dispositivos móveis em que há apenas um usuário por vez e são raros os acessos simultâneos a um repositório de dados. Como o bloqueio não é usado, não há tempo desperdiçado na configuração de bloqueios nem na espera para que outras transações liberem os respectivos bloqueios.
Para usar o controle de simultaneidade otimista ao atualizar uma única linha ContactsContract.RawContacts
, siga estas etapas:
-
Recupere a coluna
VERSION
do contato bruto junto com os outros dados recuperados. -
Crie um objeto
ContentProviderOperation.Builder
adequado para aplicar uma restrição usando o métodonewAssertQuery(Uri)
. Para o URI de conteúdo, useRawContacts.CONTENT_URI
com o_ID
do contato bruto anexado a ele. -
Para o objeto
ContentProviderOperation.Builder
, chamewithValue()
para comparar a colunaVERSION
com o número da versão que você acabou de recuperar. -
Para o mesmo
ContentProviderOperation.Builder
, chamewithExpectedCount()
para garantir que apenas uma linha seja testada por essa declaração. -
Chame
build()
para criar o objetoContentProviderOperation
e, em seguida, adicione esse objeto como o primeiro objeto naArrayList
que você transmite paraapplyBatch()
. - Aplique a transação em lote.
Se a linha do contato bruto for atualizada por outra operação entre o momento da leitura da linha e o momento em que você tentar modificá-la, a ContentProviderOperation
de "assert" falhará e todo o lote de operações será cancelado. Em seguida, é possível tentar novamente
o lote ou realizar alguma outra ação.
O snippet a seguir demonstra como criar uma ContentProviderOperation
de "declaração" após consultar um único contato bruto usando um CursorLoader
:
Kotlin
/* * The application uses CursorLoader to query the raw contacts table. The system calls this method * when the load is finished. */ override fun onLoadFinished(loader: Loader<Cursor>, cursor: Cursor) { // Gets the raw contact's _ID and VERSION values rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)) mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)) } ... // Sets up a Uri for the assert operation val rawContactUri: Uri = ContentUris.withAppendedId( ContactsContract.RawContacts.CONTENT_URI, rawContactID ) // Creates a builder for the assert operation val assertOp: ContentProviderOperation.Builder = ContentProviderOperation.newAssertQuery(rawContactUri).apply { // Adds the assertions to the assert operation: checks the version withValue(SyncColumns.VERSION, mVersion) // and count of rows tested withExpectedCount(1) } // Creates an ArrayList to hold the ContentProviderOperation objects val ops = arrayListOf<ContentProviderOperation>() ops.add(assertOp.build()) // You would add the rest of your batch operations to "ops" here ... // Applies the batch. If the assert fails, an Exception is thrown try { val results: Array<ContentProviderResult> = contentResolver.applyBatch(AUTHORITY, ops) } catch (e: OperationApplicationException) { // Actions you want to take if the assert operation fails go here }
Java
/* * The application uses CursorLoader to query the raw contacts table. The system calls this method * when the load is finished. */ public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { // Gets the raw contact's _ID and VERSION values rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)); mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)); } ... // Sets up a Uri for the assert operation Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactID); // Creates a builder for the assert operation ContentProviderOperation.Builder assertOp = ContentProviderOperation.newAssertQuery(rawContactUri); // Adds the assertions to the assert operation: checks the version and count of rows tested assertOp.withValue(SyncColumns.VERSION, mVersion); assertOp.withExpectedCount(1); // Creates an ArrayList to hold the ContentProviderOperation objects ArrayList ops = new ArrayList<ContentProviderOperation>; ops.add(assertOp.build()); // You would add the rest of your batch operations to "ops" here ... // Applies the batch. If the assert fails, an Exception is thrown try { ContentProviderResult[] results = getContentResolver().applyBatch(AUTHORITY, ops); } catch (OperationApplicationException e) { // Actions you want to take if the assert operation fails go here }
Recuperação e modificação com intents
Ao enviar uma intent ao app de contatos do dispositivo, você pode acessar o Provedor de contatos indiretamente. O intent inicia a interface do aplicativo de contatos do dispositivo, na qual os usuários podem fazer trabalhos relacionados a contatos. Com esse tipo de acesso, os usuários podem:
- Selecionar um contato de uma lista e retorná-lo ao aplicativo para trabalhos futuros.
- Editar os dados de um contato existente.
- Inserir um novo contato bruto para quaisquer das suas contas.
- Excluir um contato ou dados dos contatos.
Se o usuário estiver inserindo ou atualizando dados, será possível coletar os dados primeiro e enviá-los como parte da intent.
Quando você usa intents para acessar o Provedor de contatos pelo aplicativo de contatos do dispositivo, não é necessário criar a própria IU ou código para acessar o provedor. Também não é necessário solicitar permissão de leitura ou gravação no provedor. O aplicativo de contatos do dispositivo pode delegar a permissão de leitura de um contato para você e, como você está fazendo modificações no provedor por outro aplicativo, não é necessário ter permissões de gravação.
O processo geral de envio de uma intent para acessar um provedor é descrito em detalhes no guia
Fundamentos do provedor de conteúdo na seção "Acesso a dados por intents". Os valores de ação,
tipo MIME e dados usados para as tarefas disponíveis estão resumidos na Tabela 4, enquanto os
valores extras que podem ser usados com
putExtra()
estão listados na
documentação de referência de ContactsContract.Intents.Insert
:
Tabela 4. Intenções do Provedor de Contatos
Tarefa | Ação | Dados | Tipo MIME | Observações |
---|---|---|---|---|
Escolher um contato de uma lista | ACTION_PICK |
Uma destas opções:
|
Não usado |
Exibe uma lista de contatos brutos ou uma lista de dados de um contato bruto, dependendo do tipo de URI de conteúdo fornecido.
Chame
|
Inserir um novo contato bruto | Insert.ACTION |
N/A |
RawContacts.CONTENT_TYPE , tipo MIME para um conjunto de contatos brutos.
|
Exibe a tela Adicionar contato do aplicativo de contatos do dispositivo. Os
valores extras adicionados à intent são exibidos. Se enviado com startActivityForResult() , o URI de conteúdo do contato bruto recém-adicionado será retornado ao método de callback onActivityResult() da atividade no argumento Intent , no campo "dados". Para receber o valor, chame getData() .
|
Editar um contato | ACTION_EDIT |
CONTENT_LOOKUP_URI para o contato. A atividade do editor permite que o usuário edite qualquer dado associado
a este contato.
|
Contacts.CONTENT_ITEM_TYPE , um único contato. |
Exibe a tela “Edit Contact” no aplicativo de contatos. São exibidos os valores extras adicionados à intent. Quando o usuário clica em Concluído para salvar as edições, sua atividade retorna ao primeiro plano. |
Exibir um seletor que também pode adicionar dados | ACTION_INSERT_OR_EDIT |
N/A |
CONTENT_ITEM_TYPE
|
Essa intent sempre exibe a tela do seletor do app de contatos. O usuário pode
escolher um contato para editar ou adicionar um novo. A tela de edição ou de adição é exibida, dependendo da escolha do usuário, e são exibidos os dados extras transmitidos à intent. Se o app exibir dados de contato, como um e-mail ou número de telefone, use
essa intent para permitir que o usuário adicione os dados a um contato já existente.
contato,
Observação:não é necessário enviar um valor de nome nos extras dessa intent, porque o usuário sempre seleciona um nome já existente ou adiciona um novo. Além disso, se você enviar um nome e o usuário escolher fazer uma edição, o app Contatos exibirá o nome enviado, substituindo o valor anterior. Se o usuário não perceber isso e salvar a edição, o valor antigo será perdido. |
O app de contatos do dispositivo não permite a exclusão de um contato bruto ou dos dados dele com uma
intent. Em vez disso, para excluir um contato bruto, use
ContentResolver.delete()
ou ContentProviderOperation.newDelete()
.
O snippet a seguir mostra como criar e enviar uma intent que insere um novo contato bruto e dados:
Kotlin
// Gets values from the UI val name = contactNameEditText.text.toString() val phone = contactPhoneEditText.text.toString() val email = contactEmailEditText.text.toString() val company = companyName.text.toString() val jobtitle = jobTitle.text.toString() /* * Demonstrates adding data rows as an array list associated with the DATA key */ // Defines an array list to contain the ContentValues objects for each row val contactData = arrayListOf<ContentValues>() /* * Defines the raw contact row */ // Sets up the row as a ContentValues object val rawContactRow = ContentValues().apply { // Adds the account type and name to the row put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.type) put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.name) } // Adds the row to the array contactData.add(rawContactRow) /* * Sets up the phone number data row */ // Sets up the row as a ContentValues object val phoneRow = ContentValues().apply { // Specifies the MIME type for this data row (all data rows must be marked by their type) put(ContactsContract.Data.MIMETYPE,ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // Adds the phone number and its type to the row put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) } // Adds the row to the array contactData.add(phoneRow) /* * Sets up the email data row */ // Sets up the row as a ContentValues object val emailRow = ContentValues().apply { // Specifies the MIME type for this data row (all data rows must be marked by their type) put(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) // Adds the email address and its type to the row put(ContactsContract.CommonDataKinds.Email.ADDRESS, email) } // Adds the row to the array contactData.add(emailRow) // Creates a new intent for sending to the device's contacts application val insertIntent = Intent(ContactsContract.Intents.Insert.ACTION).apply { // Sets the MIME type to the one expected by the insertion activity type = ContactsContract.RawContacts.CONTENT_TYPE // Sets the new contact name putExtra(ContactsContract.Intents.Insert.NAME, name) // Sets the new company and job title putExtra(ContactsContract.Intents.Insert.COMPANY, company) putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle) /* * Adds the array to the intent's extras. It must be a parcelable object in order to * travel between processes. The device's contacts app expects its key to be * Intents.Insert.DATA */ putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData) } // Send out the intent to start the device's contacts app in its add contact activity. startActivity(insertIntent)
Java
// Gets values from the UI String name = contactNameEditText.getText().toString(); String phone = contactPhoneEditText.getText().toString(); String email = contactEmailEditText.getText().toString(); String company = companyName.getText().toString(); String jobtitle = jobTitle.getText().toString(); // Creates a new intent for sending to the device's contacts application Intent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION); // Sets the MIME type to the one expected by the insertion activity insertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE); // Sets the new contact name insertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name); // Sets the new company and job title insertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company); insertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle); /* * Demonstrates adding data rows as an array list associated with the DATA key */ // Defines an array list to contain the ContentValues objects for each row ArrayList<ContentValues> contactData = new ArrayList<ContentValues>(); /* * Defines the raw contact row */ // Sets up the row as a ContentValues object ContentValues rawContactRow = new ContentValues(); // Adds the account type and name to the row rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType()); rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName()); // Adds the row to the array contactData.add(rawContactRow); /* * Sets up the phone number data row */ // Sets up the row as a ContentValues object ContentValues phoneRow = new ContentValues(); // Specifies the MIME type for this data row (all data rows must be marked by their type) phoneRow.put( ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE ); // Adds the phone number and its type to the row phoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone); // Adds the row to the array contactData.add(phoneRow); /* * Sets up the email data row */ // Sets up the row as a ContentValues object ContentValues emailRow = new ContentValues(); // Specifies the MIME type for this data row (all data rows must be marked by their type) emailRow.put( ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE ); // Adds the email address and its type to the row emailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email); // Adds the row to the array contactData.add(emailRow); /* * Adds the array to the intent's extras. It must be a parcelable object in order to * travel between processes. The device's contacts app expects its key to be * Intents.Insert.DATA */ insertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData); // Send out the intent to start the device's contacts app in its add contact activity. startActivity(insertIntent);
Integridade dos dados
Como o repositório de contatos contém dados importantes e confidenciais que os usuários esperam que estejam corretos e atualizados, o Provedor de contatos tem regras bem definidas para a integridade dos dados. É sua responsabilidade seguir essas regras ao modificar os dados dos contatos. As regras importantes são listadas a seguir:
-
Sempre adicione uma linha
ContactsContract.CommonDataKinds.StructuredName
para cada linhaContactsContract.RawContacts
que você adicionar. -
Uma linha
ContactsContract.RawContacts
sem uma linhaContactsContract.CommonDataKinds.StructuredName
na tabelaContactsContract.Data
pode causar problemas durante a agregação. -
Sempre vincule novas linhas
ContactsContract.Data
à linha mãeContactsContract.RawContacts
. -
Uma linha
ContactsContract.Data
que não está vinculada a umContactsContract.RawContacts
não fica visível no app de contatos do dispositivo e pode causar problemas com adaptadores de sincronização. - Altere dados somente para seus contatos brutos.
- Lembre-se de que o Provedor de contatos geralmente gerencia dados de vários tipos de conta/serviços on-line diferentes. O aplicativo precisa modificar ou excluir apenas os dados das linhas que pertencem a você e que ele só insira dados com um nome e tipo de conta que você controla.
-
Sempre use as constantes definidas em
ContactsContract
e suas subclasses para autoridades, URIs de conteúdo, caminhos de URI, nomes de coluna, tipos MIME e valoresTYPE
. - O uso dessas constantes ajuda a evitar erros. Você também vai receber uma notificação com avisos do compilador se alguma das constantes for descontinuada.
Linhas de dados personalizados
Ao criar e usar seus próprios tipos MIME personalizados, você pode inserir, editar, excluir e recuperar suas próprias linhas de dados na tabela ContactsContract.Data
. As linhas só usam a coluna definida em ContactsContract.DataColumns
. No entanto, é possível associar os próprios nomes de coluna de tipo específico aos nomes de coluna padrão. No aplicativo de contatos do dispositivo,
os dados das linhas são exibidos, mas não podem ser editados ou excluídos, e os usuários não podem adicionar
outros dados. Para permitir que os usuários modifiquem suas linhas de dados personalizados, você precisa fornecer uma atividade do editor no seu próprio aplicativo.
Para exibir seus dados personalizados, forneça um arquivo contacts.xml
contendo um elemento <ContactsAccountType>
e um ou mais dos elementos filhos <ContactsDataKind>
dele. Isso é descrito em mais detalhes na
seção <ContactsDataKind> element
.
Para saber mais sobre tipos MIME personalizados, leia o guia Criar um provedor de conteúdo.
Adaptadores de sincronização do Provedor de contatos
O Provedor de contatos foi projetado especificamente para processar a sincronização de dados de contatos entre um dispositivo e um serviço on-line. Isso permite que os usuários façam o download dos dados em um novo dispositivo e façam o upload dos dados para uma nova conta. A sincronização também garante que os usuários tenham os dados mais recentes à mão, independentemente da origem de adições e alterações. Outra vantagem da sincronização é que ela disponibiliza os dados dos contatos mesmo quando o dispositivo não está conectado à rede.
Embora você possa implementar a sincronização de várias maneiras, o sistema Android oferece um framework de sincronização de plug-in que automatiza as seguintes tarefas:
- Verificação da disponibilidade da rede.
- Agendamento e execução de sincronizações, com base nas preferências do usuário.
- Reinicialização de sincronizações que foram interrompidas.
Para usar essa biblioteca, deve-se fornecer um plug-in do adaptador de sincronização. Cada adaptador de sincronização é exclusivo de um serviço e provedor de conteúdo, mas pode processar vários nomes de conta do mesmo serviço. O framework também permite vários adaptadores de sincronização para o mesmo serviço e provedor.
Classes e arquivos do adaptador de sincronização
Implemente um adaptador de sincronização como uma subclasse de
AbstractThreadedSyncAdapter
e o instale como parte de um app
Android. O sistema aprende sobre o adaptador de sincronização com elementos no manifesto do
aplicativo e com um arquivo XML especial apontado pelo manifesto. O arquivo XML define o
tipo de conta do serviço on-line e a autoridade do provedor de conteúdo, que, juntos,
identificam exclusivamente o adaptador. O adaptador de sincronização não fica ativo até que o usuário adicione uma conta para o tipo de conta dele e ative a sincronização para o provedor de conteúdo com que o adaptador será sincronizado. Nesse ponto, o sistema começa a gerenciar o adaptador, chamando-o conforme necessário para fazer a sincronização entre o provedor de conteúdo e o servidor.
Observação:usar um tipo de conta como parte da identificação do adaptador de sincronização permite
que o sistema detecte e agrupe adaptadores de sincronização que acessam diferentes serviços da
mesma organização. Por exemplo, todos os adaptadores de sincronização para serviços on-line do Google têm o mesmo
tipo de conta com.google
. Quando o usuário adiciona uma Conta do Google aos dispositivos, todos
os adaptadores de sincronização instalados para serviços do Google são listados juntos. Cada um deles
é sincronizado com um provedor de conteúdo diferente no dispositivo.
Como a maioria dos serviços exige que os usuários verifiquem a identidade antes de acessar
os dados, o sistema Android oferece um framework de autenticação semelhante ao framework do adaptador de sincronização e muitas vezes
usado com ele. O framework de autenticação usa
autenticadores de plug-ins que são subclasses de
AbstractAccountAuthenticator
. Um autenticador verifica
a identidade do usuário nas seguintes etapas:
- Coleta o nome, a senha ou informações semelhantes do usuário (as credenciais dele).
- Envia as credenciais para o serviço.
- Examina a resposta do serviço.
Se o serviço aceitar as credenciais, o autenticador poderá armazená-las para uso posterior. Graças ao framework do autenticador de plug-ins, o
AccountManager
pode fornecer acesso a qualquer token de autenticação compatível com um autenticador
que escolha expor, como os tokens de autenticação OAuth2.
Embora as autenticações não sejam necessárias, a maioria dos serviços de contato as usam. No entanto, não é obrigatório usar o framework de autenticação do Android para fazer a autenticação.
Implementação do adaptador de sincronização
Para implementar um adaptador de sincronização para o Provedor de contatos, comece criando um app Android que contenha o seguinte:
-
Um componente
Service
que responde a solicitações do sistema para se vincular ao adaptador de sincronização. -
Quando o sistema quer executar uma sincronização, ele chama o método
onBind()
do serviço para receber umIBinder
para o adaptador de sincronização. Isso permite que o sistema faça chamadas entre processos aos métodos do adaptador. -
O adaptador de sincronização real, implementado como uma subclasse concreta de
AbstractThreadedSyncAdapter
. -
Essa classe realiza o trabalho de fazer o download de dados do servidor, fazer upload de dados do
dispositivo e resolver conflitos. O trabalho principal do adaptador é feito no método
onPerformSync()
. Essa classe deve ser instanciada como um singleton. -
Uma subclasse de
Application
. -
Essa classe funciona como uma fábrica para o Singleton do adaptador de sincronização. Use o método
onCreate()
para instanciar o adaptador de sincronização e forneça um método "getter" estático para retornar o singleton ao métodoonBind()
do serviço do adaptador de sincronização. -
Opcional:um componente
Service
que responde a solicitações do sistema para autenticação do usuário. -
AccountManager
inicia este serviço para iniciar o processo de autenticação. O métodoonCreate()
do serviço instancia um objeto autenticador. Quando o sistema quer autenticar uma conta de usuário para o adaptador de sincronização do aplicativo, ele chama o métodoonBind()
do serviço para receber umIBinder
para o autenticador. Isso permite que o sistema faça chamadas entre processos para os métodos do autenticador. -
Opcional:uma subclasse concreta de
AbstractAccountAuthenticator
que processa solicitações de autenticação. -
Essa classe fornece métodos que o
AccountManager
invoca para autenticar as credenciais do usuário com o servidor. Os detalhes desse processo variam bastante, de acordo com a tecnologia de servidor em uso. Consulte a documentação do seu software servidor para saber mais sobre autenticação. - Os arquivos XML que definem o adaptador de sincronização e o autenticador para o sistema.
-
Os componentes de serviço do adaptador de sincronização e do autenticador descritos anteriormente são
definidos nos elementos
<service>
do manifesto do aplicativo. Esses elementos contêm elementos filhos<meta-data>
que fornecem dados específicos ao sistema:-
O elemento
<meta-data>
do serviço do adaptador de sincronização aponta para o arquivo XMLres/xml/syncadapter.xml
. Esse arquivo, por sua vez, especifica um URI para o serviço da Web que será sincronizado com o Provedor de contatos e um tipo de conta para o serviço da Web. -
Opcional:o elemento
<meta-data>
do autenticador aponta para o arquivo XMLres/xml/authenticator.xml
. Esse arquivo, por sua vez, especifica o tipo de conta compatível com esse autenticador, bem como recursos de IU que aparecem durante o processo de autenticação. O tipo de conta especificado nesse elemento precisa ser o mesmo que o especificado para o adaptador de sincronização.
-
O elemento
Dados de streams sociais
As tabelas android.provider.ContactsContract.StreamItems e android.provider.ContactsContract.StreamItemPhotos gerenciam dados recebidos de redes sociais. É possível criar um adaptador de sincronização que adicione dados de stream da sua própria rede a essas tabelas, ler dados de stream dessas tabelas e exibi-los no seu aplicativo ou ambos. Com esses recursos, os serviços e aplicativos de redes sociais podem ser integrados à experiência das redes sociais no Android.
Textos de streams sociais
Itens de stream sempre são associados a um contato bruto. O
android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID se vincula ao
valor _ID
do contato bruto. O tipo e o nome da conta do contato bruto também são armazenados na linha do item de stream.
Armazene os dados do seu stream nas colunas a seguir:
- android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE
- Obrigatório. É o tipo de conta do usuário do contato bruto associado a esse item de stream. Lembre-se de definir esse valor ao inserir um item de stream.
- android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME
- Obrigatório. O nome da conta do usuário do contato bruto associado a esse item de stream. Lembre-se de definir esse valor ao inserir um item de stream.
- Colunas identificadoras
-
Obrigatório. É preciso inserir as colunas identificadoras a seguir ao
inserir um item de stream:
- android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID: o valor android.provider.BaseColumns#_ID do contato a que esse item de stream está associado.
- android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY: o valor android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY do contato a que esse item de fluxo está associado.
- android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID: o valor android.provider.BaseColumns#_ID do contato bruto a que esse item de stream está associado.
- android.provider.ContactsContract.StreamItemsColumns#COMMENTS
- Opcional. Armazena informações resumidas que podem ser exibidas no início do item de stream.
- android.provider.ContactsContract.StreamItemsColumns#TEXT
-
O texto do item de stream, o conteúdo que foi postado pela origem do item ou a descrição de alguma ação que gerou o item de stream. Essa coluna pode conter
qualquer formatação e imagens de recursos incorporadas que possam ser renderizadas por
fromHtml()
. O provedor pode truncar ou abreviar conteúdo longo, mas tentará evitar a quebra de tags. - android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP
- Uma string de texto contendo a hora em que o item de stream foi inserido ou atualizado, em forma de milissegundos desde a época. Os aplicativos que inserem ou atualizam itens de fluxo são responsáveis por manter essa coluna. Ela não é mantida automaticamente pelo Provedor de contatos.
Para mostrar informações de identificação dos itens de fluxo, use android.provider.ContactsContract.StreamItemsColumns#RES_ICON, android.provider.ContactsContract.StreamItemsColumns#RES_LABEL e android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE para vincular a recursos do aplicativo para fazer isso.
A tabela android.provider.ContactsContract.StreamItems também contém as colunas de android.provider.ContactsContract.StreamItemsColumns#SYNC1 a android.provider.ContactsContract.StreamItemsColumns#SYNC4 para uso exclusivo de adaptadores de sincronização.
Fotos de streams sociais
A tabela android.provider.ContactsContract.StreamItemPhotos armazena fotos associadas
a um item de stream. A coluna
android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID
da tabela se vincula a valores na coluna _ID
da
tabela android.provider.ContactsContract.StreamItems. As referências de fotos são armazenadas na tabela nestas colunas:
- Coluna android.provider.ContactsContract.StreamItemPhotos#PHOTO (um BLOB).
- Uma representação binária da foto, redimensionada pelo provedor para armazenamento e exibição. Essa coluna está disponível para compatibilidade com versões anteriores do Provedor de contatos que a usavam para armazenar fotos. No entanto, na versão atual, não é recomendável usar essa coluna para armazenar fotos. Em vez disso, use android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID ou android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI (ambos são descritos nos pontos a seguir) para armazenar fotos em um arquivo. Essa coluna agora contém uma miniatura da foto, que está disponível para leitura.
- android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID
-
Identificador numérico de uma foto de um contato bruto. Anexe esse valor à constante
DisplayPhoto.CONTENT_URI
para receber um URI de conteúdo que aponte para um único arquivo de foto e, em seguida, chameopenAssetFileDescriptor()
para receber um identificador para o arquivo de foto. - android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI
-
Um URI de conteúdo que aponta diretamente para o arquivo de foto da foto representada por essa linha.
Chame
openAssetFileDescriptor()
com esse URI para gerar um identificador para o arquivo de foto.
Uso de tabelas de streams sociais
Essas tabelas funcionam como as outras tabelas principais do Provedor de Contatos, exceto que:
- exigem permissões de acesso adicionais. Para ler o conteúdo delas, o aplicativo precisa ter a permissão android.Manifest.permission#READ_SOCIAL_STREAM. Para modificá-las, o aplicativo precisa ter a permissão android.Manifest.permission#WRITE_SOCIAL_STREAM.
-
Para a tabela android.provider.ContactsContract.StreamItems, o número de linhas
armazenadas para cada contato bruto é limitado. Quando o limite é atingido,
o Provedor de contatos abre espaço para novas linhas de itens de stream excluindo automaticamente
as linhas que têm o
android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP mais antigo. Para acessar o
limite, faça uma consulta ao URI de conteúdo
android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI. É possível deixar todos os argumentos, exceto o URI de conteúdo, definidos como
null
. A consulta retorna um Cursor contendo uma única linha, com a coluna única android.provider.ContactsContract.StreamItems#MAX_ITEMS.
A classe android.provider.ContactsContract.StreamItems.StreamItemPhotos define uma subtabela de android.provider.ContactsContract.StreamItemPhotos que contém as linhas de foto de um único item de fluxo.
Interações de streams sociais
Os dados de fluxo social gerenciados pelo Provedor de contatos, em conjunto com o aplicativo de contatos do dispositivo, oferecem uma maneira eficiente de conectar seu sistema de rede social a contatos existentes. Os seguintes recursos estão disponíveis:
- Ao sincronizar seu serviço de rede social com o Provedor de contatos com um adaptador de sincronização, é possível recuperar a atividade recente dos contatos de um usuário e armazená-la nas tabelas android.provider.ContactsContract.StreamItems e android.provider.ContactsContract.StreamItemPhotos para uso posterior.
- Além da sincronização regular, é possível acionar o adaptador de sincronização para recuperar dados adicionais quando o usuário seleciona um contato para visualizar. Isso permite que o adaptador de sincronização recupere fotos de alta resolução e os itens de stream mais recentes do contato.
- Ao registrar uma notificação no aplicativo de contatos do dispositivo e no Provedor de contatos, você pode receber um intent quando um contato é visualizado e, nesse momento, atualizar o status do contato pelo serviço. Essa abordagem pode ser mais rápida e usar menos largura de banda do que fazer uma sincronização completa com um adaptador de sincronização.
- Os usuários podem adicionar um contato ao seu serviço de rede social enquanto o visualizam no aplicativo de contatos do dispositivo. Ative isso com o recurso "convidar contato", que é ativado com uma combinação de uma atividade que adiciona um contato existente à sua rede e um arquivo XML que fornece o aplicativo de contatos do dispositivo e o Provedor de contatos com os detalhes do seu app.
A sincronização regular de itens de stream com o Provedor de contatos é igual a outras sincronizações. Para saber mais sobre sincronização, consulte a seção Adaptadores de sincronização do Provedor de contatos. O registro de notificações e o convite a contatos são abordados nas próximas duas seções.
Registro para processar exibições de redes sociais
Para registrar o adaptador de sincronização para receber notificações quando o usuário exibe um contato gerenciado pelo adaptador de sincronização:
-
Crie um arquivo chamado
contacts.xml
no diretóriores/xml/
do projeto. Se você já tiver esse arquivo, pule esta etapa. -
Nesse arquivo, adicione o elemento
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">
. Se esse elemento já existir, pule esta etapa. -
Para registrar um serviço que é notificado quando o usuário abre a página de detalhes de um contato no aplicativo de contatos do dispositivo, adicione o atributo
viewContactNotifyService="serviceclass"
ao elemento, em queserviceclass
é o nome de classe totalmente qualificado do serviço que receberá a intent do aplicativo de contatos do dispositivo. Para o serviço de notificação, use uma classe que estendaIntentService
para permitir que o serviço receba intents. Os dados nos intents recebidas contêm o URI de conteúdo do contato bruto em que o usuário clicou. No serviço de notificação, é possível vincular e chamar o adaptador de sincronização para atualizar os dados do contato bruto.
Para registrar uma atividade a ser chamada quando o usuário clica em um item de stream, em uma foto ou em ambos:
-
Crie um arquivo chamado
contacts.xml
no diretóriores/xml/
do projeto. Se você já tiver esse arquivo, pule esta etapa. -
Nesse arquivo, adicione o elemento
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">
. Se esse elemento já existir, pule esta etapa. -
Para registrar uma das suas atividades para processar o usuário que clica em um item de stream no
aplicativo de contatos do dispositivo, adicione o atributo
viewStreamItemActivity="activityclass"
ao elemento, em queactivityclass
é o nome de classe totalmente qualificado da atividade que receberá o intent do aplicativo de contatos do dispositivo. -
Para registrar uma das suas atividades para processar o usuário que clica em uma foto de stream no
aplicativo de contatos do dispositivo, adicione o atributo
viewStreamItemPhotoActivity="activityclass"
ao elemento, em queactivityclass
é o nome de classe totalmente qualificado da atividade que receberá o intent do aplicativo de contatos do dispositivo.
O elemento <ContactsAccountType>
é descrito em mais detalhes na
seção Elemento<ContactsAccountType>.
O intent recebido contém o URI de conteúdo do item ou foto em que o usuário clicou. Para ter atividades separadas para itens de texto e para fotos, use os dois atributos no mesmo arquivo.
Interação com o serviço de redes sociais
Os usuários não precisam sair do aplicativo de contatos do dispositivo para convidar um contato para seu site de rede social. Em vez disso, o app de contatos do dispositivo pode enviar uma intent para convidar o contato para uma das suas atividades. Para definir essa configuração:
-
Crie um arquivo chamado
contacts.xml
no diretóriores/xml/
do projeto. Se você já tiver esse arquivo, pule esta etapa. -
Nesse arquivo, adicione o elemento
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">
. Se esse elemento já existir, pule esta etapa. -
Adicione os seguintes atributos:
inviteContactActivity="activityclass"
-
inviteContactActionLabel="@string/invite_action_label"
activityclass
é o nome de classe totalmente qualificado da atividade que receberá a intent. O valorinvite_action_label
é uma string de texto mostrada no menu Add Connection no aplicativo de contatos do dispositivo.
Observação:ContactsSource
é um nome de tag descontinuado de
ContactsAccountType
.
Referência do contacts.xml
O arquivo contacts.xml
contém elementos XML que controlam a interação do adaptador de sincronização e do aplicativo com o aplicativo de contatos e o Provedor de contatos. Esses elementos são descritos nas seções a seguir.
Elemento <ContactsAccountType>
O elemento <ContactsAccountType>
controla a interação do seu aplicativo com o aplicativo de contatos. Ele tem a seguinte sintaxe:
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android" inviteContactActivity="activity_name" inviteContactActionLabel="invite_command_text" viewContactNotifyService="view_notify_service" viewGroupActivity="group_view_activity" viewGroupActionLabel="group_action_text" viewStreamItemActivity="viewstream_activity_name" viewStreamItemPhotoActivity="viewphotostream_activity_name">
contidos em:
res/xml/contacts.xml
pode conter:
<ContactsDataKind>
Description:
Declara componentes e rótulos da interface do Android que permitem que os usuários convidem um dos contatos para uma rede social, notifiquem os usuários quando um dos streams de redes sociais deles for atualizado e assim por diante.
Observe que o prefixo do atributo android:
não é necessário para os atributos
de <ContactsAccountType>
.
Atributos:
inviteContactActivity
- É o nome de classe totalmente qualificado da atividade no app que você quer ativar quando o usuário seleciona Add connection no aplicativo de contatos do dispositivo.
inviteContactActionLabel
-
Uma string de texto que é mostrada para a atividade especificada em
inviteContactActivity
, no menu Add connection. Por exemplo, você pode usar a string "Seguir na minha rede". Você pode usar um identificador de recurso de string para esse rótulo. viewContactNotifyService
- O nome de classe totalmente qualificado de um serviço no aplicativo que receberá notificações quando o usuário visualizar um contato. Essa notificação é enviada pelo aplicativo de contatos do dispositivo. Ela permite que o aplicativo adie operações com uso intensivo de dados até que elas sejam necessárias. Por exemplo, seu aplicativo pode responder a essa notificação lendo e mostrando a foto em alta resolução do contato e os itens mais recentes do fluxo de redes sociais. Esse recurso é descrito em mais detalhes na seção Interações de fluxos sociais.
viewGroupActivity
- É o nome de classe totalmente qualificado de uma atividade no aplicativo que pode exibir informações de grupo. Quando o usuário clica no rótulo do grupo no aplicativo de contatos do dispositivo, a IU dessa atividade é exibida.
viewGroupActionLabel
-
O rótulo que o aplicativo de contatos exibe para um controle de interface que permite
que o usuário veja grupos no seu aplicativo.
Um identificador de recurso de string é permitido para esse atributo.
viewStreamItemActivity
- É o nome de classe totalmente qualificado de uma atividade no aplicativo que o aplicativo de contatos do dispositivo inicia quando o usuário clica em um item de stream de um contato bruto.
viewStreamItemPhotoActivity
- É o nome de classe totalmente qualificado de uma atividade no aplicativo que o aplicativo de contatos do dispositivo inicia quando o usuário clica em uma foto no item de stream de um contato bruto.
Elemento <ContactsDataKind>
O elemento <ContactsDataKind>
controla a exibição das linhas de dados personalizados do aplicativo na IU do aplicativo de contatos. Ele tem a seguinte sintaxe:
<ContactsDataKind android:mimeType="MIMEtype" android:icon="icon_resources" android:summaryColumn="column_name" android:detailColumn="column_name">
contidos em:
<ContactsAccountType>
Description:
Use esse elemento para que o aplicativo de contatos exiba o conteúdo de uma linha de dados personalizados como parte dos detalhes de um contato bruto. Cada elemento filho <ContactsDataKind>
de <ContactsAccountType>
representa um tipo de linha de dados personalizados que o adaptador de sincronização adiciona à tabela ContactsContract.Data
. Adicione um elemento <ContactsDataKind>
para cada tipo MIME personalizado que você usar. Não é necessário adicionar o elemento se você não quiser exibir dados em uma linha de dados personalizados.
Atributos:
android:mimeType
-
O tipo MIME personalizado que você definiu para um dos tipos de linha de dados personalizados na tabela
ContactsContract.Data
. Por exemplo, o valorvnd.android.cursor.item/vnd.example.locationstatus
pode ser um tipo MIME personalizado para uma linha de dados que registra o último local conhecido de um contato. android:icon
- Um recurso drawable do Android que o aplicativo de contatos exibe ao lado dos seus dados. Use isso para indicar ao usuário que os dados vêm do seu serviço.
android:summaryColumn
- O nome da coluna do primeiro de dois valores recuperados da linha de dados. O valor é exibido como a primeira linha da entrada para essa linha de dados. A primeira linha deve ser usada como um resumo dos dados, mas isso é opcional. Veja também android:detailColumn.
android:detailColumn
-
O nome da coluna do segundo de dois valores recuperados da linha de dados. O valor é exibido como a segunda linha da entrada para essa linha de dados. Consulte também
android:summaryColumn
.
Recursos adicionais do Provedor de contatos
Além dos principais recursos descritos nas seções anteriores, o Provedor de contatos oferece estes recursos úteis para trabalhar com dados de contatos:
- Grupos de contatos
- Recursos de foto
Grupos de contatos
O Provedor de contatos pode marcar coleções de contatos relacionados com dados do grupo. Se o servidor associado a uma conta de usuário quiser manter grupos, o adaptador de sincronização do tipo de conta precisará transferir os dados dos grupos entre o Provedor de contatos e o servidor. Quando o usuário adiciona um novo contato ao servidor e coloca esse contato em um novo grupo, o adaptador de sincronização precisa adicionar o novo grupo à tabela ContactsContract.Groups
. Os grupos a que um contato bruto pertence são armazenados na tabela ContactsContract.Data
, usando o tipo MIME ContactsContract.CommonDataKinds.GroupMembership
.
Se você estiver projetando um adaptador de sincronização que adicionará dados de contatos brutos do
servidor ao Provedor de contatos e não estiver usando grupos, será necessário instruir
o provedor a tornar os dados visíveis. No código executado quando um usuário adiciona uma conta ao dispositivo, atualize a linha ContactsContract.Settings
que o Provedor de contatos adiciona à conta. Nessa linha, defina o valor da coluna
Settings.UNGROUPED_VISIBLE
como 1. Ao fazer isso, o Provedor de contatos sempre
deixará seus dados de contatos visíveis, mesmo que você não use grupos.
Fotos de contatos
A tabela ContactsContract.Data
armazena fotos como linhas com o tipo MIME
Photo.CONTENT_ITEM_TYPE
. A coluna CONTACT_ID
da linha está vinculada à coluna _ID
do contato bruto a que pertence.
A classe ContactsContract.Contacts.Photo
define uma subtabela de ContactsContract.Contacts
contendo informações da foto principal de um contato, que é a foto principal do contato bruto principal do contato. Da mesma forma, a classe ContactsContract.RawContacts.DisplayPhoto
define uma subtabela de ContactsContract.RawContacts
contendo informações de foto para a foto principal de um contato bruto.
A documentação de referência para ContactsContract.Contacts.Photo
e
ContactsContract.RawContacts.DisplayPhoto
contém exemplos de
recuperação de informações da foto. Não existe uma classe de conveniência para recuperar a miniatura
principal de um contato bruto, mas é possível enviar uma consulta para a tabela
ContactsContract.Data
, selecionando as colunas
_ID
, Photo.CONTENT_ITEM_TYPE
e IS_PRIMARY
do contato bruto para encontrar a linha da foto principal do contato bruto.
Dados de streams sociais de uma pessoa também podem conter fotos. Eles são armazenados na tabela android.provider.ContactsContract.StreamItemPhotos, descrita em mais detalhes na seção Fotos de fluxos de redes sociais.