Gerenciar locais de armazenamento de contatos

Os apps podem permitir que os usuários criem e armazenem contatos. Esses contatos geralmente podem ser salvos em dois locais:

1. Conta de nuvem: salve contatos em uma conta associada a um serviço de nuvem (como o Google Cloud) para permitir a sincronização e o backup de contatos.
2. Conta local: os contatos podem ser armazenados localmente no dispositivo.

Os usuários podem definir o local de armazenamento preferido nas configurações do dispositivo. Esse local preferido é conhecido como a conta padrão e é usado ao criar contatos. Os apps precisam respeitar essa preferência. Este documento explica como trabalhar com diferentes locais de armazenamento de contatos, incluindo contas em nuvem e locais, e implementar práticas recomendadas para gerenciar as preferências do usuário. A conta local se refere ao armazenamento de contatos diretamente no dispositivo.

Recuperar a conta padrão

Para determinar a conta padrão para novos contatos, use o ContactsContract.RawContacts.DefaultAccount

Chame getDefaultAccountForNewContacts() para receber o objeto ContactsContrast.RawContacts.DefaultAccount.DefaultAccountAndState. Esse objeto contém informações sobre a configuração de conta padrão.

Kotlin

import ContactsContrast.RawContacts
import ContactsContrast.RawContacts.DefaultAccount
import ContactsContrast.RawContacts.DefaultAccount.DefaultAccountAndState

val defaultAccountAndState: DefaultAccountAndState =
  DefaultAccount.getDefaultAccountForNewContacts(
      getContentResolver()
  )

Java

import ContactsContrast.RawContacts;
import ContactsContrast.RawContacts.DefaultAccount;
import ContactsContrast.RawContacts.DefaultAccount.DefaultAccountAndState;

DefaultAccountAndState defaultAccountAndState =
  DefaultAccount.getDefaultAccountForNewContacts(
    getContentResolver()
  );

O objeto DefaultAccountAndState contém:

• Estado: indica se uma conta padrão está definida e, se sim, a categoria dela (nuvem, local ou SIM).
• Conta: fornece os detalhes específicos da conta (nome e tipo) se o estado for DEFAULT_ACCOUNT_STATE_CLOUD or DEFAULT_ACCOUNT_STATE_SIM. Ele será nulo para outros estados, incluindo DEFAULT_ACCOUNT_STATE_LOCAL.

Observação: para a conta local (DEFAULT_ACCOUNT_STATE_LOCAL), é possível recuperar as informações da conta usando RawContacts.getLocalAccountName() e RawContacts.getLocalAccountType().

Confira um exemplo de como analisar o objeto DefaultAccountAndState:

Kotlin

// Retrieves the state of default account.
val defaultAccountState = defaultAccountAndState.state
var defaultAccountName: String? = null
var defaultAccountType: String? = null

when (defaultAccountState) {
    // Default account is set to a cloud or a SIM account.
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_CLOUD,
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_SIM -> {
        defaultAccountName = defaultAccountAndState.account?.name
        defaultAccountType = defaultAccountAndState.account?.type
    }
    // Default account is set to the local account on the device.
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_LOCAL -> {
        defaultAccountName = RawContacts.getLocalAccountType()
        defaultAccountType = RawContacts.getLocalAccountName()
    }
    // Default account is not set.
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_NOT_SET -> {
    }
}

Java

// Retrieves the state of default account.
var defaultAccountState = defaultAccountAndState.getState();
String defaultAccountName = null;
String defaultAccountType = null;

switch (defaultAccountState) {
  // Default account is set to a cloud or a SIM account.
  case DefaultAccountState.DEFAULT_ACCOUNT_STATE_CLOUD:
  case DefaultAccountState.DEFAULT_ACCOUNT_STATE_SIM:
    defaultAccountName = defaultAccountAndState.getAccount().name;
    defaultAccountType = defaultAccountAndState.getAccount().type;
    break;
  // Default account is set to the local account on the device.
  case  DefaultAccountState.DEFAULT_ACCOUNT_STATE_LOCAL:
    defaultAccountName = RawContacts.getLocalAccountType();
    defaultAccountType = RawContacts.getLocalAccountName();
    break;

  // Default account is not set.
  case DefaultAccountState.DEFAULT_ACCOUNT_STATE_NOT_SET:
    break;
}

Criar contatos sem especificar uma conta

Se a conta padrão estiver definida, o app geralmente não precisará especificar explicitamente uma conta ao criar contatos. O sistema salva automaticamente o novo contato na conta padrão. Veja como criar um contato sem especificar uma conta.

Crie um novo ArrayList de objetos ContentProviderOperation. Essa lista contém as operações para inserir o contato bruto e os dados associados a ele.

Kotlin

val ops = ArrayList<ContentProviderOperation>()

Java

ArrayList<ContentProviderOperation> ops =
        new ArrayList<ContentProviderOperation>();

Crie um novo ContentProviderOperation para inserir o contato bruto. Como você não especifica uma conta, não é necessário incluir ACCOUNT_TYPE e ACCOUNT_NAME.

Kotlin

val op = ContentProviderOperation.newInsert(
    ContactsContract.RawContacts.CONTENT_URI
)
ops.add(op.build())

Java

ContentProviderOperation.Builder op =
    ContentProviderOperation.newInsert(
        ContactsContract.RawContacts.CONTENT_URI
    );
ops.add(op.build());

Adicione outros objetos ContentProviderOperation à lista de operações para incluir os campos de contato, como nome, número de telefone e e-mail. Em seguida, execute a operação em lote para criar o contato.

Kotlin

try {
    getContentResolver().applyBatch(
        ContactsContract.AUTHORITY, ops
    )
} catch (e: Exception) {
    // Handle exceptions
}

Java

try {
    getContentResolver().applyBatch(
        ContactsContract.AUTHORITY, ops
    );
} catch (Exception e) {
    // Handle exceptions
}

Criar contatos em uma conta na nuvem

Para criar um contato em uma conta de nuvem, insira a linha de contato bruto na tabela ContactsContract.RawContacts e especifique a conta de nuvem. Veja como:

Crie um novo ArrayList de objetos ContentProviderOperation.

Kotlin

val ops = ArrayList<ContentProviderOperation>()

Java

ArrayList<ContentProviderOperation> ops =
    new ArrayList<ContentProviderOperation>();

Crie um novo ContentProviderOperation para inserir o contato bruto. Use o método withValue() para especificar o tipo e o nome da conta em nuvem selecionada.

Kotlin

val op = ContentProviderOperation.newInsert(
    ContactsContract.RawContacts.CONTENT_URI
)
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_TYPE,
        selectedAccount.type
    )
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_NAME,
        selectedAccount.name
    )
ops.add(op.build())

Java

ContentProviderOperation.Builder op =
    ContentProviderOperation.newInsert(
        ContactsContract.RawContacts.CONTENT_URI
    )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_TYPE,
            selectedAccount.getType()
        )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_NAME,
            selectedAccount.getName()
        );
ops.add(op.build());

Adicione outros objetos ContentProviderOperation à lista de operações para incluir os campos de contato e execute a operação em lote para criar o contato.

Criar contatos na conta local

Atenção: quando a conta padrão é definida como uma conta de nuvem (DEFAULT_ACCOUNT_STATE_CLOUD), os contatos só podem ser criados na conta de nuvem. Evite criar contatos na conta local ou em qualquer conta de chip nesse cenário.

Para criar um contato na conta local, insira uma nova linha de contato bruto na tabela ContactsContract.RawContacts e especifique as informações da conta local:

Crie um novo ArrayList de objetos ContentProviderOperation.

Kotlin

val ops = ArrayList<ContentProviderOperation>()

Java

ArrayList<ContentProviderOperation> ops =
    new ArrayList<ContentProviderOperation>();

Crie um novo ContentProviderOperation para inserir o contato bruto. Use ContactsContract.RawContacts.getLocalAccountName() e ContactsContract.RawContacts.getLocalAccountType() para especificar as informações da conta local.

Kotlin

val op = ContentProviderOperation.newInsert(
    ContactsContract.RawContacts.CONTENT_URI
)
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_TYPE,
        ContactsContract.RawContacts.getLocalAccountType()
    )
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_NAME,
        ContactsContract.RawContacts.getLocalAccountName()
    )
ops.add(op.build())

Java

ContentProviderOperation.Builder op =
    ContentProviderOperation.newInsert(
        ContactsContract.RawContacts.CONTENT_URI
    )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_TYPE,
            ContactsContract.RawContacts.getLocalAccountType()
        )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_NAME,
            ContactsContract.RawContacts.getLocalAccountName()
        );
ops.add(op.build());

Adicione outros objetos ContentProviderOperation à lista de operações para incluir os campos de contato e execute as operações em lote para criar o contato.