Provider di contatti

Il fornitore di contatti è un componente Android potente e flessibile che gestisce il repository centrale del dispositivo dei dati sulle persone. Il fornitore di contatti è l'origine dei dati che visualizzi nell'applicazione Contatti del dispositivo, e puoi anche accedervi nella tua applicazione e trasferire i dati tra il dispositivo e i servizi online. Il provider ospita una vasta gamma di origini dati e cerca di gestire il maggior numero possibile di dati per ogni persona, con il risultato che la sua organizzazione è complessa. Per questo motivo, l'API del provider include un insieme completo di classi di contratto e interfacce che facilitano il recupero e la modifica dei dati.

Questa guida descrive quanto segue:

• La struttura di base del fornitore.
• Come recuperare i dati dal provider.
• Come modificare i dati nel fornitore.
• Come scrivere un adattatore di sincronizzazione per la sincronizzazione dei dati dal server al provider di contatti.

Questa guida presuppone che tu conosca le nozioni di base dei fornitori di contenuti Android. Per ulteriori informazioni sui fornitori di contenuti Android, leggi la guida Nozioni di base sui fornitori di contenuti.

Organizzazione del fornitore di contatti

Il fornitore di contatti è un componente del fornitore di contenuti Android. Contiene tre tipi di dati su una persona, ognuno dei quali corrisponde a una tabella offerta dal provider, come illustrato nella figura 1:

Figura 1. Struttura della tabella del fornitore di contatti.

Le tre tabelle vengono comunemente indicate con i nomi delle rispettive classi di contratto. Le classi definiscono le costanti per gli URI dei contenuti, i nomi delle colonne e i valori delle colonne utilizzati dalle tabelle:

ContactsContract.Contacts tabella

Righe che rappresentano persone diverse, in base ad aggregazioni di righe di contatti non elaborate.

ContactsContract.RawContacts tabella

Righe contenenti un riepilogo dei dati di una persona, specifici per un account utente e un tipo.

ContactsContract.Data tabella

Righe contenenti i dettagli dei contatti non elaborati, come indirizzi email o numeri di telefono.

Le altre tabelle rappresentate dalle classi di contratto in ContactsContract sono tabelle ausiliarie che il provider di contatti utilizza per gestire le proprie operazioni o supportare funzioni specifiche nei contatti o nelle applicazioni di telefonia del dispositivo.

Contatti non elaborati

Un contatto non elaborato rappresenta i dati di una persona provenienti da un singolo tipo di account e nome di account. Poiché il provider di contatti consente più di un servizio online come origine dei dati per una persona, il provider di contatti consente più contatti non elaborati per la stessa persona. Più contatti non elaborati consentono inoltre a un utente di combinare i dati di una persona di più account appartenenti allo stesso tipo.

La maggior parte dei dati per un contatto non elaborato non è archiviata nella tabella ContactsContract.RawContacts. ma viene archiviato in una o più righe nella tabella ContactsContract.Data. Ogni riga di dati ha una colonna Data.RAW_CONTACT_ID che contiene il valore RawContacts._ID della relativa riga ContactsContract.RawContacts padre.

Colonne importanti dei contatti non elaborati

Le colonne importanti nella tabella ContactsContract.RawContacts sono elencate nella tabella 1. Leggi le seguenti note dopo la tabella:

Tabella 1. Colonne importanti dei contatti non elaborati.

Nome colonna	Usa	Notes
ACCOUNT_NAME	Il nome dell'account del tipo di account che rappresenta l'origine di questo contatto non elaborato. Ad esempio, il nome di un Account Google è uno degli indirizzi Gmail del proprietario del dispositivo. Consulta la voce successiva per ACCOUNT_TYPE per ulteriori informazioni.	Il formato di questo nome è specifico per il tipo di account. Non si tratta necessariamente di un indirizzo email.
ACCOUNT_TYPE	Il tipo di account che rappresenta l'origine di questo contatto non elaborato. Ad esempio, il tipo di account di un Account Google è com.google. qualifica sempre il tipo di account con un identificatore di dominio per un dominio di tua proprietà o che controlli. In questo modo, il tipo di account sarà univoco.	In genere, un tipo di account che offre dati dei contatti è associato a un adattatore di sincronizzazione che si sincronizza con il fornitore di contatti.
DELETED	Il flag "deleted" di un contatto non elaborato.	Questo flag consente al provider di contatti di mantenere la riga internamente fino a quando gli adattatori di sincronizzazione non sono in grado di eliminarla dai server per poi eliminarla dal repository.

Notes

Di seguito sono riportate alcune note importanti relative alla tabella ContactsContract.RawContacts:

• Il nome di un contatto non elaborato non è archiviato nella relativa riga in ContactsContract.RawContacts. ma viene archiviato nella tabella ContactsContract.Data, in una riga ContactsContract.CommonDataKinds.StructuredName. Un contatto non elaborato ha una sola riga di questo tipo nella tabella ContactsContract.Data.
• Attenzione: per utilizzare i dati del tuo account in una riga di contatto non elaborata, devi prima registrarli con AccountManager. Per farlo, chiedi agli utenti di aggiungere il tipo di account e il nome del loro account all'elenco degli account. Se non lo fai, il provider di contatti eliminerà automaticamente la riga dei contatti non elaborata.

  Ad esempio, se vuoi che la tua app conservi i dati dei contatti per il tuo servizio basato sul web con il dominio com.example.dataservice e l'account utente per il tuo servizio è [e-mail], l'utente deve prima aggiungere il "tipo" (com.example.dataservice) e il "nome" dell'account ([e-mail]) prima che l'app possa aggiungere righe di contatti non elaborate. Puoi spiegare questo requisito all'utente nella documentazione oppure puoi chiedere all'utente di aggiungere il tipo e il nome, o entrambi. I tipi e i nomi degli account sono descritti in maggiore dettaglio nella prossima sezione.

Origini dei dati non elaborati dei contatti

Per capire come funzionano i contatti non elaborati, considera l'utente "Emily Dickinson", il cui dispositivo ha definito i tre account utente seguenti:

• [e-mail]
• [e-mail]
• Account Twitter "belle_of_amherst"

Questo utente ha abilitato la funzionalità Sincronizza contatti per tutti e tre questi account nelle impostazioni Account.

Supponiamo che Emily Dickinson apra una finestra del browser, acceda a Gmail come [e-mail], apra Contatti e aggiunga "Thomas Higginson". Più tardi accede a Gmail come [e-mail] e invia un'email a "Thomas Higginson", che lo aggiunge automaticamente come contatto. Segue anche "colonel_tom" (ID Twitter di Thomas Higginson) su Twitter.

Il fornitore di contatti crea tre contatti non elaborati a seguito di questo lavoro:

1. Un contatto non elaborato per "Thomas Higginson" associato a [e-mail]. Il tipo di account utente è Google.
2. Un secondo contatto non elaborato per "Thomas Higginson" associato a [e-mail]. Anche il tipo di account utente è Google. Esiste un secondo contatto non elaborato anche se il nome è identico al nome precedente, perché la persona è stata aggiunta per un account utente diverso.
3. Un terzo contatto non elaborato per "Thomas Higginson" associato a "belle_of_amherst". Il tipo di account utente è Twitter.

Dati

Come indicato in precedenza, i dati di un contatto non elaborato vengono archiviati in una riga ContactsContract.Data collegata al valore _ID del contatto non elaborato. Ciò consente a un singolo contatto non elaborato di avere più istanze dello stesso tipo di dati, come indirizzi email o numeri di telefono. Ad esempio, se "Thomas Higginson" per [e-mail] (la riga di contatto non elaborata di Thomas Higginson associata all'Account Google [e-mail]) ha un indirizzo email di casa [e-mail] e un indirizzo email di lavoro [e-mail], il fornitore di contatti archivia le due righe degli indirizzi email e le collega entrambe al contatto non elaborato.

Tieni presente che in questa singola tabella vengono archiviati diversi tipi di dati. Le righe relative a nome visualizzato, numero di telefono, email, indirizzo postale, foto e dettagli del sito web sono disponibili nella tabella ContactsContract.Data. Per semplificare la gestione, la tabella ContactsContract.Data contiene alcune colonne con nomi descrittivi e altre con nomi generici. I contenuti di una colonna con nome descrittivo hanno lo stesso significato indipendentemente dal tipo di dati nella riga, mentre i contenuti di una colonna con nome generico hanno significati diversi a seconda del tipo di dati.

Nomi descrittivi delle colonne

Ecco alcuni esempi di nomi di colonna descrittivi:

RAW_CONTACT_ID

Il valore della colonna _ID del contatto non elaborato per questi dati.

MIMETYPE

Il tipo di dati archiviati in questa riga, espressi come tipo MIME personalizzato. Il provider di contatti utilizza i tipi MIME definiti nelle sottoclassi di ContactsContract.CommonDataKinds. Questi tipi MIME sono open source e possono essere utilizzati da qualsiasi applicazione o adattatore di sincronizzazione compatibile con il fornitore di contatti.

IS_PRIMARY

Se questo tipo di riga di dati può verificarsi più di una volta per un contatto non elaborato, la colonna IS_PRIMARY segnala la riga di dati che contiene i dati principali per il tipo. Ad esempio, se l'utente esercita una pressione prolungata su un numero di telefono per un contatto e seleziona Imposta predefinito, la riga ContactsContract.Data contenente quel numero avrà la colonna IS_PRIMARY impostata su un valore diverso da zero.

Nomi di colonna generici

Sono disponibili 15 colonne generiche denominate da DATA1 a DATA15 e altre quattro colonne generiche da SYNC1 a SYNC4 che devono essere utilizzate solo dagli adattatori di sincronizzazione. Le costanti dei nomi di colonna generiche funzionano sempre, indipendentemente dal tipo di dati contenuti nella riga.

La colonna DATA1 è indicizzata. Il fornitore di contatti utilizza sempre questa colonna per i dati che prevede saranno il target più frequente di una query. Ad esempio, in una riga email, questa colonna contiene l'indirizzo email effettivo.

Per convenzione, la colonna DATA15 è riservata all'archiviazione dei dati BLOB (Binary Large Object) come le miniature delle foto.

Nomi delle colonne specifici del tipo

Per semplificare l'utilizzo delle colonne per un determinato tipo di riga, il provider di contatti fornisce anche costanti dei nomi di colonna specifiche del tipo, definite nelle sottoclassi di ContactsContract.CommonDataKinds. Le costanti assegnano semplicemente un nome costante diverso allo stesso nome di colonna, in modo da poter accedere ai dati di una riga di un determinato tipo.

Ad esempio, la classe ContactsContract.CommonDataKinds.Email definisce le costanti dei nomi di colonna specifiche del tipo per una riga ContactsContract.Data con il tipo MIME Email.CONTENT_ITEM_TYPE. La classe contiene la costante ADDRESS per la colonna dell'indirizzo email. Il valore effettivo di ADDRESS è "data1", che corrisponde al nome generico della colonna.

Attenzione: non aggiungere dati personalizzati alla tabella ContactsContract.Data utilizzando una riga che contiene uno dei tipi MIME predefiniti del provider. Se lo fai, potresti perdere i dati o causare il malfunzionamento del provider. Ad esempio, nella colonna DATA1 non devi aggiungere una riga con tipo MIME Email.CONTENT_ITEM_TYPE che contiene un nome utente anziché un indirizzo email. Se utilizzi il tuo tipo MIME personalizzato per la riga, puoi definire nomi di colonna specifici per il tipo e utilizzare le colonne come preferisci.

La Figura 2 mostra il modo in cui le colonne descrittive e le colonne di dati vengono visualizzate in una riga ContactsContract.Data e il modo in cui i nomi di colonna specifici per tipo "sovrappongono" i nomi delle colonne generiche

Figura 2. Nomi di colonna specifici del tipo e nomi di colonna generici.

Classi di nomi di colonna specifiche per il tipo

Nella tabella 2 sono elencate le classi dei nomi di colonna specifiche per il tipo più utilizzate:

Tabella 2. Classi di nomi di colonna specifiche per il tipo

Classe di mappatura	Tipo di dati	Notes
ContactsContract.CommonDataKinds.StructuredName	I dati del nome del contatto non elaborato associato a questa riga di dati.	Un contatto non elaborato ha solo una di queste righe.
ContactsContract.CommonDataKinds.Photo	La foto principale del contatto non elaborato associato a questa riga di dati.	Un contatto non elaborato ha solo una di queste righe.
ContactsContract.CommonDataKinds.Email	Un indirizzo email per il contatto non elaborato associato a questa riga di dati.	Un contatto non elaborato può avere più indirizzi email.
ContactsContract.CommonDataKinds.StructuredPostal	Un indirizzo postale per il contatto non elaborato associato a questa riga di dati.	Un contatto non elaborato può avere più indirizzi postali.
ContactsContract.CommonDataKinds.GroupMembership	Un identificatore che collega il contatto non elaborato a uno dei gruppi del provider di contatti.	I gruppi sono una funzionalità facoltativa del tipo e del nome dell'account. Sono descritti in maggiore dettaglio nella sezione Gruppi di contatti.

Contatti

Il fornitore di contatti combina le righe dei contatti non elaborate di tutti i tipi di account e nomi di account per formare un contatto. Questo facilita la visualizzazione e la modifica di tutti i dati che un utente ha raccolto per una persona. Il fornitore di contatti gestisce la creazione di nuove righe di contatti e l'aggregazione di contatti non elaborati con una riga di contatto esistente. Né le applicazioni né gli adattatori di sincronizzazione possono aggiungere contatti e alcune colonne in una riga dei contatti sono di sola lettura.

Nota: se provi ad aggiungere un contatto al fornitore di contatti con insert(), riceverai un'eccezione UnsupportedOperationException. Se provi ad aggiornare una colonna elencata come "di sola lettura ", l'aggiornamento viene ignorato.

Il fornitore di contatti crea un nuovo contatto in risposta all'aggiunta di un nuovo contatto non elaborato che non corrisponde ad alcun contatto esistente. Il provider esegue questa operazione anche se i dati di un contatto non elaborato esistente cambiano in modo da non corrispondere più al contatto a cui erano stati precedentemente associati. Se un'applicazione o un adattatore di sincronizzazione crea un nuovo contatto non elaborato che corrisponde a un contatto esistente, il nuovo contatto non elaborato viene aggregato al contatto esistente.

Il fornitore di contatti collega una riga di contatto alle rispettive righe di contatto non elaborate con la colonna _ID della riga dei contatti nella tabella Contacts. La colonna CONTACT_ID della tabella dei contatti non elaborati ContactsContract.RawContacts contiene valori _ID per la riga dei contatti associata a ogni riga di contatti non elaborata.

La tabella ContactsContract.Contacts contiene anche la colonna LOOKUP_KEY, che è un link "permanente" alla riga dei contatti. Poiché il provider di contatti gestisce automaticamente i contatti, può modificare il valore _ID di una riga di contatto in risposta a un'aggregazione o una sincronizzazione. Anche in questo caso, l'URI dei contenuti CONTENT_LOOKUP_URI combinato con l'LOOKUP_KEY del contatto rimanderà comunque alla riga del contatto, quindi puoi utilizzare LOOKUP_KEY per mantenere i link ai contatti "preferiti" e così via. Questa colonna ha un proprio formato non correlato a quello della colonna _ID.

La Figura 3 mostra la correlazione tra le tre tabelle principali.

Figura 3. Relazioni nella tabella Contatti, Contatti non elaborati e Dettagli.

Attenzione: se pubblichi la tua app sul Google Play Store o se si trova su un dispositivo con Android 10 (livello API 29) o versioni successive, tieni presente che un insieme limitato di metodi e campi dei dati dei contatti è obsoleti.

Nelle condizioni indicate, il sistema cancella periodicamente qualsiasi valore scritto in questi campi di dati:

• ContactsContract.ContactOptionsColumns.LAST_TIME_CONTACTED
• ContactsContract.ContactOptionsColumns.TIMES_CONTACTED
• ContactsContract.DataUsageStatColumns.LAST_TIME_USED
• ContactsContract.DataUsageStatColumns.TIMES_USED

Anche le API utilizzate per impostare i campi di dati sopra indicati sono obsolete:

• ContactsContract.Contacts.markAsContacted()
• ContactsContract.DataUsageFeedback

Inoltre, i seguenti campi non restituiranno più contatti frequenti. Tieni presente che alcuni di questi campi influenzano il ranking dei contatti solo quando i contatti fanno parte di un tipo di dati specifico.

• ContactsContract.Contacts.CONTENT_FREQUENT_URI
• ContactsContract.Contacts.CONTENT_STREQUENT_URI
• ContactsContract.Contacts.CONTENT_STREQUENT_FILTER_URI
• CONTENT_FILTER_URI (interessa solo i tipi di dati Email, Phone, Callable e Contactables)
• ENTERPRISE_CONTENT_FILTER_URI (interessa solo i tipi di dati Email, Telefono e Chiamabili)

Se le tue app accedono o aggiornano questi campi o API, utilizza metodi alternativi. Ad esempio, puoi soddisfare determinati casi d'uso utilizzando fornitori di contenuti privati o altri dati archiviati all'interno della tua app o dei tuoi sistemi di backend.

Per verificare che questa modifica non influisca sulla funzionalità della tua app, puoi cancellare manualmente questi campi di dati. Per farlo, esegui il comando ADB seguente su un dispositivo con Android 4.1 (livello API 16) o versioni successive:

adb shell content delete \
--uri content://com.android.contacts/contacts/delete_usage

Dati dagli adattatori di sincronizzazione

Gli utenti inseriscono i dati dei contatti direttamente nel dispositivo, ma passano anche al fornitore di contatti dai servizi web tramite adattatori di sincronizzazione, che automatizzano il trasferimento dei dati tra il dispositivo e i servizi. Gli adattatori di sincronizzazione vengono eseguiti in background sotto il controllo del sistema e chiamano i metodi ContentResolver per gestire i dati.

In Android, il servizio web con cui funziona un adattatore di sincronizzazione viene identificato da un tipo di account. Ogni adattatore di sincronizzazione funziona con un solo tipo di account, ma può supportare più nomi di account per quel tipo. I tipi di account e i nomi degli account sono descritti brevemente nella sezione Fonti dei dati non elaborati dei contatti. Le seguenti definizioni forniscono maggiori dettagli e descrivono la relazione tra nome e tipo di account e adattatori e servizi di sincronizzazione.

Tipo di conto

Identifica un servizio in cui l'utente ha archiviato dati. La maggior parte delle volte l'utente deve autenticarsi con il servizio. Ad esempio, Contatti Google è un tipo di account, identificato dal codice google.com. Questo valore corrisponde al tipo di account utilizzato da AccountManager.

Il nome dell'account

Identifica un determinato account o login per un tipo di account. Gli account Contatti Google sono uguali agli Account Google, che hanno un indirizzo email come nome account. Altri servizi potrebbero utilizzare un nome utente di una sola parola o un ID numerico.

I tipi di account non devono essere univoci. Un utente può configurare più account Contatti Google e scaricare i propri dati nel fornitore di contatti. Ciò può accadere se l'utente ha un insieme di contatti personali per il nome di un account personale e un altro impostato per il lavoro. I nomi degli account sono generalmente univoci. Insieme, identificano un flusso di dati specifico tra il provider di contatti e un servizio esterno.

Se vuoi trasferire i dati del tuo servizio al fornitore di contatti, devi scrivere un tuo adattatore di sincronizzazione. Questa operazione è descritta in maggiore dettaglio nella sezione Adattatori di sincronizzazione del Provider di contatti.

La Figura 4 mostra come il fornitore di contatti si inserisce nel flusso di dati sulle persone. Ogni adattatore è etichettato in base al tipo di account nella casella "Adattatori di sincronizzazione".

Figura 4. Il flusso di dati del fornitore di contatti.

Autorizzazioni richieste

Le applicazioni che desiderano accedere al provider di contatti devono richiedere le seguenti autorizzazioni:

Accesso in lettura a una o più tabelle

READ_CONTACTS, specificato in AndroidManifest.xml con l'elemento <uses-permission> come <uses-permission android:name="android.permission.READ_CONTACTS">.

Accesso in scrittura a una o più tabelle

WRITE_CONTACTS, specificato in AndroidManifest.xml con l'elemento <uses-permission> come <uses-permission android:name="android.permission.WRITE_CONTACTS">.

Queste autorizzazioni non si estendono ai dati del profilo utente. Il profilo utente e le autorizzazioni richieste sono illustrati nella sezione seguente, Il profilo utente.

Ricorda che i dati di contatto dell'utente sono personali e sensibili. Gli utenti sono preoccupati per la loro privacy, pertanto non vogliono che le applicazioni raccolgano dati su di loro o sui loro contatti. Se il motivo per cui hai bisogno dell'autorizzazione per accedere ai dati dei contatti potrebbe non essere chiaro, l'applicazione potrebbe dare valutazioni basse alla tua applicazione o semplicemente rifiutarsi di installarla.

Il profilo utente

La tabella ContactsContract.Contacts ha una singola riga contenente i dati del profilo dell'utente del dispositivo. Questi dati descrivono il numero user del dispositivo anziché uno dei contatti dell'utente. La riga dei contatti del profilo è collegata a una riga dei contatti non elaborata per ogni sistema che utilizza un profilo. Ogni riga di contatto non elaborata del profilo può avere più righe di dati. Le costanti per l'accesso al profilo utente sono disponibili nella classe ContactsContract.Profile.

L'accesso al profilo utente richiede autorizzazioni speciali. Oltre alle autorizzazioni READ_CONTACTS e WRITE_CONTACTS necessarie per la lettura e la scrittura, l'accesso al profilo utente richiede rispettivamente le autorizzazioni android.Manifest.permission#READ_PROFILE e android.Manifest.permission#WRITE_PROFILE per l'accesso in lettura e scrittura.

Ricorda che devi considerare delicatezza il profilo di un utente. L'autorizzazione android.Manifest.permission#READ_PROFILE ti consente di accedere ai dati che consentono l'identificazione personale dell'utente del dispositivo. Assicurati di spiegare all'utente il motivo per cui hai bisogno delle autorizzazioni di accesso al profilo utente nella descrizione dell'applicazione.

Per recuperare la riga del contatto che contiene il profilo dell'utente, chiama ContentResolver.query(). Imposta l'URI del contenuto su CONTENT_URI e non fornire alcun criterio di selezione. Puoi anche utilizzare questo URI di contenuti come URI di base per recuperare contatti o dati non elaborati per il profilo. Ad esempio, questo snippet recupera i dati per il profilo:

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

Nota: se recuperi più righe dei contatti e vuoi determinare se una di queste è il profilo utente, verifica la colonna IS_USER_PROFILE della riga. Questa colonna è impostata su "1" se il contatto è il profilo utente.

Metadati del fornitore di contatti

Il fornitore di contatti gestisce i dati che tengono traccia dello stato dei dati dei contatti nel repository. Questi metadati relativi al repository sono archiviati in varie posizioni, tra cui le righe della tabella Contatti, Dati e Contatti non elaborati, la tabella ContactsContract.Settings e la tabella ContactsContract.SyncState. La tabella seguente mostra l'effetto di ciascuno di questi metadati:

Tabella 3. Metadati nel fornitore di contatti

Tabella	Colonna	Valori	Significato
ContactsContract.RawContacts	DIRTY	"0": non modificato dall'ultima sincronizzazione.	Contrassegna i contatti non elaborati che sono stati modificati sul dispositivo e che devono essere sincronizzati di nuovo con il server. Il valore viene impostato automaticamente dal provider di contatti quando le applicazioni Android aggiornano una riga. Gli adattatori di sincronizzazione che modificano le tabelle di dati o i contatti non elaborati devono sempre aggiungere la stringa CALLER_IS_SYNCADAPTER all'URI dei contenuti che utilizzano. In questo modo, il provider non può contrassegnare le righe come sporche. In caso contrario, le modifiche dell'adattatore di sincronizzazione sembrano essere modifiche locali e vengono inviate al server, anche se il server è l'origine della modifica.
		"1" - modificato dall'ultima sincronizzazione, deve essere sincronizzato di nuovo con il server.
ContactsContract.RawContacts	VERSION	Il numero di versione di questa riga.	Il fornitore di contatti incrementa automaticamente questo valore ogni volta che la riga o i dati correlati vengono modificati.
ContactsContract.Data	DATA_VERSION	Il numero di versione di questa riga.	Il fornitore di contatti incrementa automaticamente questo valore ogni volta che la riga di dati viene modificata.
ContactsContract.RawContacts	SOURCE_ID	Un valore stringa che identifica in modo univoco questo contatto non elaborato nell'account in cui è stato creato.	Quando un adattatore di sincronizzazione crea un nuovo contatto non elaborato, questa colonna deve essere impostata sull'ID univoco del server per il contatto non elaborato. Quando un'applicazione Android crea un nuovo contatto non elaborato, questa colonna deve essere lasciata vuota. In questo modo viene segnalato all'adattatore di sincronizzazione che deve creare un nuovo contatto non elaborato sul server e ottenere un valore per SOURCE_ID. In particolare, l'ID origine deve essere univoco per ogni tipo di account e deve essere stabile tra le sincronizzazioni: Unico: ogni contatto non elaborato per un account deve avere un proprio ID origine. Se non applichi questa impostazione, si verificheranno problemi nell'applicazione dei contatti. Tieni presente che due contatti non elaborati per lo stesso tipo di account possono avere lo stesso ID origine. Ad esempio, il contatto non elaborato "Thomas Higginson" per l'account [e-mail] può avere lo stesso ID origine del contatto non elaborato "Thomas Higginson" per l'account [e-mail]. Stabile: gli ID origine fanno parte permanente dei dati del servizio online per il contatto non elaborato. Ad esempio, se l'utente cancella lo spazio di archiviazione dei contatti dalle impostazioni dell'app ed esegue di nuovo la sincronizzazione, i contatti non elaborati ripristinati devono avere gli stessi ID origine di prima. Se non applichi questa impostazione, le scorciatoie smetteranno di funzionare.
ContactsContract.Groups	GROUP_VISIBLE	"0" - I contatti di questo gruppo non dovrebbero essere visibili nelle interfacce utente delle applicazioni Android.	Questa colonna consente di verificare la compatibilità con i server che consentono a un utente di nascondere i contatti in determinati gruppi.
		"1" - I contatti di questo gruppo possono essere visibili nelle interfacce utente delle applicazioni.
ContactsContract.Settings	UNGROUPED_VISIBLE	"0": per questo tipo di account e account, i contatti che non appartengono a un gruppo non sono visibili alle interfacce utente delle applicazioni Android.	Per impostazione predefinita, i contatti sono invisibili se nessuno dei loro contatti non elaborati appartiene a un gruppo (l'appartenenza al gruppo per un contatto non elaborato è indicata da una o più righe ContactsContract.CommonDataKinds.GroupMembership nella tabella ContactsContract.Data). Se imposti questo flag nella riga della tabella ContactsContract.Settings per un tipo di account e un account, puoi forzare la visualizzazione dei contatti senza gruppi. Questo flag viene utilizzato per mostrare i contatti dei server che non utilizzano gruppi.
		"1": per questo tipo di account e account, i contatti che non appartengono a un gruppo sono visibili nelle interfacce utente delle applicazioni.
ContactsContract.SyncState	(tutti)	Utilizza questa tabella per archiviare i metadati relativi all'adattatore di sincronizzazione.	Con questa tabella puoi archiviare lo stato della sincronizzazione e altri dati relativi alla sincronizzazione in modo permanente sul dispositivo.

Accesso del fornitore di contatti

Questa sezione descrive le linee guida per l'accesso ai dati dal fornitore di contatti, in particolare sui seguenti aspetti:

• Query sulle entità.
• Modifica in batch.
• Recupero e modifica con intenti.
• Integrità dei dati.

Anche le modifiche da un adattatore di sincronizzazione sono trattate in maggiore dettaglio nella sezione Adattatori di sincronizzazione del provider di contatti.

Esecuzione di query sulle entità

Poiché le tabelle del provider di contatti sono organizzate in una gerarchia, spesso è utile recuperare una riga e tutte le righe "secondarie" ad essa collegate. Ad esempio, per visualizzare tutte le informazioni relative a una persona, puoi recuperare tutte le righe ContactsContract.RawContacts per una singola riga ContactsContract.Contacts o tutte le righe ContactsContract.CommonDataKinds.Email per una singola riga ContactsContract.RawContacts. Per facilitare questa operazione, il provider di contatti offre costrutti di entità, che agiscono come join di database tra tabelle.

Un'entità è come una tabella composta da colonne selezionate provenienti da una tabella padre e da una tabella figlio. Quando esegui una query su un'entità, fornisci una proiezione e un criterio di ricerca basati sulle colonne disponibili dall'entità. Il risultato è un valore Cursor che contiene una riga per ogni riga della tabella figlio recuperata. Ad esempio, se esegui una query su ContactsContract.Contacts.Entity per trovare un nome di contatto e su tutte le righe ContactsContract.CommonDataKinds.Email per tutti i contatti non elaborati per quel nome, verrà restituito un Cursor contenente una riga per ogni riga ContactsContract.CommonDataKinds.Email.

Le entità semplificano le query. Utilizzando un'entità, puoi recuperare contemporaneamente tutti i dati dei contatti di un contatto o di un contatto non elaborato, anziché dover prima eseguire una query sulla tabella padre per ottenere un ID e poi eseguire una query sulla tabella figlio con questo ID. Inoltre, il fornitore di contatti elabora una query su un'entità in una singola transazione, assicurando che i dati recuperati siano coerenti internamente.

Nota: di solito un'entità non contiene tutte le colonne delle tabelle padre e figlio. Se provi a lavorare con un nome di colonna che non è presente nell'elenco delle costanti dei nomi di colonna per l'entità, otterrai un Exception.

Il seguente snippet mostra come recuperare tutte le righe dei contatti non elaborate di un contatto. Lo snippet fa parte di un'applicazione più grande che ha due attività, "main" e "detail". L'attività principale mostra un elenco di righe di contatti; quando l'utente ne seleziona una, l'attività invia il suo ID all'attività dei dettagli. L'attività dei dettagli utilizza ContactsContract.Contacts.Entity per visualizzare tutte le righe di dati di tutti i contatti non elaborati associati al contatto selezionato.

Questo snippet è ricavato dall'attività "detail":

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

Al termine del caricamento, LoaderManager richiama un callback per onLoadFinished(). Uno degli argomenti in entrata in questo metodo è un Cursor con i risultati della query. Nella tua app puoi recuperare i dati di questo Cursor per visualizzarli o utilizzarli ulteriormente.

Modifica in batch

Quando possibile, devi inserire, aggiornare ed eliminare i dati nel provider di contatti in "modalità batch", creando un ArrayList di ContentProviderOperation oggetti e chiamando applyBatch(). Poiché il provider di contatti esegue tutte le operazioni in applyBatch() in una singola transazione, le modifiche non lasceranno mai il repository dei contatti in uno stato incoerente. La modifica batch semplifica anche l'inserimento di un contatto non elaborato e dei relativi dati dettagliati contemporaneamente.

Nota: per modificare un singolo contatto non elaborato, potresti inviare un intent all'applicazione dei contatti del dispositivo anziché gestire la modifica nell'app. Questa operazione è descritta più dettagliatamente nella sezione Recupero e modifica con intent.

Punti di rendimento

Una modifica batch contenente un numero elevato di operazioni può bloccare altri processi, determinando un'esperienza utente complessiva negativa. Per organizzare tutte le modifiche che vuoi eseguire nel minor numero possibile di elenchi separati ed evitare allo stesso tempo che blocchino il sistema, devi impostare i punti di rendimento per una o più operazioni. Un punto di rendimento è un oggetto ContentProviderOperation il cui valore di isYieldAllowed() è impostato su true. Quando il provider di contatti raggiunge un punto di rendimento, mette in pausa il lavoro per consentire l'esecuzione di altri processi e chiude la transazione in corso. Quando il provider riparte, continua con l'operazione successiva in ArrayList e avvia una nuova transazione.

I punti di rendimento comportano più di una transazione per chiamata a applyBatch(). Per questo motivo, devi impostare un punto di rendimento per l'ultima operazione relativa a un insieme di righe correlate. Ad esempio, devi impostare un punto di rendimento per l'ultima operazione in un set che aggiunge righe di contatto non elaborate e le relative righe di dati associate o l'ultima operazione per un insieme di righe relative a un singolo contatto.

I punti di snervamento sono anche un'unità del funzionamento atomico. Tutti gli accessi tra due punti di rendimento avranno esito positivo o negativo come una singola unità. Se non imposti alcun punto di rendimento, l'operazione atomica più piccola è l'intero batch di operazioni. Se utilizzi i punti di rendimento, impedisci alle operazioni di ridurre le prestazioni del sistema, garantendo al contempo che un sottoinsieme di operazioni sia atomico.

Riferimenti a modifiche indietro

Quando inserisci una nuova riga di contatto non elaborata e le relative righe di dati associate come insieme di oggetti ContentProviderOperation, devi collegare le righe di dati alla riga del contatto non elaborata inserendo il valore _ID del contatto non elaborato come valore RAW_CONTACT_ID. Tuttavia, questo valore non è disponibile quando crei ContentProviderOperation per la riga di dati, perché non hai ancora applicato ContentProviderOperation per la riga di contatto non elaborata. Per risolvere questo problema, la classe ContentProviderOperation.Builder ha il metodo withValueBackReference(). Questo metodo consente di inserire o modificare una colonna con il risultato di un'operazione precedente.

Il metodo withValueBackReference() ha due argomenti:

key

La chiave di una coppia chiave-valore. Il valore di questo argomento deve essere il nome di una colonna nella tabella che stai modificando.

previousResult

L'indice in base 0 di un valore nell'array di oggetti ContentProviderResult di applyBatch(). Quando vengono applicate le operazioni batch, il risultato di ogni operazione viene archiviato in un array intermedio di risultati. Il valore previousResult è l'indice di uno di questi risultati, che viene recuperato e archiviato con il valore key. Ciò ti consente di inserire un nuovo record di contatto non elaborato e di recuperare il suo valore _ID, quindi di creare un "backreference" al valore quando aggiungi una riga ContactsContract.Data.

L'intero array dei risultati viene creato quando chiami per la prima volta applyBatch(), con una dimensione pari a quella degli oggetti ArrayList di ContentProviderOperation che fornisci. Tuttavia, tutti gli elementi nell'array dei risultati sono impostati su null e, se provi a eseguire un riferimento a ritroso a un risultato per un'operazione non ancora applicata, withValueBackReference() restituisce un valore Exception.

Gli snippet seguenti mostrano come inserire un nuovo contatto e dati non elaborati in gruppo. Includono codice che stabilisce un punto di rendimento e utilizza un backreference.

Il primo snippet recupera i dati dei contatti dall'interfaccia utente. A questo punto, l'utente ha già selezionato l'account per cui aggiungere il nuovo contatto non elaborato.

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());

Lo snippet successivo crea un'operazione per inserire la riga di contatto non elaborata nella tabella 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());

Successivamente, il codice crea righe di dati per le righe del nome visualizzato, del numero di telefono e dell'email.

Ogni oggetto del generatore di operazioni utilizza withValueBackReference() per ottenere RAW_CONTACT_ID. Il riferimento torna all'oggetto ContentProviderResult dalla prima operazione, che aggiunge la riga di contatto non elaborata e restituisce il nuovo valore _ID. Di conseguenza, ogni riga di dati viene collegata automaticamente dal relativo RAW_CONTACT_ID alla nuova riga ContactsContract.RawContacts a cui appartiene.

L'oggetto ContentProviderOperation.Builder che aggiunge la riga dell'email viene contrassegnato con withYieldAllowed(), che imposta un punto di 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());

L'ultimo snippet mostra la chiamata a applyBatch() che inserisce le nuove righe di dati e contatti non elaborati.

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

Le operazioni batch consentono inoltre di implementare il controllo ottimistico della contemporaneità, un metodo per applicare transazioni di modifica senza dover bloccare il repository sottostante. Per utilizzare questo metodo, applica la transazione e poi verifica la presenza di altre modifiche che potrebbero essere state apportate contemporaneamente. Se ritieni che si sia verificata una modifica incoerente, esegui il rollback della transazione e riprova.

Il controllo ottimistico della contemporaneità è utile per i dispositivi mobili dove esiste un solo utente alla volta e gli accessi simultanei a un repository di dati sono rari. Poiché non viene utilizzato il blocco, non si perde tempo a bloccare le impostazioni o ad attendere il rilascio di altre transazioni.

Per utilizzare il controllo ottimistico della contemporaneità durante l'aggiornamento di una singola riga ContactsContract.RawContacts, segui questi passaggi:

1. Recupera la colonna VERSION del contatto non elaborato insieme agli altri dati recuperati.
2. Crea un oggetto ContentProviderOperation.Builder adatto per l'applicazione di un vincolo, utilizzando il metodo newAssertQuery(Uri). Per l'URI dei contenuti, utilizza RawContacts.CONTENT_URI aggiungendo _ID del contatto non elaborato.
3. Per l'oggetto ContentProviderOperation.Builder, chiama withValue() per confrontare la colonna VERSION con il numero di versione appena recuperato.
4. Per lo stesso ContentProviderOperation.Builder, chiama withExpectedCount() per assicurarti che solo una riga venga testata da questa asserzione.
5. Chiama build() per creare l'oggetto ContentProviderOperation, quindi aggiungi questo oggetto come primo oggetto nel ArrayList che passi a applyBatch().
6. Applica la transazione batch.

Se la riga del contatto non elaborata viene aggiornata da un'altra operazione tra il momento in cui la leggi e il momento in cui tenti di modificarla, l'istruzione ContentProviderOperation di "asserto" non andrà a buon fine e verrà eseguito il backup dell'intero batch di operazioni. Puoi quindi scegliere di riprovare a eseguire il batch o eseguire un'altra azione.

Lo snippet seguente mostra come creare una "assert" ContentProviderOperation dopo aver eseguito una query per un singolo contatto non elaborato utilizzando un 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
    }

Recupero e modifica con intent

L'invio di un intent all'applicazione dei contatti del dispositivo consente di accedere indirettamente al provider di contatti. L'intent avvia l'interfaccia utente dell'applicazione per i contatti del dispositivo, in cui gli utenti possono svolgere le operazioni relative ai contatti. Con questo tipo di accesso, gli utenti possono:

• Scegli un contatto da un elenco e fallo restituire alla tua app per ulteriori attività.
• Modificare i dati di un contatto esistente.
• Inserisci un nuovo contatto non elaborato per i suoi account.
• Eliminare i dati di un contatto o dei contatti.

Se l'utente inserisce o aggiorna i dati, puoi prima raccoglierli e inviarli come parte dell'intent.

Quando utilizzi intent per accedere al fornitore di contatti tramite l'applicazione per i contatti del dispositivo, non devi scrivere una UI o un codice personalizzati per accedere al provider. Inoltre, non è necessario richiedere l'autorizzazione di lettura o scrittura al provider. L'applicazione Contatti del dispositivo può delegare a te l'autorizzazione di lettura per un contatto e, poiché stai apportando modifiche al provider tramite un'altra applicazione, non devi disporre di autorizzazioni di scrittura.

Il processo generale di invio di un intent per accedere a un provider è descritto in dettaglio nella guida Nozioni di base sui fornitori di contenuti nella sezione "Accesso ai dati tramite intent". L'azione, il tipo MIME e i valori dei dati che utilizzi per le attività disponibili sono riepilogati nella tabella 4, mentre i valori extra che puoi utilizzare con putExtra() sono elencati nella documentazione di riferimento per ContactsContract.Intents.Insert:

Tabella 4. Intent del provider di contatti.

Attività	Azione	Dati	Tipo MIME	Notes
Scegliere un contatto da un elenco	ACTION_PICK	Uno dei seguenti valori: Contacts.CONTENT_URI, che mostra un elenco di contatti. Phone.CONTENT_URI, che mostra un elenco di numeri di telefono per un contatto non elaborato. StructuredPostal.CONTENT_URI, che mostra un elenco di indirizzi postali per un contatto non elaborato. Email.CONTENT_URI, che mostra un elenco di indirizzi email per un contatto non elaborato.	Not used	Visualizza un elenco di contatti non elaborati o un elenco di dati di un contatto non elaborato, a seconda del tipo di URI dei contenuti che fornisci. Richiama startActivityForResult(), che restituisce l'URI dei contenuti della riga selezionata. La forma dell'URI è l'URI dei contenuti della tabella, a cui è aggiunto il valore LOOKUP_ID della riga. L'app Contatti del dispositivo delega le autorizzazioni di lettura e scrittura a questo URI dei contenuti per l'intera durata della tua attività. Per ulteriori dettagli, consulta la guida Nozioni di base sui fornitori di contenuti.
Inserire un nuovo contatto non elaborato	Insert.ACTION	N/A	RawContacts.CONTENT_TYPE, tipo MIME per un insieme di contatti non elaborati.	Visualizza la schermata Aggiungi contatto dell'applicazione Contatti del dispositivo. Vengono visualizzati i valori extra che aggiungi all'intent. Se inviato con startActivityForResult(), l'URI dei contenuti del contatto non elaborato appena aggiunto viene restituito al metodo di callback onActivityResult() dell'attività nell'argomento Intent, nel campo "dati". Per ottenere il valore, chiama getData().
Modificare un contatto	ACTION_EDIT	CONTENT_LOOKUP_URI per il contatto. L'attività di modifica consentirà all'utente di modificare qualsiasi dato associato a questo contatto.	Contacts.CONTENT_ITEM_TYPE, un unico contatto.	Visualizza la schermata Modifica contatto nell'applicazione contatti. Vengono visualizzati i valori extra che aggiungi all'intent. Quando l'utente fa clic su Fine per salvare le modifiche, la tua attività torna in primo piano.
Mostra un selettore che possa anche aggiungere dati.	ACTION_INSERT_OR_EDIT	N/A	CONTENT_ITEM_TYPE	Questo intent mostra sempre la schermata di selezione dell'app Contatti. L'utente può scegliere un contatto da modificare o aggiungere un nuovo contatto. A seconda della scelta dell'utente, viene visualizzata la schermata relativa alla modifica o all'aggiunta e vengono mostrati i dati extra trasmessi nell'intent. Se la tua app mostra dati di contatto, ad esempio un indirizzo email o un numero di telefono, utilizza questo intent per consentire all'utente di aggiungere i dati a un contatto esistente. contatto, Nota:non è necessario inviare un valore nome negli extra di questo intent perché l'utente sceglie sempre un nome esistente o ne aggiunge uno nuovo. Inoltre, se invii un nome e l'utente sceglie di apportare una modifica, l'app Contatti mostrerà il nome inviato, sovrascrivendo il valore precedente. Se l'utente non si accorge e salva la modifica, il valore precedente andrà perso.

L'app Contatti del dispositivo non consente di eliminare un contatto non elaborato o eventuali relativi dati con un intent. Per eliminare un contatto non elaborato, utilizza invece ContentResolver.delete() o ContentProviderOperation.newDelete().

Lo snippet seguente mostra come creare e inviare un intent che inserisce un nuovo contatto e dati non elaborati:

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

Integrità dei dati

Poiché il repository dei contatti contiene dati importanti e sensibili che gli utenti si aspettano che siano corretti e aggiornati, il fornitore di contatti ha regole ben definite per l'integrità dei dati. È tua responsabilità rispettare queste regole quando modifichi i dati dei contatti. Le regole importanti sono elencate qui:

Aggiungi sempre una riga ContactsContract.CommonDataKinds.StructuredName per ogni riga ContactsContract.RawContacts che aggiungi.

Una riga ContactsContract.RawContacts senza una riga ContactsContract.CommonDataKinds.StructuredName nella tabella ContactsContract.Data può causare problemi durante l'aggregazione.

Collega sempre le nuove righe ContactsContract.Data alla riga ContactsContract.RawContacts principale.

Una riga ContactsContract.Data non collegata a ContactsContract.RawContacts non sarà visibile nell'applicazione Contatti del dispositivo e potrebbe causare problemi con gli adattatori di sincronizzazione.

Modificare solo i dati dei contatti non elaborati di tua proprietà.

Ricorda che in genere il fornitore di contatti gestisce i dati di diversi tipi di account/servizi online. Devi assicurarti che l'applicazione modifichi o elimini solo i dati delle righe di tua proprietà e che inserisca solo i dati con un tipo e un nome di account controllati da te.

Utilizza sempre le costanti definite in ContactsContract e nelle relative sottoclassi per autorità, URI dei contenuti, percorsi URI, nomi colonna, tipi MIME e valori TYPE.

L'uso di queste costanti consente di evitare errori. Se una delle costanti è deprecata, riceverai anche una notifica con avvisi del compilatore.

Righe di dati personalizzate

Creando e utilizzando tipi MIME personalizzati, puoi inserire, modificare, eliminare e recuperare le tue righe di dati nella tabella ContactsContract.Data. Le righe sono limitate all'utilizzo della colonna definita in ContactsContract.DataColumns, anche se puoi mappare i nomi delle tue colonne specifiche per tipo ai nomi delle colonne predefiniti. Nell'applicazione Contatti del dispositivo, i dati per le righe vengono visualizzati, ma non possono essere modificati o eliminati e gli utenti non possono aggiungere ulteriori dati. Per consentire agli utenti di modificare le righe di dati personalizzate, devi fornire un'attività di editor nella tua applicazione.

Per visualizzare i tuoi dati personalizzati, fornisci un file contacts.xml contenente un elemento <ContactsAccountType> e uno o più dei relativi elementi secondari <ContactsDataKind>. Ciò è descritto più dettagliatamente nella sezione <ContactsDataKind> element.

Per saperne di più sui tipi MIME personalizzati, leggi la guida Creare un fornitore di contenuti.

Adattatori di sincronizzazione del fornitore di contatti

Il fornitore di contatti è progettato specificamente per la gestione della sincronizzazione dei dati dei contatti tra un dispositivo e un servizio online. In questo modo, gli utenti possono scaricare i dati esistenti su un nuovo dispositivo e caricare quelli esistenti in un nuovo account. La sincronizzazione assicura inoltre che gli utenti abbiano a portata di mano i dati più recenti, indipendentemente dall'origine delle aggiunte e delle modifiche. Un altro vantaggio della sincronizzazione è che rende disponibili i dati dei contatti anche quando il dispositivo non è connesso alla rete.

Sebbene sia possibile implementare la sincronizzazione in diversi modi, il sistema Android fornisce un framework di sincronizzazione con plug-in che automatizza le seguenti attività:

• Controllo della disponibilità della rete in corso...
• Programmazione ed esecuzione della sincronizzazione, in base alle preferenze dell'utente.
• Riavvio delle sincronizzazioni interrotte.

Per utilizzare questo framework, devi fornire un plug-in per l'adattatore di sincronizzazione. Ogni adattatore di sincronizzazione è univoco per un fornitore di servizi e contenuti, ma può gestire più nomi account per lo stesso servizio. Il framework consente inoltre più adattatori di sincronizzazione per lo stesso servizio e provider.

File e classi di adattatori di sincronizzazione

Puoi implementare un adattatore di sincronizzazione come sottoclasse di AbstractThreadedSyncAdapter e installarlo come parte di un'applicazione Android. Il sistema apprende l'utilizzo dell'adattatore di sincronizzazione dagli elementi del file manifest dell'applicazione e da uno speciale file XML a cui rimanda il file manifest. Il file XML definisce il tipo di account per il servizio online e l'autorità del fornitore di contenuti, che insieme identificano in modo univoco l'adattatore. L'adattatore di sincronizzazione non diventa attivo finché l'utente non aggiunge un account per il tipo di account dell'adattatore di sincronizzazione e non attiva la sincronizzazione per il fornitore di contenuti con cui l'adattatore di sincronizzazione viene sincronizzato. A quel punto, il sistema inizia a gestire l'adattatore, chiamandolo come necessario per la sincronizzazione tra il fornitore di contenuti e il server.

Nota: l'utilizzo di un tipo di account come parte dell'identificazione dell'adattatore di sincronizzazione consente al sistema di rilevare e raggruppare gli adattatori di sincronizzazione che accedono a servizi diversi della stessa organizzazione. Ad esempio, gli adattatori di sincronizzazione per i servizi online di Google hanno tutti lo stesso tipo di account com.google. Quando gli utenti aggiungono un Account Google ai propri dispositivi, tutti gli adattatori di sincronizzazione installati per i servizi Google vengono elencati insieme; ogni adattatore di sincronizzazione elencato si sincronizza con un fornitore di contenuti diverso sul dispositivo.

Poiché la maggior parte dei servizi richiede agli utenti di verificare la propria identità prima di accedere ai dati, il sistema Android offre un framework di autenticazione simile e spesso utilizzato in combinazione con il framework dell'adattatore di sincronizzazione. Il framework di autenticazione utilizza certificati di plug-in che sono sottoclassi di AbstractAccountAuthenticator. Un autenticatore verifica l'identità dell'utente nei seguenti passaggi:

1. Raccoglie il nome, la password o informazioni simili dell'utente (le credenziali dell'utente).
2. Invia le credenziali al servizio
3. Esamina la risposta del servizio.

Se il servizio accetta le credenziali, l'autenticatore può archiviare le credenziali per utilizzarle in un secondo momento. Grazie al framework dell'autenticatore plug-in, AccountManager può fornire l'accesso a tutti i token di autenticazione supportati da un autenticatore e che sceglie di esporre, ad esempio i token di autenticazione OAuth2.

Sebbene l'autenticazione non sia obbligatoria, viene utilizzata dalla maggior parte dei servizi dei contatti. Tuttavia, non è necessario utilizzare il framework di autenticazione di Android per eseguire l'autenticazione.

Implementazione dell'adattatore di sincronizzazione

Per implementare un adattatore di sincronizzazione per il fornitore di contatti, inizia creando un'applicazione Android che contenga quanto segue:

Un componente Service che risponde alle richieste del sistema di associarsi all'adattatore di sincronizzazione.

Quando il sistema vuole eseguire una sincronizzazione, chiama il metodo onBind() del servizio per ottenere un IBinder per l'adattatore di sincronizzazione. Ciò consente al sistema di effettuare chiamate cross-process ai metodi dell'adattatore.

L'effettivo adattatore di sincronizzazione, implementato come una sottoclasse concreta di AbstractThreadedSyncAdapter.

Questa classe si occupa di scaricare i dati dal server, caricarli dal dispositivo e risolvere i conflitti. Il lavoro principale dell'adattatore viene svolto nel metodo onPerformSync(). È necessario creare un'istanza di questa classe come singleton.

Una sottoclasse di Application.

Questa classe funge da fabbrica per il singleton dell'adattatore di sincronizzazione. Utilizza il metodo onCreate() per creare un'istanza dell'adattatore di sincronizzazione e fornire un metodo "getter" statico per restituire il singleton al metodo onBind() del servizio dell'adattatore di sincronizzazione.

Facoltativo: un componente Service che risponde alle richieste del sistema per l'autenticazione degli utenti.

AccountManager avvia questo servizio per iniziare il processo di autenticazione. Il metodo onCreate() del servizio crea un'istanza di un oggetto di autenticazione. Quando il sistema vuole autenticare un account utente per l'adattatore di sincronizzazione dell'applicazione, chiama il metodo onBind() del servizio per ottenere un IBinder per l'autenticatore. Ciò consente al sistema di effettuare chiamate cross-process ai metodi dell'autenticatore.

Facoltativo: una sottoclasse concreta di AbstractAccountAuthenticator che gestisce le richieste di autenticazione.

Questa classe fornisce i metodi utilizzati da AccountManager per autenticare le credenziali dell'utente con il server. I dettagli del processo di autenticazione variano notevolmente in base alla tecnologia server in uso. Per saperne di più sull'autenticazione, consulta la documentazione del software server.

File XML che definiscono l'adattatore di sincronizzazione e l'autenticatore per il sistema.

I componenti del servizio dell'adattatore di sincronizzazione e dell'autenticatore descritti in precedenza sono definiti negli elementi <service> del file manifest dell'applicazione. Questi elementi contengono <meta-data> elementi secondari che forniscono dati specifici al sistema:

• L'elemento <meta-data> del servizio dell'adattatore di sincronizzazione rimanda al file XML res/xml/syncadapter.xml. A sua volta, questo file specifica un URI per il servizio web che verrà sincronizzato con il provider di contatti e un tipo di account per il servizio web.
• Facoltativo: l'elemento <meta-data> per l'autenticatore rimanda al file XML res/xml/authenticator.xml. A sua volta, questo file specifica il tipo di account supportato da questo autenticatore, nonché le risorse UI che vengono visualizzate durante il processo di autenticazione. Il tipo di account specificato in questo elemento deve essere uguale a quello specificato per l'adattatore di sincronizzazione.

Dati stream social

Le tabelle android.provider.ContactsContract.StreamItems e android.provider.ContactsContract.StreamItemPhotos gestiscono i dati in entrata dai social network. Puoi scrivere un adattatore di sincronizzazione che aggiunga flussi di dati dalla tua rete a queste tabelle, leggere i dati dei flussi di queste tabelle e visualizzarli nella tua applicazione oppure in entrambe. Con queste funzionalità, le tue applicazioni e i tuoi servizi di social networking possono essere integrati nell'esperienza di social networking di Android.

Testo stream social

Gli elementi dello stream sono sempre associati a un contatto non elaborato. Il android.provider.ContactsContract.StreamItemscolumn#RAW_CONTACT_ID rimanda al valore _ID del contatto non elaborato. Nella riga dell'elemento dello stream vengono archiviati anche il tipo e il nome dell'account del contatto non elaborato.

Archivia i dati dello stream nelle seguenti colonne:

android.provider.ContactsContract.StreamItemsColonne#ACCOUNT_TYPE

Obbligatorio. Il tipo di account dell'utente per il contatto non elaborato associato a questo elemento di stream. Ricordati di impostare questo valore quando inserisci un elemento dello stream.

android.provider.ContactsContract.StreamItemsColonne#ACCOUNT_NAME

Obbligatorio. Il nome dell'account utente per il contatto non elaborato associato a questo elemento di stream. Ricordati di impostare questo valore quando inserisci un elemento dello stream.

Colonne dell'identificatore

Obbligatorio. Quando inserisci un elemento dello stream, devi inserire le seguenti colonne degli identificatori:

• android.provider.ContactsContract.StreamItemsColumn#CONTACT_ID: il valore android.provider.Base bolle#_ID del contatto a cui è associato questo elemento di flusso.
• android.provider.ContactsContract.StreamItems pertanto#CONTACT_LOOKUP_KEY: il valore android.provider.ContactsContract.ContactsContacts#LOOKUP_KEY del contatto a cui è associato questo elemento dello stream.
• android.provider.ContactsContract.StreamItems pertantoColonne#RAW_CONTACT_ID: il valore android.provider.Base bolle#_ID del contatto non elaborato a cui è associato questo elemento di flusso.

android.provider.ContactsContract.StreamItemsColonne#COMMENTS

Facoltativo. Memorizza le informazioni di riepilogo che puoi visualizzare all'inizio di un elemento dello stream.

android.provider.ContactsContract.StreamItemsColonne#TEXT

Il testo dell'elemento di streaming, ovvero i contenuti pubblicati dall'origine dell'elemento o una descrizione di un'azione che ha generato l'elemento dello stream. Questa colonna può contenere qualsiasi formattazione e immagine delle risorse incorporate di cui fromHtml() può eseguire il rendering. Il provider potrebbe troncare o fare puntini di sospensione dei contenuti lunghi, ma cercherà di evitare di rompere i tag.

android.provider.ContactsContract.StreamItemsColumn#TIMESTAMP

Una stringa di testo contenente l'ora in cui l'elemento di streaming è stato inserito o aggiornato, sotto forma di millisecondi dall'epoca. Le applicazioni che inseriscono o aggiornano elementi del flusso sono responsabili della manutenzione di questa colonna, che non viene gestita automaticamente dal provider di contatti.

Per visualizzare le informazioni identificative degli elementi dello stream, utilizza android.provider.ContactsContract.StreamItems pertantoColonne#RES_ICON, android.provider.ContactsContract.StreamItemsColonne#RES_LABEL e android.provider.ContactsContract.StreamItemsColumn#RES_PACKAGE per collegarti alle risorse nell'applicazione.

La tabella android.provider.ContactsContract.StreamItems contiene anche le colonne android.provider.ContactsContract.StreamItemsColumn#SYNC1 tramite android.provider.ContactsContract.StreamItemscolumn#SYNC4 per l'uso esclusivo degli adattatori di sincronizzazione.

Foto stream social

La tabella android.provider.ContactsContract.StreamItemPhotos archivia le foto associate a un elemento dello stream. La colonna android.provider.ContactsContract.StreamItemPhotosColumn#STREAM_ITEM_ID rimanda ai valori nella colonna _ID della tabella android.provider.ContactsContract.StreamItems. I riferimenti alle foto sono archiviati nella tabella in queste colonne:

colonna android.provider.ContactsContract.StreamItemPhotos#PHOTO (un BLOB).

Una rappresentazione binaria della foto, ridimensionata dal provider per l'archiviazione e la visualizzazione. Questa colonna è disponibile per la compatibilità con le versioni precedenti del provider di contatti che la utilizzava per l'archiviazione delle foto. Tuttavia, nella versione attuale non devi utilizzare questa colonna per archiviare le foto. Utilizza invece android.provider.ContactsContract.StreamItemPhotosColumn#PHOTO_FILE_ID o android.provider.ContactsContract.StreamItemPhotoscolumn#PHOTO_URI (entrambi descritti nei punti seguenti) per archiviare le foto in un file. Questa colonna ora contiene una miniatura della foto, disponibile per la lettura.

android.provider.ContactsContract.StreamItemFotoColonne#PHOTO_FILE_ID

Un identificatore numerico di una foto per un contatto non elaborato. Aggiungi questo valore alla costante DisplayPhoto.CONTENT_URI per ottenere un URI di contenuti che rimanda a un singolo file di foto, quindi chiama openAssetFileDescriptor() per ottenere un handle al file di foto.

android.provider.ContactsContract.StreamItemPhotosColumn#PHOTO_URI

Un URI di contenuti che rimanda direttamente al file della foto rappresentata da questa riga. Chiama openAssetFileDescriptor() con questo URI per ottenere un handle per il file di foto.

Utilizzare le tabelle dei social stream

Queste tabelle funzionano come le altre tabelle principali nel provider di contatti, ad eccezione del fatto che:

• Queste tabelle richiedono autorizzazioni di accesso aggiuntive. Per leggere questi dati, la tua applicazione deve avere l'autorizzazione android.Manifest.permission#READ_SOCIAL_STREAM. Per modificarli, la tua applicazione deve avere l'autorizzazione android.Manifest.permission#WRITE_SOCIAL_STREAM.
• Per la tabella android.provider.ContactsContract.StreamItems, il numero di righe archiviate per ogni contatto non elaborato è limitato. Una volta raggiunto questo limite, il fornitore di contatti libera spazio per le nuove righe degli elementi dello stream eliminando automaticamente le righe che contengono il valore android.provider.ContactsContract.StreamItemsColumn#TIMESTAMP. Per ottenere il limite, esegui una query all'URI dei contenuti android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI. Puoi lasciare tutti gli argomenti diversi dall'URI dei contenuti impostati su null. La query restituisce un cursore contenente una singola riga, con la colonna singola android.provider.ContactsContract.StreamItems#MAX_ITEMS.

La classe android.provider.ContactsContract.StreamItems.StreamItemPhotos definisce una sottotabella di android.provider.ContactsContract.StreamItemPhotos contenente le righe di foto per un singolo elemento dello stream.

Interazioni con gli stream social

I dati del social stream gestiti dal provider di contatti, insieme all'applicazione per i contatti del dispositivo, offrono un metodo efficace per connettere il tuo sistema di social network ai contatti esistenti. Sono disponibili le seguenti funzionalità:

• Se sincronizzi il tuo servizio di social networking con il fornitore di contatti con un adattatore di sincronizzazione, puoi recuperare l'attività recente dei contatti di un utente e memorizzarla nelle tabelle android.provider.ContactsContract.StreamItems e android.provider.ContactsContract.StreamItemPhotos per un utilizzo futuro.
• Oltre alla sincronizzazione normale, puoi attivare l'adattatore di sincronizzazione in modo che recuperi dati aggiuntivi quando l'utente seleziona un contatto da visualizzare. In questo modo l'adattatore di sincronizzazione può recuperare foto ad alta risoluzione e gli elementi dello stream più recenti per il contatto.
• Registrando una notifica con l'applicazione contatti del dispositivo e il provider di contatti, puoi ricevere un intent quando viene visualizzato un contatto e, a quel punto, aggiornare lo stato del contatto dal tuo servizio. Questo approccio potrebbe essere più rapido e utilizzare meno larghezza di banda rispetto a una sincronizzazione completa con un adattatore di sincronizzazione.
• Gli utenti possono aggiungere un contatto al servizio di social networking mentre lo visualizzano nell'applicazione dei contatti del dispositivo. Puoi attivare questa funzionalità con la funzionalità "Invita contatto", che puoi attivare con una combinazione di un'attività che aggiunge un contatto esistente alla tua rete e un file XML che fornisce i dettagli dell'applicazione all'applicazione per i contatti del dispositivo e al provider di contatti.

La sincronizzazione regolare degli elementi dello stream con il provider di contatti è la stessa di altre sincronizzazioni. Per scoprire di più sulla sincronizzazione, consulta la sezione Adattatori di sincronizzazione del provider contatti. La registrazione delle notifiche e gli inviti ai contatti sono trattati nelle prossime due sezioni.

Registrazione per gestire le visualizzazioni sui social network

Per registrare l'adattatore di sincronizzazione in modo da ricevere notifiche quando l'utente visualizza un contatto gestito dall'adattatore:

1. Crea un file denominato contacts.xml nella directory res/xml/ del tuo progetto. Se hai già il file, puoi saltare questo passaggio.
2. In questo file, aggiungi l'elemento <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">. Se questo elemento esiste già, puoi saltare questo passaggio.
3. Per registrare un servizio che viene avvisato quando l'utente apre la pagina dei dettagli di un contatto nell'applicazione dei contatti del dispositivo, aggiungi l'attributo viewContactNotifyService="serviceclass" all'elemento, dove serviceclass è il nome di classe completo del servizio che dovrebbe ricevere l'intent dall'applicazione dei contatti del dispositivo. Per il servizio di notifica, utilizza una classe che estende IntentService, in modo da consentire al servizio di ricevere gli intent. I dati nell'intent in entrata contengono l'URI dei contenuti del contatto non elaborato su cui l'utente ha fatto clic. Dal servizio di notifica, puoi associare e poi chiamare l'adattatore di sincronizzazione per aggiornare i dati relativi al contatto non elaborato.

Per registrare un'attività da chiamare quando l'utente fa clic su un elemento dello stream, su una foto o su entrambi:

1. Crea un file denominato contacts.xml nella directory res/xml/ del tuo progetto. Se hai già il file, puoi saltare questo passaggio.
2. In questo file, aggiungi l'elemento <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">. Se questo elemento esiste già, puoi saltare questo passaggio.
3. Per registrare una delle tue attività per gestire l'utente che fa clic su un elemento di streaming nell'applicazione dei contatti del dispositivo, aggiungi l'attributo viewStreamItemActivity="activityclass" all'elemento, dove activityclass è il nome di classe completo dell'attività che dovrebbe ricevere l'intent dall'applicazione dei contatti del dispositivo.
4. Per registrare una delle tue attività per gestire l'utente che fa clic su una foto in streaming nell'applicazione dei contatti del dispositivo, aggiungi l'attributo viewStreamItemPhotoActivity="activityclass" all'elemento, dove activityclass è il nome di classe completo dell'attività che dovrebbe ricevere l'intent dall'applicazione dei contatti del dispositivo.

L'elemento <ContactsAccountType> è descritto più dettagliatamente nella sezione Elemento <ContactsAccountType>.

L'intent in entrata contiene l'URI dei contenuti dell'elemento o della foto su cui l'utente ha fatto clic. Per creare attività distinte per gli elementi di testo e per le foto, utilizza entrambi gli attributi nello stesso file.

Interazione con il servizio di social network

Gli utenti non devono uscire dall'applicazione dei contatti del dispositivo per invitare un contatto sul tuo sito di social network. In alternativa, puoi fare in modo che l'app Contatti del dispositivo invii un intent per invitare il contatto a una delle tue attività. Per configurare questa impostazione:

1. Crea un file denominato contacts.xml nella directory res/xml/ del tuo progetto. Se hai già il file, puoi saltare questo passaggio.
2. In questo file, aggiungi l'elemento <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">. Se questo elemento esiste già, puoi saltare questo passaggio.
3. Aggiungi i seguenti attributi:
   • inviteContactActivity="activityclass"
   • inviteContactActionLabel="@string/invite_action_label"
   Il valore activityclass è il classname completo dell'attività che deve ricevere l'intent. Il valore invite_action_label è una stringa di testo visualizzata nel menu Aggiungi connessione nell'applicazione Contatti del dispositivo.

Nota: ContactsSource è un nome tag obsoleto per ContactsAccountType.

Riferimento contacts.xml

Il file contacts.xml contiene elementi XML che controllano l'interazione dell'adattatore e dell'applicazione di sincronizzazione con l'applicazione per i contatti e il provider di contatti. Questi elementi sono descritti nelle sezioni seguenti.

Elemento <ContactsAccountType>

L'elemento <ContactsAccountType> controlla l'interazione della tua applicazione con l'applicazione dei contatti. La sintassi è la seguente:

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

contenuto in:

res/xml/contacts.xml

può contenere:

<ContactsDataKind>

Descrizione:

Dichiara i componenti Android e le etichette UI che consentono agli utenti di invitare uno dei loro contatti su un social network, avvisare gli utenti quando uno dei loro stream di social network viene aggiornato e così via.

Tieni presente che il prefisso dell'attributo android: non è necessario per gli attributi di <ContactsAccountType>.

Attributi:

inviteContactActivity

Il nome completo della classe dell'attività nell'applicazione che vuoi attivare quando l'utente seleziona Aggiungi connessione dall'applicazione dei contatti del dispositivo.

inviteContactActionLabel

Una stringa di testo visualizzata per l'attività specificata in inviteContactActivity, nel menu Aggiungi connessione. Ad esempio, puoi utilizzare la stringa "Segui nella mia rete". Puoi utilizzare un identificatore di risorsa stringa per questa etichetta.

viewContactNotifyService

Il nome completo della classe di un servizio nell'applicazione che deve ricevere notifiche quando l'utente visualizza un contatto. Questa notifica viene inviata dall'applicazione dei contatti del dispositivo e consente all'applicazione di posticipare le operazioni che richiedono un uso intensivo dei dati fino a quando non sono necessarie. Ad esempio, l'applicazione può rispondere a questa notifica leggendo e visualizzando la foto ad alta risoluzione del contatto e gli elementi dello stream social più recenti. Questa funzionalità è descritta in maggiore dettaglio nella sezione Interazioni degli stream social.

viewGroupActivity

Il nome completo del corso di un'attività nell'applicazione che può visualizzare informazioni sul gruppo. Quando l'utente fa clic sull'etichetta del gruppo nell'applicazione dei contatti del dispositivo, viene visualizzata l'interfaccia utente per questa attività.

viewGroupActionLabel

L'etichetta visualizzata dall'applicazione Contatti per un controllo UI che consente all'utente di esaminare i gruppi nell'applicazione.

Per questo attributo è consentito un identificatore di risorsa stringa.

viewStreamItemActivity

Il nome completo della classe di un'attività nell'applicazione che l'applicazione di contatto del dispositivo avvia quando l'utente fa clic su un elemento dello stream per un contatto non elaborato.

viewStreamItemPhotoActivity

Il nome completo della classe di un'attività nell'applicazione che l'applicazione di contatto del dispositivo avvia quando l'utente fa clic su una foto nell'elemento dello stream per un contatto non elaborato.

Elemento <ContactsDataKind>

L'elemento <ContactsDataKind> controlla la visualizzazione delle righe di dati personalizzate della tua applicazione nell'interfaccia utente dell'applicazione per i contatti. La sintassi è la seguente:

<ContactsDataKind
        android:mimeType="MIMEtype"
        android:icon="icon_resources"
        android:summaryColumn="column_name"
        android:detailColumn="column_name">

contenuto in:

<ContactsAccountType>

Descrizione:

Utilizza questo elemento per fare in modo che l'applicazione per i contatti mostri i contenuti di una riga di dati personalizzata come parte dei dettagli di un contatto non elaborato. Ogni elemento secondario <ContactsDataKind> di <ContactsAccountType> rappresenta un tipo di riga di dati personalizzata che l'adattatore di sincronizzazione aggiunge alla tabella ContactsContract.Data. Aggiungi un elemento <ContactsDataKind> per ogni tipo MIME personalizzato utilizzato. Non è necessario aggiungere l'elemento se disponi di una riga di dati personalizzata per la quale non vuoi visualizzare dati.

Attributi:

android:mimeType

Il tipo MIME personalizzato che hai definito per uno dei tipi di righe di dati personalizzati nella tabella ContactsContract.Data. Ad esempio, il valore vnd.android.cursor.item/vnd.example.locationstatus potrebbe essere un tipo MIME personalizzato per una riga di dati che registra l'ultima posizione nota di un contatto.

android:icon

Una risorsa disegnabile di Android visualizzata accanto ai tuoi dati dall'applicazione dei contatti. Utilizzalo per indicare all'utente che i dati provengono dal tuo servizio.

android:summaryColumn

Il nome della colonna del primo dei due valori recuperati dalla riga di dati. Il valore viene visualizzato come prima riga della voce per questa riga di dati. La prima riga è destinata a essere utilizzata come riepilogo dei dati, ma è facoltativa. Vedi anche android:detailColumn.

android:detailColumn

Il nome della colonna per il secondo dei due valori recuperati dalla riga di dati. Il valore viene visualizzato come seconda riga della voce per questa riga di dati. Vedi anche android:summaryColumn.

Funzionalità aggiuntive del fornitore di contatti

Oltre alle funzionalità principali descritte nelle sezioni precedenti, il fornitore di contatti offre queste utili funzionalità per l'utilizzo dei dati dei contatti:

• Gruppi di contatti
• Funzionalità fotografiche

Gruppi di contatti

Il fornitore di contatti può facoltativamente etichettare le raccolte di contatti correlati con dati di gruppo. Se il server associato a un account utente vuole mantenere dei gruppi, l'adattatore di sincronizzazione per il tipo di account dell'account deve trasferire i dati dei gruppi tra il fornitore di contatti e il server. Quando gli utenti aggiungono un nuovo contatto al server e lo inseriscono in un nuovo gruppo, l'adattatore di sincronizzazione deve aggiungere il nuovo gruppo alla tabella ContactsContract.Groups. Il gruppo o i gruppi a cui appartiene un contatto non elaborato sono archiviati nella tabella ContactsContract.Data, utilizzando il tipo MIME ContactsContract.CommonDataKinds.GroupMembership.

Se stai progettando un adattatore di sincronizzazione che aggiungerà dati di contatto non elaborati dal server al provider di contatti e non utilizzi gruppi, devi comunicare al provider di rendere visibili i tuoi dati. Nel codice che viene eseguito quando un utente aggiunge un account al dispositivo, aggiorna la riga ContactsContract.Settings aggiunta dal fornitore di contatti per l'account. In questa riga, imposta il valore della colonna Settings.UNGROUPED_VISIBLE su 1. In questo caso, il fornitore di contatti renderà sempre visibili i dati dei tuoi contatti, anche se non utilizzi i gruppi.

Foto dei contatti

La tabella ContactsContract.Data archivia le foto come righe con tipo MIME Photo.CONTENT_ITEM_TYPE. La colonna CONTACT_ID della riga è collegata alla colonna _ID del contatto non elaborato a cui appartiene. La classe ContactsContract.Contacts.Photo definisce una sottotabella di ContactsContract.Contacts contenente le informazioni sulla foto della foto principale di un contatto, che è la foto principale del contatto non elaborato principale del contatto. Analogamente, la classe ContactsContract.RawContacts.DisplayPhoto definisce una sottotabella di ContactsContract.RawContacts contenente le informazioni sulla foto per la foto principale di un contatto non elaborato.

La documentazione di riferimento per ContactsContract.Contacts.Photo e ContactsContract.RawContacts.DisplayPhoto contiene esempi di recupero di informazioni sulle foto. Non esiste una classe di comodità per il recupero della miniatura principale per un contatto non elaborato, ma puoi inviare una query alla tabella ContactsContract.Data, selezionando _ID del contatto non elaborato, Photo.CONTENT_ITEM_TYPE e IS_PRIMARY per trovare la riga della foto principale del contatto non elaborato.

I dati degli stream social relativi a una persona possono anche includere foto. Questi dati vengono memorizzati nella tabella android.provider.ContactsContract.StreamItemPhotos, descritta più nel dettaglio nella sezione Foto degli stream social.