150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainpage.title=Contacts Provider 250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main@jd:body 350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<div id="qv-wrapper"> 450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<div id="qv"> 550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>Quickview</h2> 650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ul> 750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Android's repository of information about people.</li> 850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Syncs with the web. 1050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 1150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 1250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Integrates social stream data. 1350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 1450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ul> 1550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>In this document</h2> 1650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 1750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 1850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#InformationTypes">Contacts Provider Organization</a> 1950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 2050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 2150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#RawContactBasics">Raw contacts</a> 2250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 2350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 2450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#DataBasics">Data</a> 2550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 2650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 2750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#ContactBasics">Contacts</a> 2850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 2950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 3050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#Sources">Data From Sync Adapters</a> 3150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 3250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 3350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#Permissions">Required Permissions</a> 3450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 3550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 3650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#UserProfile">The User Profile</a> 3750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 3850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 3950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#ContactsProviderMetadata">Contacts Provider Metadata</a> 4050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 4150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 4250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#Access">Contacts Provider Access</a> 4350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 4450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 4550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 4650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#SyncAdapters">Contacts Provider Sync Adapters</a> 4750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 4850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 4950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#SocialStream">Social Stream Data</a> 5050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 5150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 5250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#AdditionalFeatures">Additional Contacts Provider Features</a> 5350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 5450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 5550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>Key classes</h2> 5650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 5750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.provider.ContactsContract.Contacts}</li> 5850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.provider.ContactsContract.RawContacts}</li> 5950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.provider.ContactsContract.Data}</li> 606d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov <li>android.provider.ContactsContract.StreamItems</li> 6150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 6250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>Related Samples</h2> 6350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 6450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 6550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}resources/samples/ContactManager/index.html"> 6650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Contact Manager 6750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </a> 6850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 6950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 7050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> 7150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sample Sync Adapter</a> 7250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 7350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 7450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>See Also</h2> 7550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 7650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 7750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 7850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Content Provider Basics 7950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </a> 8050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 8150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 8250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</div> 8350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</div> 8450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 8550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider is a powerful and flexible Android component that manages the 8650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main device's central repository of data about people. The Contacts Provider is the source of data 8750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main you see in the device's contacts application, and you can also access its data in your own 8850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main application and transfer data between the device and online services. The provider accommodates 8950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a wide range of data sources and tries to manage as much data as possible for each person, with 9050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the result that its organization is complex. Because of this, the provider's API includes an 9150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main extensive set of contract classes and interfaces that facilitate both data retrieval and 9250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main modification. 9350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 9450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 9550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This guide describes the following: 9650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 9750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 9850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 9950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The basic provider structure. 10050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 10150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 10250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main How to retrieve data from the provider. 10350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 10450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 10550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main How to modify data in the provider. 10650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 10750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 10850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main How to write a sync adapter for synchronizing data from your server to the 10950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Contacts Provider. 11050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 11150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 11250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 11350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This guide assumes that you know the basics of Android content providers. To learn more 11450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main about Android content providers, read the 11550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 11650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Content Provider Basics</a> guide. The 11750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Sample Sync Adapter</a> 11850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sample app is an example of using a sync adapter to transfer data between the Contacts 11950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Provider and a sample application hosted by Google Web Services. 12050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 12150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="InformationTypes">Contacts Provider Organization</h2> 12250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 12350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider is an Android content provider component. It maintains three types of 12450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main data about a person, each of which corresponds to a table offered by the provider, as 12550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main illustrated in figure 1: 12650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 12750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/providers/contacts_structure.png" alt="" 12850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main height="364" id="figure1" /> 12950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="img-caption"> 13050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Figure 1.</strong> Contacts Provider table structure. 13150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 13250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 13350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The three tables are commonly referred to by the names of their contract classes. The classes 13450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main define constants for content URIs, column names, and column values used by the tables: 13550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 13650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 13750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 13850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts} table 13950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 14050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 14150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Rows representing different people, based on aggregations of raw contact rows. 14250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 14350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 14450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} table 14550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 14650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 14750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Rows containing a summary of a person's data, specific to a user account and type. 14850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 14950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 15050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} table 15150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 15250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 15350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Rows containing the details for raw contact, such as email addresses or phone numbers. 15450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 15550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 15650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 15750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The other tables represented by contract classes in {@link android.provider.ContactsContract} 15850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main are auxiliary tables that the Contacts Provider uses to manage its operations or support 15950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main specific functions in the device's contacts or telephony applications. 16050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 16150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="RawContactBasics">Raw contacts</h2> 16250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 16350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A raw contact represents a person's data coming from a single account type and account 16450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main name. Because the Contacts Provider allows more than one online service as the source of 16550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main data for a person, the Contacts Provider allows multiple raw contacts for the same person. 16650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Multiple raw contacts also allow a user to combine a person's data from more than one account 16750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main from the same account type. 16850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 16950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 17050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Most of the data for a raw contact isn't stored in the 17150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} table. Instead, it's stored in one or more 17250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main rows in the {@link android.provider.ContactsContract.Data} table. Each data row has a column 17350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID Data.RAW_CONTACT_ID} that 17450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contains the {@link android.provider.BaseColumns#_ID RawContacts._ID} value of its 17550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main parent {@link android.provider.ContactsContract.RawContacts} row. 17650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 17750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="RawContactsColumns">Important raw contact columns</h3> 17850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 17950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The important columns in the {@link android.provider.ContactsContract.RawContacts} table are 18050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main listed in table 1. Please read the notes that follow after the table: 18150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 18250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="table-caption" id="table1"> 18350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Table 1.</strong> Important raw contact columns. 18450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 18550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<table> 18650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 18750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Column name</th> 18850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Use</th> 18950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Notes</th> 19050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 19150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 19250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 19350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_NAME} 19450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 19550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 19650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The account name for the account type that's the source of this raw contact. 19750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For example, the account name of a Google account is one of the device owner's Gmail 19850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main addresses. See the next entry for 19950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE} for more 20050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main information. 20150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 20250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 20350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The format of this name is specific to its account type. It is not 20450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main necessarily an email address. 20550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 20650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 20750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 20850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 20950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE} 21050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 21150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 21250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The account type that's the source of this raw contact. For example, the account 21350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main type of a Google account is <code>com.google</code>. Always qualify your account type 21450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main with a domain identifier for a domain you own or control. This will ensure that your 21550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account type is unique. 21650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 21750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 21850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main An account type that offers contacts data usually has an associated sync adapter that 21950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main synchronizes with the Contacts Provider. 22050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 22150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 22250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 22350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContactsColumns#DELETED} 22450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 22550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 22650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The "deleted" flag for a raw contact. 22750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 22850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 22950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This flag allows the Contacts Provider to maintain the row internally until sync 23050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main adapters are able to delete the row from their servers and then finally delete the row 23150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main from the repository. 23250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 23350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 23450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</table> 23550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h4>Notes</h4> 23650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 23750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The following are important notes about the 23850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} table: 23950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 24050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ul> 24150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 24250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A raw contact's name is not stored in its row in 24350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts}. Instead, it's stored in 24450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the {@link android.provider.ContactsContract.Data} table, in a 24550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} row. A raw contact 24650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main has only one row of this type in the {@link android.provider.ContactsContract.Data} table. 24750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 24850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 24950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Caution:</strong> To use your own account data in a raw contact row, it must 25050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main first be registered with the {@link android.accounts.AccountManager}. To do this, prompt 25150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main users to add the account type and their account name to the list of accounts. If you don't 25250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main do this, the Contacts Provider will automatically delete your raw contact row. 25350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 25450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For example, if you want your app to maintain contacts data for your web-based service 25550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main with the domain {@code com.example.dataservice}, and the user's account for your service 25650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main is {@code becky.sharp@dataservice.example.com}, the user must first add the account 25750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main "type" ({@code com.example.dataservice}) and account "name" 25850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ({@code becky.smart@dataservice.example.com}) before your app can add raw contact rows. 25950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main You can explain this requirement to the user in documentation, or you can prompt the 26050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main user to add the type and name, or both. Account types and account names 26150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main are described in more detail in the next section. 26250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 26350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ul> 26450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="RawContactsExample">Sources of raw contacts data</h3> 26550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 26650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To understand how raw contacts work, consider the user "Emily Dickinson" who has the following 26750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main three user accounts defined on her device: 26850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 26950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ul> 27050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><code>emily.dickinson@gmail.com</code></li> 27150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><code>emilyd@gmail.com</code></li> 27250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Twitter account "belle_of_amherst"</li> 27350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ul> 27450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 27550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This user has enabled <em>Sync Contacts</em> for all three of these accounts in the 27650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <em>Accounts</em> settings. 27750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 27850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 27950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Suppose Emily Dickinson opens a browser window, logs into Gmail as 28050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>emily.dickinson@gmail.com</code>, opens 28150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Contacts, and adds "Thomas Higginson". Later on, she logs into Gmail as 28250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>emilyd@gmail.com</code> and sends an email to "Thomas Higginson", which automatically 28350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main adds him as a contact. She also follows "colonel_tom" (Thomas Higginson's Twitter ID) on 28450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Twitter. 28550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 28650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 28750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider creates three raw contacts as a result of this work: 28850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 28950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 29050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 29150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A raw contact for "Thomas Higginson" associated with <code>emily.dickinson@gmail.com</code>. 29250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The user account type is Google. 29350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 29450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 29550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A second raw contact for "Thomas Higginson" associated with <code>emilyd@gmail.com</code>. 29650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The user account type is also Google. There is a second raw contact even 29750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main though the name is identical to a previous name, because the person was added for a 29850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main different user account. 29950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 30050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 30150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A third raw contact for "Thomas Higginson" associated with "belle_of_amherst". The user 30250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account type is Twitter. 30350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 30450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 30550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="DataBasics">Data</h2> 30650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 30750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main As noted previously, the data for a raw contact is stored in a 30850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} row that is linked to the raw contact's 30950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>_ID</code> value. This allows a single raw contact to have multiple instances of the same 31050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main type of data such as email addresses or phone numbers. For example, if 31150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main "Thomas Higginson" for {@code emilyd@gmail.com} (the raw contact row for Thomas Higginson 31250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main associated with the Google account <code>emilyd@gmail.com</code>) has a home email address of 31350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>thigg@gmail.com</code> and a work email address of 31450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>thomas.higginson@gmail.com</code>, the Contacts Provider stores the two email address 31550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main rows and links them both to the raw contact. 31650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 31750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 31850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Notice that different types of data are stored in this single table. Display name, 31950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main phone number, email, postal address, photo, and website detail rows are all found in the 32050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} table. To help manage this, the 32150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} table has some columns with descriptive names, 32250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main and others with generic names. The contents of a descriptive-name column have the same meaning 32350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main regardless of the type of data in the row, while the contents of a generic-name column have 32450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main different meanings depending on the type of data. 32550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 32650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="DescriptiveColumns">Descriptive column names</h3> 32750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 32850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Some examples of descriptive column names are: 32950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 33050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 33150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 33250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data#RAW_CONTACT_ID} 33350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 33450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 33550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The value of the <code>_ID</code> column of the raw contact for this data. 33650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 33750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 33850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data#MIMETYPE} 33950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 34050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 34150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The type of data stored in this row, expressed as a custom MIME type. The Contacts Provider 34250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main uses the MIME types defined in the subclasses of 34350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds}. These MIME types are open source, 34450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main and can be used by any application or sync adapter that works with the Contacts Provider. 34550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 34650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 34750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} 34850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 34950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 35050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If this type of data row can occur more than once for a raw contact, the 35150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} column flags 35250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the data row that contains the primary data for the type. For example, if 35350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the user long-presses a phone number for a contact and selects <strong>Set default</strong>, 35450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main then the {@link android.provider.ContactsContract.Data} row containing that number 35550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main has its {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} column set to a 35650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main non-zero value. 35750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 35850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 35950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="GenericColumns">Generic column names</h3> 36050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 36150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main There are 15 generic columns named <code>DATA1</code> through 36250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>DATA15</code> that are generally available and an additional four generic 36350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main columns <code>SYNC1</code> through <code>SYNC4</code> that should only be used by sync 36450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main adapters. The generic column name constants always work, regardless of the type of 36550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main data the row contains. 36650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 36750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 36850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The <code>DATA1</code> column is indexed. The Contacts Provider always uses this column for 36950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the data that the provider expects will be the most frequent target of a query. For example, 37050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main in an email row, this column contains the actual email address. 37150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 37250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 37350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main By convention, the column <code>DATA15</code> is reserved for storing Binary Large Object 37450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main (BLOB) data such as photo thumbnails. 37550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 37650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="TypeSpecificNames">Type-specific column names</h3> 37750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 37850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To facilitate working with the columns for a particular type of row, the Contacts Provider 37950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main also provides type-specific column name constants, defined in subclasses of 38050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds}. The constants simply give a 38150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main different constant name to the same column name, which helps you access data in a row of a 38250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main particular type. 38350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 38450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 38550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For example, the {@link android.provider.ContactsContract.CommonDataKinds.Email} class defines 38650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main type-specific column name constants for a {@link android.provider.ContactsContract.Data} row 38750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that has the MIME type 38850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE 38950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Email.CONTENT_ITEM_TYPE}. The class contains the constant 39050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} for the email address 39150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main column. The actual value of 39250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} is "data1", which is 39350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the same as the column's generic name. 39450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 39550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="caution"> 39650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Caution:</strong> Don't add your own custom data to the 39750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} table using a row that has one of the 39850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main provider's pre-defined MIME types. If you do, you may lose the data or cause the provider to 39950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main malfunction. For example, you should not add a row with the MIME type 40050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE 40150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Email.CONTENT_ITEM_TYPE} that contains a user name instead of an email address in the 40250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main column <code>DATA1</code>. If you use your own custom MIME type for the row, then you are free 40350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to define your own type-specific column names and use the columns however you wish. 40450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 40550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 40650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Figure 2 shows how descriptive columns and data columns appear in a 40750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} row, and how type-specific column names "overlay" 40850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the generic column names 40950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 41050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/providers/data_columns.png" 41150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main alt="How type-specific column names map to generic column names" 41250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main height="311" id="figure2" /> 41350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="img-caption"> 41450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Figure 2.</strong> Type-specific column names and generic column names. 41550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 41650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="ColumnMaps">Type-specific column name classes</h3> 41750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 41850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Table 2 lists the most commonly-used type-specific column name classes: 41950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 42050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="table-caption" id="table2"> 42150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Table 2.</strong> Type-specific column name classes</p> 42250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<table> 42350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 42450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Mapping class</th> 42550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Type of data</th> 42650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Notes</th> 42750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 42850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 42950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredName}</td> 43050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>The name data for the raw contact associated with this data row.</td> 43150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>A raw contact has only one of these rows.</td> 43250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 43350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 43450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.CommonDataKinds.Photo}</td> 43550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>The main photo for the raw contact associated with this data row.</td> 43650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>A raw contact has only one of these rows.</td> 43750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 43850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 43950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.CommonDataKinds.Email}</td> 44050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>An email address for the raw contact associated with this data row.</td> 44150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>A raw contact can have multiple email addresses.</td> 44250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 44350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 44450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal}</td> 44550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>A postal address for the raw contact associated with this data row.</td> 44650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>A raw contact can have multiple postal addresses.</td> 44750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 44850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 44950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.CommonDataKinds.GroupMembership}</td> 45050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>An identifier that links the raw contact to one of the groups in the Contacts Provider.</td> 45150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 45250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Groups are an optional feature of an account type and account name. They're described in 45350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main more detail in the section <a href="#Groups">Contact groups</a>. 45450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 45550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 45650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</table> 45750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="ContactBasics">Contacts</h3> 45850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 45950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider combines the raw contact rows across all account types and account names 46050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to form a <strong>contact</strong>. This facilitates displaying and modifying all the data a 46150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main user has collected for a person. The Contacts Provider manages the creation of new contact 46250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main rows, and the aggregation of raw contacts with an existing contact row. Neither applications nor 46350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sync adapters are allowed to add contacts, and some columns in a contact row are read-only. 46450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 46550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"> 46650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Note:</strong> If you try to add a contact to the Contacts Provider with an 46750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#insert(Uri,ContentValues) insert()}, you'll get 46850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main an {@link java.lang.UnsupportedOperationException} exception. If you try to update a column 46950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that's listed as "read-only," the update is ignored. 47050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 47150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 47250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider creates a new contact in response to the addition of a new raw contact 47350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that doesn't match any existing contacts. The provider also does this if an existing raw 47450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact's data changes in such a way that it no longer matches the contact to which it was 47550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main previously attached. If an application or sync adapter creates a new raw contact that 47650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <em>does</em> match an existing contact, the new raw contact is aggregated to the existing 47750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact. 47850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 47950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 48050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider links a contact row to its raw contact rows with the contact row's 48150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>_ID</code> column in the {@link android.provider.ContactsContract.Contacts Contacts} 48250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main table. The <code>CONTACT_ID</code> column of the raw contacts table 48350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} contains <code>_ID</code> values for 48450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the contacts row associated with each raw contacts row. 48550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 48650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 48750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The {@link android.provider.ContactsContract.Contacts} table also has the column 48850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} that is a 48950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main "permanent" link to the contact row. Because the Contacts Provider maintains contacts 49050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main automatically, it may change a contact row's {@link android.provider.BaseColumns#_ID} value 49150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main in response to an aggregation or sync. Even If this happens, the content URI 49250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} combined with 49350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact's {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} will still 49450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main point to the contact row, so you can use 49550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} 49650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to maintain links to "favorite" contacts, and so forth. This column has its own format that is 49750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main unrelated to the format of the {@link android.provider.BaseColumns#_ID} column. 49850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 49950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 50050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Figure 3 shows how the three main tables relate to each other. 50150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 50250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/providers/contacts_tables.png" alt="Contacts provider main tables" 50350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main height="514" id="figure4" /> 50450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="img-caption"> 50550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Figure 3.</strong> Contacts, Raw Contacts, and Details table relationships. 50650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 50750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="Sources">Data From Sync Adapters</h2> 50850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 50950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Users enter contacts data directly into the device, but data also flows into the Contacts 51050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Provider from web services via <strong>sync adapters</strong>, which automate 51150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the transfer of data between the device and services. Sync adapters run in the background 51250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main under the control of the system, and they call {@link android.content.ContentResolver} methods 51350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to manage data. 51450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 51550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 51650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In Android, the web service that a sync adapter works with is identified by an account type. 51750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Each sync adapter works with one account type, but it can support multiple account names for 51850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that type. Account types and account names are described briefly in the section 51950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#RawContactsExample">Sources of raw contacts data</a>. The following definitions offer 52050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main more detail, and describe how account type and name relate to sync adapters and services. 52150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 52250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 52350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 52450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Account type 52550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 52650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 52750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Identifies a service in which the user has stored data. Most of the time, the user has to 52850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main authenticate with the service. For example, Google Contacts is an account type, identified 52950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main by the code <code>google.com</code>. This value corresponds to the account type used by 53050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.accounts.AccountManager}. 53150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 53250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 53350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Account name 53450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 53550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 53650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Identifies a particular account or login for an account type. Google Contacts accounts 53750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main are the same as Google accounts, which have an email address as an account name. 53850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Other services may use a single-word username or numeric id. 53950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 54050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 54150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 54250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Account types don't have to be unique. A user can configure multiple Google Contacts accounts 54350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main and download their data to the Contacts Provider; this may happen if the user has one set of 54450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main personal contacts for a personal account name, and another set for work. Account names are 54550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main usually unique. Together, they identify a specific data flow between the Contacts Provider and 54650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main an external service. 54750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 54850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 54950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If you want to transfer your service's data to the Contacts Provider, you need to write your 55050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main own sync adapter. This is described in more detail in the section 55150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#SyncAdapters">Contacts Provider Sync Adapters</a>. 55250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 55350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 55450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Figure 4 shows how the Contacts Provider fits into the flow of data 55550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main about people. In the box marked "sync adapters," each adapter is labeled by its account type. 55650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 55750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/providers/ContactsDataFlow.png" alt="Flow of data about people" 55850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main height="252" id="figure5" /> 55950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="img-caption"> 56050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Figure 4.</strong> The Contacts Provider flow of data. 56150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 56250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="Permissions">Required Permissions</h2> 56350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 56450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Applications that want to access the Contacts Provider must request the following 56550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main permissions: 56650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 56750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 56850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>Read access to one or more tables</dt> 56950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 57050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.Manifest.permission#READ_CONTACTS}, specified in 57150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>AndroidManifest.xml</code> with the 57250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> 57350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <uses-permission></a></code> element as 57450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><uses-permission android:name="android.permission.READ_CONTACTS"></code>. 57550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 57650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>Write access to one or more tables</dt> 57750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 57850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.Manifest.permission#WRITE_CONTACTS}, specified in 57950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>AndroidManifest.xml</code> with the 58050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> 58150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <uses-permission></a></code> element as 58250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><uses-permission android:name="android.permission.WRITE_CONTACTS"></code>. 58350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 58450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 58550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 58650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main These permissions do not extend to the user profile data. The user profile and its 58750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main required permissions are discussed in the following section, 58850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#UserProfile">The User Profile</a>. 58950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 59050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 59150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Remember that the user's contacts data is personal and sensitive. Users are concerned about 59250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main their privacy, so they don't want applications collecting data about them or their contacts. 59350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If it's not obvious why you need permission to access their contacts data, they may give 59450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main your application low ratings or simply refuse to install it. 59550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 59650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="UserProfile">The User Profile</h2> 59750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 59850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The {@link android.provider.ContactsContract.Contacts} table has a single row containing 59950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main profile data for the device's user. This data describes the device's <code>user</code> rather 60050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main than one of the user's contacts. The profile contacts row is linked to a raw 60150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts row for each system that uses a profile. 60250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Each profile raw contact row can have multiple data rows. Constants for accessing the user 60350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main profile are available in the {@link android.provider.ContactsContract.Profile} class. 60450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 60550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 60650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Access to the user profile requires special permissions. In addition to the 60750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.Manifest.permission#READ_CONTACTS} and 60850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.Manifest.permission#WRITE_CONTACTS} permissions needed to read and write, access 6096d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov to the user profile requires the android.Manifest.permission#READ_PROFILE and 6106d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.Manifest.permission#WRITE_PROFILE permissions for read and write access, 61150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main respectively. 61250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 61350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 61450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Remember that you should consider a user's profile to be sensitive. The permission 6156d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.Manifest.permission#READ_PROFILE allows you to access the device user's 61650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main personally-identifying data. Make sure to tell the user why 61750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main you need user profile access permissions in the description of your application. 61850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 61950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 62050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To retrieve the contact row that contains the user's profile, 62150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main call {@link android.content.ContentResolver#query(Uri,String[], String, String[], String) 62250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentResolver.query()}. Set the content URI to 62350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Profile#CONTENT_URI} and don't provide any 62450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main selection criteria. You can also use this content URI as the base URI for retrieving raw 62550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts or data for the profile. For example, this snippet retrieves data for the profile: 62650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 62750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 62850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets the columns to retrieve for the user profile 62950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainmProjection = new String[] 63050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main { 63150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Profile._ID, 63250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Profile.DISPLAY_NAME_PRIMARY, 63350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Profile.LOOKUP_KEY, 63450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Profile.PHOTO_THUMBNAIL_URI 63550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main }; 63650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 63750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Retrieves the profile from the Contacts Provider 63850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainmProfileCursor = 63950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main getContentResolver().query( 64050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Profile.CONTENT_URI, 64150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mProjection , 64250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main null, 64350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main null, 64450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main null); 64550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 64650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"> 64750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Note:</strong> If you retrieve multiple contact rows, and you want to determine if one of them 64850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main is the user profile, test the row's 64950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.ContactsColumns#IS_USER_PROFILE} column. This column 65050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main is set to "1" if the contact is the user profile. 65150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 65250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="ContactsProviderMetadata">Contacts Provider Metadata</h2> 65350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 65450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider manages data that keeps track of the state of contacts data in the 65550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main repository. This metadata about the repository is stored in various places, including the 65650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Raw Contacts, Data, and Contacts table rows, the 65750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Settings} table, and the 65850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.SyncState} table. The following table shows the 65950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main effect of each of these pieces of metadata: 66050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 66150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="table-caption" id="table3"> 66250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Table 3.</strong> Metadata in the Contacts Provider</p> 66350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<table> 66450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 66550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Table</th> 66650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Column</th> 66750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Values</th> 66850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col">Meaning</th> 66950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 67050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 67150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2">{@link android.provider.ContactsContract.RawContacts}</td> 67250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2">{@link android.provider.ContactsContract.SyncColumns#DIRTY}</td> 67350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>"0" - not changed since the last sync.</td> 67450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2"> 67550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Marks raw contacts that were changed on the device and have to be synced back to the 67650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main server. The value is set automatically by the Contacts Provider when Android 67750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main applications update a row. 67850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 67950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sync adapters that modify the raw contact or data tables should always append the 68050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main string {@link android.provider.ContactsContract#CALLER_IS_SYNCADAPTER} to the 68150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main content URI they use. This prevents the provider from marking rows as dirty. 68250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Otherwise, sync adapter modifications appear to be local modifications and are 68350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sent to the server, even though the server was the source of the modification. 68450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 68550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 68650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 68750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 68850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>"1" - changed since last sync, needs to be synced back to the server.</td> 68950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 69050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 69150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.RawContacts}</td> 69250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.SyncColumns#VERSION}</td> 69350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>The version number of this row.</td> 69450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 69550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider automatically increments this value whenever the row or 69650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main its related data changes. 69750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 69850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 69950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 70050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.Data}</td> 70150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.DataColumns#DATA_VERSION}</td> 70250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>The version number of this row.</td> 70350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 70450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider automatically increments this value whenever the data row 70550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main is changed. 70650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 70750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 70850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 70950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.RawContacts}</td> 71050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}</td> 71150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 71250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A string value that uniquely identifies this raw contact to the account in 71350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which it was created. 71450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 71550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 71650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main When a sync adapter creates a new raw contact, this column should be set to the 71750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main server's unique ID for the raw contact. When an Android application creates a new 71850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main raw contact, the application should leave this column empty. This signals the sync 71950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main adapter that it should create a new raw contact on the server, and get a 72050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main value for the {@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}. 72150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 72250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In particular, the source id must be <strong>unique</strong> for each account 72350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main type and should be stable across syncs: 72450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 72550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 72650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 72750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Unique: Each raw contact for an account must have its own source id. If you 72850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main don't enforce this, you'll cause problems in the contacts application. 72950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Notice that two raw contacts for the same account <em>type</em> may have 73050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the same source id. For example, the raw contact "Thomas Higginson" for the 73150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account {@code emily.dickinson@gmail.com} is allowed to have the same source 73250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main id as the raw contact "Thomas Higginson" for the account 73350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@code emilyd@gmail.com}. 73450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 73550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 73650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Stable: Source ids are a permanent part of the online service's data for 73750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the raw contact. For example, if the user clears Contacts Storage from the 73850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Apps settings and re-syncs, the restored raw contacts should have the same 73950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main source ids as before. If you don't enforce this, shortcuts will stop 74050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main working. 74150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 74250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 74350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 74450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 74550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 74650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2">{@link android.provider.ContactsContract.Groups}</td> 74750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2">{@link android.provider.ContactsContract.GroupsColumns#GROUP_VISIBLE}</td> 74850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>"0" - Contacts in this group should not be visible in Android application UIs.</td> 74950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 75050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This column is for compatibility with servers that allow a user to hide contacts in 75150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main certain groups. 75250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 75350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 75450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 75550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>"1" - Contacts in this group are allowed to be visible in application UIs.</td> 75650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 75750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 75850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2">{@link android.provider.ContactsContract.Settings}</td> 75950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2"> 76050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE}</td> 76150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 76250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main "0" - For this account and account type, contacts that don't belong to a group are 76350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main invisible to Android application UIs. 76450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 76550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td rowspan="2"> 76650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main By default, contacts are invisible if none of their raw contacts belongs to a group 76750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main (Group membership for a raw contact is indicated by one or more 76850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership} rows 76950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main in the {@link android.provider.ContactsContract.Data} table). 77050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main By setting this flag in the {@link android.provider.ContactsContract.Settings} table row 77150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main for an account type and account, you can force contacts without groups to be visible. 77250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main One use of this flag is to show contacts from servers that don't use groups. 77350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 77450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 77550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 77650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 77750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main "1" - For this account and account type, contacts that don't belong to a group are 77850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main visible to application UIs. 77950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 78050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 78150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 78250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 78350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.SyncState}</td> 78450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>(all)</td> 78550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 78650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Use this table to store metadata for your sync adapter. 78750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 78850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 78950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main With this table you can store sync state and other sync-related data persistently on 79050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the device. 79150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 79250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 79350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</table> 79450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="Access">Contacts Provider Access</h2> 79550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 79650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This section describes guidelines for accessing data from the Contacts Provider, focusing on 79750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the following: 79850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 79950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ul> 80050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 80150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Entity queries. 80250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 80350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 80450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Batch modification. 80550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 80650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 80750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Retrieval and modification with intents. 80850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 80950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 81050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Data integrity. 81150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 81250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ul> 81350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 81450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Making modifications from a sync adapter is also covered in more detail in the section 81550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#SyncAdapters">Contacts Provider Sync Adapters</a>. 81650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 81750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="Entities">Querying entities</h3> 81850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 81950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Because the Contacts Provider tables are organized in a hierarchy, it's often useful to 82050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main retrieve a row and all of the "child" rows that are linked to it. For example, to display 82150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main all the information for a person, you may want to retrieve all the 82250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} rows for a single 82350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts} row, or all the 82450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.Email} rows for a single 82550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} row. To facilitate this, the Contacts 82650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Provider offers <strong>entity</strong> constructs, which act like database joins between 82750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main tables. 82850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 82950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 83050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main An entity is like a table composed of selected columns from a parent table and its child table. 83150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main When you query an entity, you supply a projection and search criteria based on the columns 83250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main available from the entity. The result is a {@link android.database.Cursor} that contains 83350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contains one row for each child table row that was retrieved. For example, if you query 83450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts.Entity} for a contact name 83550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main and all the {@link android.provider.ContactsContract.CommonDataKinds.Email} rows for all the 83650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main raw contacts for that name, you get back a {@link android.database.Cursor} containing one row 83750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main for each {@link android.provider.ContactsContract.CommonDataKinds.Email} row. 83850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 83950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 84050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Entities simplify queries. Using an entity, you can retrieve all of the contacts data for a 84150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact or raw contact at once, instead of having to query the parent table first to get an 84250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ID, and then having to query the child table with that ID. Also, the Contacts Provider processes 84350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a query against an entity in a single transaction, which ensures that the retrieved data is 84450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main internally consistent. 84550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 84650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"> 84750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Note:</strong> An entity usually doesn't contain all the columns of the parent and 84850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main child table. If you attempt to work with a column name that isn't in the list of column name 84950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main constants for the entity, you'll get an {@link java.lang.Exception}. 85050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 85150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 85250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The following snippet shows how to retrieve all the raw contact rows for a contact. The snippet 85350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main is part of a larger application that has two activities, "main" and "detail". The main activity 85450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main shows a list of contact rows; when the user select one, the activity sends its ID to the detail 85550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main activity. The detail activity uses the {@link android.provider.ContactsContract.Contacts.Entity} 85650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to display all of the data rows from all of the raw contacts associated with the selected 85750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact. 85850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 85950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 86050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This snippet is taken from the "detail" activity: 86150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 86250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 86350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main... 86450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 86550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Appends the entity path to the URI. In the case of the Contacts Provider, the 86650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * expected URI is content://com.google.contacts/#/entity (# is the ID value). 86750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 86850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mContactUri = Uri.withAppendedPath( 86950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mContactUri, 87050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.Contacts.Entity.CONTENT_DIRECTORY); 87150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 87250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Initializes the loader identified by LOADER_ID. 87350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main getLoaderManager().initLoader( 87450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main LOADER_ID, // The identifier of the loader to initialize 87550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main null, // Arguments for the loader (in this case, none) 87650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main this); // The context of the activity 87750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 87850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Creates a new cursor adapter to attach to the list view 87950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mCursorAdapter = new SimpleCursorAdapter( 88050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main this, // the context of the activity 88150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main R.layout.detail_list_item, // the view item containing the detail widgets 88250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mCursor, // the backing cursor 88350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mFromColumns, // the columns in the cursor that provide the data 88450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mToViews, // the views in the view item that display the data 88550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 0); // flags 88650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 88750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Sets the ListView's backing adapter. 88850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mRawContactList.setAdapter(mCursorAdapter); 88950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main... 89050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main@Override 89150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainpublic Loader<Cursor> onCreateLoader(int id, Bundle args) { 89250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 89350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 89450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Sets the columns to retrieve. 89550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. 89650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * DATA1 contains the first column in the data row (usually the most important one). 89750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * MIMETYPE indicates the type of data in the data row. 89850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 89950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main String[] projection = 90050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main { 90150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.Contacts.Entity.RAW_CONTACT_ID, 90250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.Contacts.Entity.DATA1, 90350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.Contacts.Entity.MIMETYPE 90450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main }; 90550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 90650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 90750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw 90850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * contact collated together. 90950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 91050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main String sortOrder = 91150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.Contacts.Entity.RAW_CONTACT_ID + 91250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main " ASC"; 91350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 91450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 91550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Returns a new CursorLoader. The arguments are similar to 91650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * ContentResolver.query(), except for the Context argument, which supplies the location of 91750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * the ContentResolver to use. 91850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 91950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main return new CursorLoader( 92050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main getApplicationContext(), // The activity's context 92150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mContactUri, // The entity content URI for a single contact 92250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main projection, // The columns to retrieve 92350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main null, // Retrieve all the raw contacts and their data rows. 92450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main null, // 92550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sortOrder); // Sort by the raw contact ID. 92650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main} 92750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 92850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 92950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main When the load is finished, {@link android.app.LoaderManager} invokes a callback to 93050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished(Loader, D) 93150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main onLoadFinished()}. One of the incoming arguments to this method is a 93250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.database.Cursor} with the results of the query. In your own app, you can get the 93350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main data from this {@link android.database.Cursor} to display it or work with it further. 93450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 93550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="Transactions">Batch modification</h3> 93650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 93750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Whenever possible, you should insert, update, and delete data in the Contacts Provider in 93850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main "batch mode", by creating an {@link java.util.ArrayList} of 93950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation} objects and calling 94050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Because 94150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the Contacts Provider performs all of the operations in an 94250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} in a single 94350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main transaction, your modifications will never leave the contacts repository in an inconsistent 94450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main state. A batch modification also facilitates inserting a raw contact and its detail data at 94550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the same time. 94650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 94750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"> 94850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Note:</strong> To modify a <em>single</em> raw contact, consider sending an intent to 94950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the device's contacts application rather than handling the modification in your app. 95050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Doing this is described in more detail in the section 95150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#Intents">Retrieval and modification with intents</a>. 95250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 95350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h4>Yield points</h4> 95450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 95550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A batch modification containing a large number of operations can block other processes, 95650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main resulting in a bad overall user experience. To organize all the modifications you want to 95750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main perform in as few separate lists as possible, and at the same time prevent them from 95850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main blocking the system, you should set <strong>yield points</strong> for one or more operations. 95950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A yield point is a {@link android.content.ContentProviderOperation} object that has its 96050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation#isYieldAllowed()} value set to 96150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>true</code>. When the Contacts Provider encounters a yield point, it pauses its work to 96250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main let other processes run and closes the current transaction. When the provider starts again, it 96350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main continues with the next operation in the {@link java.util.ArrayList} and starts a new 96450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main transaction. 96550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 96650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 96750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Yield points do result in more than one transaction per call to 96850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Because of 96950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main this, you should set a yield point for the last operation for a set of related rows. 97050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For example, you should set a yield point for the last operation in a set that adds a 97150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main raw contact rows and its associated data rows, or the last operation for a set of rows related 97250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to a single contact. 97350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 97450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 97550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Yield points are also a unit of atomic operation. All accesses between two yield points will 97650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main either succeed or fail as a single unit. If you don't set any yield points, the smallest 97750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main atomic operation is the entire batch of operations. If you do use yield points, you prevent 97850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main operations from degrading system performance, while at the same time ensuring that a subset of 97950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main operations is atomic. 98050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 98150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h4>Modification back references</h4> 98250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 98350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main When you're inserting a new raw contact row and its associated data rows as a set of 98450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation} objects, you have to link the data rows to 98550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the raw contact row by inserting the raw contact's 98650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.BaseColumns#_ID} value as the 98750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID} value. However, this 98850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main value isn't available when you're creating the {@link android.content.ContentProviderOperation} 98950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main for the data row, because you haven't yet applied the 99050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation} for the raw contact row. To work around this, 99150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the {@link android.content.ContentProviderOperation.Builder} class has the method 99250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()}. 99350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This method allows you to insert or modify a column with the 99450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main result of a previous operation. 99550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 99650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 99750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} 99850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main method has two arguments: 99950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 100050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dl> 100150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 100250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>key</code> 100350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 100450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 100550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The key of a key-value pair. The value of this argument should be the name of a column 100650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main in the table that you're modifying. 100750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 100850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 100950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>previousResult</code> 101050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 101150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 101250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The 0-based index of a value in the array of 101350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderResult} objects from 101450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. As 101550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the batch operations are applied, the result of each operation is stored in an 101650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main intermediate array of results. The <code>previousResult</code> value is the index 101750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of one of these results, which is retrieved and stored with the <code>key</code> 101850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main value. This allows you to insert a new raw contact record and get back its 101950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.BaseColumns#_ID} value, then make a "back reference" to the 102050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main value when you add a {@link android.provider.ContactsContract.Data} row. 102150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 102250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The entire result array is created when you first call 102350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}, 102450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main with a size equal to the size of the {@link java.util.ArrayList} of 102550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation} objects you provide. However, all 102650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the elements in the result array are set to <code>null</code>, and if you try 102750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to do a back reference to a result for an operation that hasn't yet been applied, 102850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} 102950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main throws an {@link java.lang.Exception}. 103050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 103150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 103250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 103350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dl> 103450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 103550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The following snippets show how to insert a new raw contact and data in batch. They 103650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main includes code that establishes a yield point and uses a back reference. The snippets are an 103750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main expanded version of the <code>createContacEntry()</code> method, which is part of the 103850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>ContactAdder</code> class in the 103950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><a href="{@docRoot}resources/samples/ContactManager/index.html"> 104050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Contact Manager</a></code> sample application. 104150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 104250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 104350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The first snippet retrieves contact data from the UI. At this point, the user has already 104450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main selected the account for which the new raw contact should be added. 104550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 104650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 104750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Creates a contact entry from the current UI values, using the currently-selected account. 104850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainprotected void createContactEntry() { 104950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 105050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Gets values from the UI 105150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 105250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main String name = mContactNameEditText.getText().toString(); 105350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main String phone = mContactPhoneEditText.getText().toString(); 105450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main String email = mContactEmailEditText.getText().toString(); 105550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 105650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main int phoneType = mContactPhoneTypes.get( 105750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mContactPhoneTypeSpinner.getSelectedItemPosition()); 105850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 105950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main int emailType = mContactEmailTypes.get( 106050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mContactEmailTypeSpinner.getSelectedItemPosition()); 106150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 106250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 106350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The next snippet creates an operation to insert the raw contact row into the 106450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} table: 106550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 106650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 106750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 106850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Prepares the batch operation for inserting a new raw contact and its data. Even if 106950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * the Contacts Provider does not have any data for this person, you can't add a Contact, 107050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * only a raw contact. The Contacts Provider will then add a Contact automatically. 107150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 107250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 107350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Creates a new array of ContentProviderOperation objects. 107450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ArrayList<ContentProviderOperation> ops = 107550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main new ArrayList<ContentProviderOperation>(); 107650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 107750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 107850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Creates a new raw contact with its account type (server type) and account name 107950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * (user's account). Remember that the display name is not stored in this row, but in a 108050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * StructuredName data row. No other data is required. 108150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 108250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentProviderOperation.Builder op = 108350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) 108450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()) 108550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); 108650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 108750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Builds the operation and adds it to the array of operations 108850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ops.add(op.build()); 108950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 109050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 109150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Next, the code creates data rows for the display name, phone, and email rows. 109250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 109350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 109450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Each operation builder object uses 109550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} 109650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to get the 109750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID}. The reference points 109850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main back to the {@link android.content.ContentProviderResult} object from the first operation, 109950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which adds the raw contact row and returns its new {@link android.provider.BaseColumns#_ID} 110050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main value. As a result, each data row is automatically linked by its 110150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID} 110250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to the new {@link android.provider.ContactsContract.RawContacts} row to which it belongs. 110350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 110450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 110550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The {@link android.content.ContentProviderOperation.Builder} object that adds the email row is 110650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main flagged with {@link android.content.ContentProviderOperation.Builder#withYieldAllowed(boolean) 110750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main withYieldAllowed()}, which sets a yield point: 110850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 110950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 111050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Creates the display name for the new raw contact, as a StructuredName data row. 111150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main op = 111250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) 111350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 111450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * withValueBackReference sets the value of the first argument to the value of 111550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * the ContentProviderResult indexed by the second argument. In this particular 111650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * call, the raw contact ID column of the StructuredName data row is set to the 111750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * value of the result returned by the first operation, which is the one that 111850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * actually adds the raw contact row. 111950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 112050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) 112150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 112250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Sets the data row's MIME type to StructuredName 112350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.Data.MIMETYPE, 112450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) 112550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 112650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Sets the data row's display name to the name in the UI. 112750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name); 112850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 112950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Builds the operation and adds it to the array of operations 113050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ops.add(op.build()); 113150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 113250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Inserts the specified phone number and type as a Phone data row 113350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main op = 113450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) 113550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 113650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Sets the value of the raw contact id column to the new raw contact ID returned 113750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * by the first operation in the batch. 113850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 113950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) 114050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 114150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Sets the data row's MIME type to Phone 114250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.Data.MIMETYPE, 114350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) 114450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 114550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Sets the phone number and type 114650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) 114750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType); 114850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 114950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Builds the operation and adds it to the array of operations 115050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ops.add(op.build()); 115150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 115250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Inserts the specified email and type as a Phone data row 115350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main op = 115450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) 115550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 115650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Sets the value of the raw contact id column to the new raw contact ID returned 115750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * by the first operation in the batch. 115850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 115950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) 116050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 116150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Sets the data row's MIME type to Email 116250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.Data.MIMETYPE, 116350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) 116450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 116550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Sets the email address and type 116650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) 116750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType); 116850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 116950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 117050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Demonstrates a yield point. At the end of this insert, the batch operation's thread 117150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * will yield priority to other threads. Use after every set of operations that affect a 117250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * single contact, to avoid degrading performance. 117350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 117450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main op.withYieldAllowed(true); 117550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 117650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Builds the operation and adds it to the array of operations 117750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ops.add(op.build()); 117850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 117950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 118050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The last snippet shows the call to 118150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} that 118250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main inserts the new raw contact and data rows. 118350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 118450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 118550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Ask the Contacts Provider to create a new contact 118650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Log.d(TAG,"Selected account: " + mSelectedAccount.getName() + " (" + 118750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mSelectedAccount.getType() + ")"); 118850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Log.d(TAG,"Creating contact: " + name); 118950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 119050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main /* 119150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Applies the array of ContentProviderOperation objects in batch. The results are 119250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * discarded. 119350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 119450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main try { 119550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 119650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); 119750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main } catch (Exception e) { 119850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 119950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Display a warning 120050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Context ctx = getApplicationContext(); 120150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 120250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main CharSequence txt = getString(R.string.contactCreationFailure); 120350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main int duration = Toast.LENGTH_SHORT; 120450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Toast toast = Toast.makeText(ctx, txt, duration); 120550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main toast.show(); 120650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 120750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Log exception 120850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Log.e(TAG, "Exception encountered while inserting contact: " + e); 120950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main } 121050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main} 121150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 121250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 121350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Batch operations also allow you to implement <strong>optimistic concurrency control</strong>, 121450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a method of applying modification transactions without having to lock the underlying repository. 121550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To use this method, you apply the transaction and then check for other modifications that 121650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main may have been made at the same time. If you find an inconsistent modification has occurred, you 121750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main roll back your transaction and retry it. 121850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 121950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 122050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Optimistic concurrency control is useful for a mobile device, where there's only one user at 122150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a time, and simultaneous accesses to a data repository are rare. Because locking isn't used, 122250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main no time is wasted on setting locks or waiting for other transactions to release their locks. 122350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 122450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 122550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To use optimistic concurrency control while updating a single 122650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} row, follow these steps: 122750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 122850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 122950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 123050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Retrieve the raw contact's {@link android.provider.ContactsContract.SyncColumns#VERSION} 123150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main column along with the other data you retrieve. 123250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 123350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 123450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Create a {@link android.content.ContentProviderOperation.Builder} object suitable for 123550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main enforcing a constraint, using the method 123650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation#newAssertQuery(Uri)}. For the content URI, 123750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main use {@link android.provider.ContactsContract.RawContacts#CONTENT_URI 123850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main RawContacts.CONTENT_URI} 123950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main with the raw contact's {@link android.provider.BaseColumns#_ID} appended to it. 124050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 124150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 124250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For the {@link android.content.ContentProviderOperation.Builder} object, call 124350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation.Builder#withValue(String, Object) 124450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main withValue()} to compare the {@link android.provider.ContactsContract.SyncColumns#VERSION} 124550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main column to the version number you just retrieved. 124650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 124750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 124850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For the same {@link android.content.ContentProviderOperation.Builder}, call 124950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation.Builder#withExpectedCount(int) 125050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main withExpectedCount()} to ensure that only one row is tested by this assertion. 125150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 125250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 125350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Call {@link android.content.ContentProviderOperation.Builder#build()} to create the 125450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation} object, then add this object as the 125550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main first object in the {@link java.util.ArrayList} that you pass to 125650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. 125750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 125850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 125950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Apply the batch transaction. 126050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 126150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 126250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 126350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If the raw contact row is updated by another operation between the time you read the row and 126450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the time you attempt to modify it, the "assert" {@link android.content.ContentProviderOperation} 126550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main will fail, and the entire batch of operations will be backed out. You can then choose to retry 126650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the batch or take some other action. 126750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 126850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 126950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The following snippet demonstrates how to create an "assert" 127050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentProviderOperation} after querying for a single raw contact using 127150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a {@link android.content.CursorLoader}: 127250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 127350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 127450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main/* 127550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * The application uses CursorLoader to query the raw contacts table. The system calls this method 127650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * when the load is finished. 127750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 127850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainpublic void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { 127950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 128050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Gets the raw contact's _ID and VERSION values 128150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mRawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)); 128250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)); 128350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main} 128450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 128550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main... 128650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 128750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets up a Uri for the assert operation 128850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainUri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, mRawContactID); 128950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 129050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Creates a builder for the assert operation 129150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainContentProviderOperation.Builder assertOp = ContentProviderOperation.netAssertQuery(rawContactUri); 129250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 129350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Adds the assertions to the assert operation: checks the version and count of rows tested 129450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainassertOp.withValue(SyncColumns.VERSION, mVersion); 129550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainassertOp.withExpectedCount(1); 129650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 129750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Creates an ArrayList to hold the ContentProviderOperation objects 129850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainArrayList ops = new ArrayList<ContentProviderOperationg>; 129950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 130050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainops.add(assertOp.build()); 130150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 130250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// You would add the rest of your batch operations to "ops" here 130350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 130450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main... 130550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 130650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Applies the batch. If the assert fails, an Exception is thrown 130750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maintry 130850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main { 130950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentProviderResult[] results = 131050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main getContentResolver().applyBatch(AUTHORITY, ops); 131150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 131250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main } catch (OperationApplicationException e) { 131350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 131450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Actions you want to take if the assert operation fails go here 131550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main } 131650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 131750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="Intents">Retrieval and modification with intents</h3> 131850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 131950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sending an intent to the device's contacts application allows you to access the Contacts 132050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Provider indirectly. The intent starts the device's contacts application UI, in which users can 132150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main do contacts-related work. With this type of access, users can: 132250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 132350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Pick a contact from a list and have it returned to your app for further work.</li> 132450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Edit an existing contact's data.</li> 132550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Insert a new raw contact for any of their accounts.</li> 132650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Delete a contact or contacts data.</li> 132750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 132850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 132950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If the user is inserting or updating data, you can collect the data first and send it as 133050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main part of the intent. 133150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 133250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 133350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main When you use intents to access the Contacts Provider via the device's contacts application, you 133450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main don't have to write your own UI or code for accessing the provider. You also don't have to 133550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main request permission to read or write to the provider. The device's contacts application can 133650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main delegate read permission for a contact to you, and because you're making modifications to the 133750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main provider through another application, you don't have to have write permissions. 133850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 133950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 134050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The general process of sending an intent to access a provider is described in detail in the 134150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 134250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Content Provider Basics</a> guide in the section "Data access via intents." The action, 134350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main MIME type, and data values you use for the available tasks are summarized in Table 4, while the 134450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main extras values you can use with 134550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.Intent#putExtra(String, String) putExtra()} are listed in the 134650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main reference documentation for {@link android.provider.ContactsContract.Intents.Insert}: 134750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 134850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="table-caption" id="table4"> 134950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Table 4.</strong> Contacts Provider Intents. 135050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 135150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<table style="width:75%"> 135250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 135350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col" style="width:10%">Task</th> 135450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col" style="width:5%">Action</th> 135550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col" style="width:10%">Data</th> 135650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col" style="width:10%">MIME type</th> 135750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <th scope="col" style="width:25%">Notes</th> 135850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 135950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 136050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td><strong>Pick a contact from a list</strong></td> 136150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.content.Intent#ACTION_PICK}</td> 136250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 136350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main One of: 136450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 136550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 136650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.provider.ContactsContract.Contacts#CONTENT_URI Contacts.CONTENT_URI}, 136750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which displays a list of contacts. 136850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 136950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 137050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_URI Phone.CONTENT_URI}, 137150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which displays a list of phone numbers for a raw contact. 137250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 137350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 137450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal#CONTENT_URI 137550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainStructuredPostal.CONTENT_URI}, 137650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which displays a list of postal addresses for a raw contact. 137750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 137850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 137950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_URI Email.CONTENT_URI}, 138050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which displays a list of email addresses for a raw contact. 138150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 138250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 138350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 138450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 138550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Not used 138650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 138750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 138850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Displays a list of raw contacts or a list of data from a raw contact, depending on the 138950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main content URI type you supply. 139050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 139150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Call 139250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, 139350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which returns the content URI of the selected row. The form of the URI is the 139450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main table's content URI with the row's <code>LOOKUP_ID</code> appended to it. 139550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The device's contacts app delegates read and write permissions to this content URI 139650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main for the life of your activity. See the 139750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 139850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Content Provider Basics</a> guide for more details. 139950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 140050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 140150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 140250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 140350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td><strong>Insert a new raw contact</strong></td> 140450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.provider.ContactsContract.Intents.Insert#ACTION Insert.ACTION}</td> 140550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>N/A</td> 140650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 140750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts#CONTENT_TYPE 140850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main RawContacts.CONTENT_TYPE}, MIME type for a set of raw contacts. 140950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 141050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 141150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Displays the device's contacts application's <strong>Add Contact</strong> screen. The 141250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main extras values you add to the intent are displayed. If sent with 141350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, 141450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the content URI of the newly-added raw contact is passed back to your activity's 141550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.Activity#onActivityResult(int, int, Intent) onActivityResult()} 141650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main callback method in the {@link android.content.Intent} argument, in the 141750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main "data" field. To get the value, call {@link android.content.Intent#getData()}. 141850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 141950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 142050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 142150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td><strong>Edit a contact</strong></td> 142250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.content.Intent#ACTION_EDIT}</td> 142350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 142450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} for 142550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the contact. The editor activity will allow the user to edit any of the data associated 142650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main with this contact. 142750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 142850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 142950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE 143050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Contacts.CONTENT_ITEM_TYPE}, a single contact.</td> 143150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 143250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Displays the Edit Contact screen in the contacts application. The extras values you add 143350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to the intent are displayed. When the user clicks <strong>Done</strong> to save the 143450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main edits, your activity returns to the foreground. 143550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 143650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 143750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <tr> 143850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td><strong>Display a picker that can also add data.</strong></td> 143950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td>{@link android.content.Intent#ACTION_INSERT_OR_EDIT}</td> 144050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 144150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main N/A 144250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 144350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 144450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE} 144550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 144650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <td> 144750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This intent always displays the contacts app's picker screen. The user can either 144850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main pick a contact to edit, or add a new contact. Either the edit or the add screen 144950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main appears, depending on the user's choice, and the extras data you pass in the intent 145050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main is displayed. If your app displays contact data such as an email or phone number, use 145150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main this intent to allow the user to add the data to an existing contact. 145250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact, 145350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p class="note"> 145450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Note:</strong> There's no need to send a name value in this intent's extras, 145550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main because the user always picks an existing name or adds a new one. Moreover, 145650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main if you send a name, and the user chooses to do an edit, the contacts app will 145750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main display the name you send, overwriting the previous value. If the user doesn't 145850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main notice this and saves the edit, the old value is lost. 145950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 146050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </td> 146150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </tr> 146250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</table> 146350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 146450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The device's contacts app doesn't allow you to delete a raw contact or any of its data with an 146550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main intent. Instead, to delete a raw contact, use 146650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#delete(Uri, String, String[]) ContentResolver.delete()} 146750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main or {@link android.content.ContentProviderOperation#newDelete(Uri) 146850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContentProviderOperation.newDelete()}. 146950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 147050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 147150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The following snippet shows how to construct and send an intent that inserts a new raw 147250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact and data: 147350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 147450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 147550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Gets values from the UI 147650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainString name = mContactNameEditText.getText().toString(); 147750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainString phone = mContactPhoneEditText.getText().toString(); 147850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainString email = mContactEmailEditText.getText().toString(); 147950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 148050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainString company = mCompanyName.getText().toString(); 148150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainString jobtitle = mJobTitle.getText().toString(); 148250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 148350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Creates a new intent for sending to the device's contacts application 148450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainIntent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION); 148550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 148650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets the MIME type to the one expected by the insertion activity 148750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaininsertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE); 148850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 148950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets the new contact name 149050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaininsertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name); 149150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 149250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets the new company and job title 149350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaininsertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company); 149450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaininsertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle); 149550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 149650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main/* 149750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Demonstrates adding data rows as an array list associated with the DATA key 149850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 149950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 150050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Defines an array list to contain the ContentValues objects for each row 150150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainArrayList<ContentValues> contactData = new ArrayList<ContentValues>(); 150250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 150350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 150450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main/* 150550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Defines the raw contact row 150650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 150750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 150850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets up the row as a ContentValues object 150950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainContentValues rawContactRow = new ContentValues(); 151050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 151150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Adds the account type and name to the row 151250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainrawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()); 151350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainrawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); 151450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 151550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Adds the row to the array 151650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaincontactData.add(rawContactRow); 151750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 151850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main/* 151950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Sets up the phone number data row 152050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 152150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 152250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets up the row as a ContentValues object 152350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainContentValues phoneRow = new ContentValues(); 152450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 152550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Specifies the MIME type for this data row (all data rows must be marked by their type) 152650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainphoneRow.put( 152750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.Data.MIMETYPE, 152850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE 152950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main); 153050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 153150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Adds the phone number and its type to the row 153250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainphoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone); 153350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 153450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Adds the row to the array 153550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaincontactData.add(phoneRow); 153650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 153750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main/* 153850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Sets up the email data row 153950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 154050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 154150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Sets up the row as a ContentValues object 154250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainContentValues emailRow = new ContentValues(); 154350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 154450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Specifies the MIME type for this data row (all data rows must be marked by their type) 154550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainemailRow.put( 154650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.Data.MIMETYPE, 154750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE 154850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main); 154950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 155050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Adds the email address and its type to the row 155150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainemailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email); 155250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 155350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Adds the row to the array 155450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaincontactData.add(emailRow); 155550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 155650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main/* 155750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Adds the array to the intent's extras. It must be a parcelable object in order to 155850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * travel between processes. The device's contacts app expects its key to be 155950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main * Intents.Insert.DATA 156050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main */ 156150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MaininsertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData); 156250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 156350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Send out the intent to start the device's contacts app in its add contact activity. 156450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainstartActivity(insertIntent); 156550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 156650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="DataIntegrity">Data integrity</h3> 156750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 156850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Because the contacts repository contains important and sensitive data that users expect to be 156950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main correct and up-to-date, the Contacts Provider has well-defined rules for data integrity. It's 157050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main your responsibility to conform to these rules when you modify contacts data. The important 157150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main rules are listed here: 157250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 157350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 157450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 157550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Always add a {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} row 157650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main for every {@link android.provider.ContactsContract.RawContacts} row you add. 157750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 157850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 157950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A {@link android.provider.ContactsContract.RawContacts} row without a 158050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} row in the 158150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} table may cause problems during 158250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main aggregation. 158350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 158450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 158550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Always link new {@link android.provider.ContactsContract.Data} rows to their parent 158650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} row. 158750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 158850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 158950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A {@link android.provider.ContactsContract.Data} row that isn't linked to a 159050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts} won't be visible in the device's 159150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts application, and it might cause problems with sync adapters. 159250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 159350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 159450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Change data only for those raw contacts that you own. 159550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 159650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 159750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Remember that the Contacts Provider is usually managing data from several different 159850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account types/online services. You need to ensure that your application only modifies 159950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main or deletes data for rows that belong to you, and that it only inserts data with an 160050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account type and name that you control. 160150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 160250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 160350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Always use the constants defined in {@link android.provider.ContactsContract} and its 160450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main subclasses for authorities, content URIs, URI paths, column names, MIME types, and 160550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.CommonColumns#TYPE} values. 160650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 160750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 160850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Using these constants helps you to avoid errors. You'll also be notified with compiler 160950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main warnings if any of the constants is deprecated. 161050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 161150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 161250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="CustomData">Custom data rows</h3> 161350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 161450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main By creating and using your own custom MIME types, you can insert, edit, delete, and retrieve 161550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main your own data rows in the {@link android.provider.ContactsContract.Data} table. Your rows 161650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main are limited to using the column defined in 161750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DataColumns}, although you can map your own 161850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main type-specific column names to the default column names. In the device's contacts application, 161950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the data for your rows is displayed but can't be edited or deleted, and users can't add 162050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main additional data. To allow users to modify your custom data rows, you must provide an editor 162150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main activity in your own application. 162250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 162350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 162450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To display your custom data, provide a <code>contacts.xml</code> file containing a 162550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><ContactsAccountType></code> element and one or more of its 162650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><ContactsDataKind></code> child elements. This is described in more detail in the 162750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main section <a href="#SocialStreamDataKind"><code><ContactsDataKind> element</code></a>. 162850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 162950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 163050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To learn more about custom MIME types, read the 163150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> 163250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Creating a Content Provider</a> guide. 163350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 163450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="SyncAdapters">Contacts Provider Sync Adapters</h2> 163550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 163650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider is specifically designed for handling <strong>synchronization</strong> 163750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of contacts data between a device and an online service. This allows users to download 163850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main existing data to a new device and upload existing data to a new account. 163950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Synchronization also ensures that users have the latest data at hand, regardless 164050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of the source of additions and changes. Another advantage of synchronization is that it makes 164150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts data available even when the device is not connected to the network. 164250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 164350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 164450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Although you can implement synchronization in a variety of ways, the Android system provides 164550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a plug-in synchronization framework that automates the following tasks: 164650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 164750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 164850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 164950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Checking network availability. 165050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 165150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 165250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Scheduling and executing synchronization, based on user preferences. 165350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 165450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 165550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Restarting synchronizations that have stopped. 165650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 165750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 165850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 165950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To use this framework, you supply a sync adapter plug-in. Each sync adapter is unique to a 166050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main service and content provider, but can handle multiple account names for the same service. The 166150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main framework also allows multiple sync adapters for the same service and provider. 166250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 166350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="SyncClassesFiles">Sync adapter classes and files</h3> 166450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 166550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main You implement a sync adapter as a subclass of 166650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.AbstractThreadedSyncAdapter} and install it as part of an Android 166750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main application. The system learns about the sync adapter from elements in your application 166850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main manifest, and from a special XML file pointed to by the manifest. The XML file defines the 166950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account type for the online service and the authority for the content provider, which together 167050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main uniquely identify the adapter. The sync adapter does not become active until the user adds an 167150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account for the sync adapter's account type and enables synchronization for the content 167250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main provider the sync adapter syncs with. At that point, the system starts managing the adapter, 167350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main calling it as necessary to synchronize between the content provider and the server. 167450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 167550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"> 167650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Note:</strong> Using an account type as part of the sync adapter's identification allows 167750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the system to detect and group together sync adapters that access different services from the 167850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main same organization. For example, sync adapters for Google online services all have the same 167950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account type <code>com.google</code>. When users add a Google account to their devices, all 168050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of the installed sync adapters for Google services are listed together; each sync adapter 168150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main listed syncs with a different content provider on the device. 168250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 168350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 168450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Because most services require users to verify their identity before accessing 168550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main data, the Android system offers an authentication framework that is similar to, and often 168650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main used in conjunction with, the sync adapter framework. The authentication framework uses 168750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main plug-in authenticators that are subclasses of 168850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.accounts.AbstractAccountAuthenticator}. An authenticator verifies 168950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the user's identity in the following steps: 169050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ol> 169150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 169250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Collects the user's name, password or similar information (the user's 169350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>credentials</strong>). 169450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 169550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 169650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sends the credentials to the service 169750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 169850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 169950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Examines the service's reply. 170050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 170150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ol> 170250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 170350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If the service accepts the credentials, the authenticator can 170450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main store the credentials for later use. Because of the plug-in authenticator framework, the 170550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.accounts.AccountManager} can provide access to any authtokens an authenticator 170650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main supports and chooses to expose, such as OAuth2 authtokens. 170750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 170850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 170950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Although authentication is not required, most contacts services use it. 171050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main However, you're not required to use the Android authentication framework to do authentication. 171150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 171250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="SyncAdapterImplementing">Sync adapter implementation</h3> 171350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 171450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To implement a sync adapter for the Contacts Provider, you start by creating an 171550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Android application that contains the following: 171650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 171750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dl> 171850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 171950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A {@link android.app.Service} component that responds to requests from the system to 172050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main bind to the sync adapter. 172150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 172250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 172350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main When the system wants to run a synchronization, it calls the service's 172450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.Service#onBind(Intent) onBind()} method to get an 172550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.os.IBinder} for the sync adapter. This allows the system to do 172650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main cross-process calls to the adapter's methods. 172750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 172850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> 172950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sample Sync Adapter</a> sample app, the class name of this service is 173050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>com.example.android.samplesync.syncadapter.SyncService</code>. 173150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 173250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 173350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 173450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The actual sync adapter, implemented as a concrete subclass of 173550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.AbstractThreadedSyncAdapter}. 173650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 173750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 173850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This class does the work of downloading data from the server, uploading data from the 173950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main device, and resolving conflicts. The main work of the adapter is 174050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main done in the method {@link android.content.AbstractThreadedSyncAdapter#onPerformSync( 174150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Account, Bundle, String, ContentProviderClient, SyncResult) 174250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main onPerformSync()}. This class must be instantiated as a singleton. 174350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 174450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> 174550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sample Sync Adapter</a> sample app, the sync adapter is defined in the class 174650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>com.example.android.samplesync.syncadapter.SyncAdapter</code>. 174750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 174850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 174950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 175050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A subclass of {@link android.app.Application}. 175150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 175250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 175350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This class acts as a factory for the sync adapter singleton. Use the 175450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.Application#onCreate()} method to instantiate the sync adapter, and 175550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main provide a static "getter" method to return the singleton to the 175650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.Service#onBind(Intent) onBind()} method of the sync adapter's 175750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main service. 175850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 175950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 176050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Optional:</strong> A {@link android.app.Service} component that responds to 176150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main requests from the system for user authentication. 176250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 176350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 176450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.accounts.AccountManager} starts this service to begin the authentication 176550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main process. The service's {@link android.app.Service#onCreate()} method instantiates an 176650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main authenticator object. When the system wants to authenticate a user account for the 176750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main application's sync adapter, it calls the service's 176850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.app.Service#onBind(Intent) onBind()} method to get an 176950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.os.IBinder} for the authenticator. This allows the system to do 177050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main cross-process calls to the authenticator's methods.. 177150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 177250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> 177350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sample Sync Adapter</a> sample app, the class name of this service is 177450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>com.example.android.samplesync.authenticator.AuthenticationService</code>. 177550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 177650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 177750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 177850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Optional:</strong> A concrete subclass of 177950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.accounts.AbstractAccountAuthenticator} that handles requests for 178050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main authentication. 178150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 178250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 178350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This class provides methods that the {@link android.accounts.AccountManager} invokes 178450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to authenticate the user's credentials with the server. The details of the 178550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main authentication process vary widely, based on the server technology in use. You should 178650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main refer to the documentation for your server software to learn more about authentication. 178750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 178850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> 178950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Sample Sync Adapter</a> sample app, the authenticator is defined in the class 179050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>com.example.android.samplesync.authenticator.Authenticator</code>. 179150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 179250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 179350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 179450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main XML files that define the sync adapter and authenticator to the system. 179550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 179650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 179750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The sync adapter and authenticator service components described previously are 179850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main defined in 179950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><<a href="{@docRoot}guide/topics/manifest/service-element.html">service</a>></code> 180050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main elements in the application manifest. These elements 180150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contain 180250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> 180350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainchild elements that provide specific data to the 180450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main system: 180550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 180650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 180750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The 180850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> 180950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main element for the sync adapter service points to the 181050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main XML file <code>res/xml/syncadapter.xml</code>. In turn, this file specifies 181150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a URI for the web service that will be synchronized with the Contacts Provider, 181250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main and an account type for the web service. 181350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 181450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 181550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Optional:</strong> The 181650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> 181750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main element for the authenticator points to the XML file 181850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>res/xml/authenticator.xml</code>. In turn, this file specifies the 181950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main account type that this authenticator supports, as well as UI resources that 182050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main appear during the authentication process. The account type specified in this 182150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main element must be the same as the account type specified for the sync 182250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main adapter. 182350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 182450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 182550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 182650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dl> 182750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="SocialStream">Social Stream Data</h2> 182850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 18296d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov The android.provider.ContactsContract.StreamItems and 18306d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotos tables 183150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main manage incoming data from social networks. You can write a sync adapter that adds stream data 183250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main from your own network to these tables, or you can read stream data from these tables and 183350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main display it in your own application, or both. With these features, your social networking 183450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main services and applications can be integrated into Android's social networking experience. 183550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 183650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="StreamText">Social stream text</h3> 183750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 183850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Stream items are always associated with a raw contact. The 18396d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID links to the 184050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>_ID</code> value for the raw contact. The account type and account name of the raw 184150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact are also stored in the stream item row. 184250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 184350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 184450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Store the data from your stream in the following columns: 184550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 184650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 184750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 18486d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE 184950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 185050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 185150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Required.</strong> The user's account type for the raw contact associated with this 185250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main stream item. Remember to set this value when you insert a stream item. 185350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 185450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 18556d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME 185650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 185750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 185850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Required.</strong> The user's account name for the raw contact associated with this 185950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main stream item. Remember to set this value when you insert a stream item. 186050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 186150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 186250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Identifier columns 186350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 186450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 186550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Required.</strong> You must insert the following identifier columns when you 186650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main insert a stream item: 186750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 186850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 18696d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID: The 18706d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.BaseColumns#_ID value of the contact that this stream 187150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main item is associated with. 187250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 187350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 18746d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY: The 18756d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY value of the 187650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact this stream item is associated with. 187750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 187850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 18796d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID: The 18806d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.BaseColumns#_ID value of the raw contact that this stream 188150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main item is associated with. 188250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 188350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 188450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 188550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 18866d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#COMMENTS 188750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 188850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 188950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Optional. Stores summary information that you can display at the beginning of a stream item. 189050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 189150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 18926d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#TEXT 189350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 189450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 189550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The text of the stream item, either the content that was posted by the source of the item, 189650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main or a description of some action that generated the stream item. This column can contain 189750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main any formatting and embedded resource images that can be rendered by 189850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.text.Html#fromHtml(String) fromHtml()}. The provider may truncate or 189950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ellipsize long content, but it will try to avoid breaking tags. 190050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 190150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 19026d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP 190350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 190450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 190550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A text string containing the time the stream item was inserted or updated, in the form 190650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of <em>milliseconds</em> since epoch. Applications that insert or update stream items are 190750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main responsible for maintaining this column; it is not automatically maintained by the 190850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Contacts Provider. 190950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 191050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 191150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 191250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To display identifying information for your stream items, use the 19136d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#RES_ICON, 19146d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#RES_LABEL, and 19156d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE to link to resources 191650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main in your application. 191750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 191850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 19196d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov The android.provider.ContactsContract.StreamItems table also contains the columns 19206d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#SYNC1 through 19216d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#SYNC4 for the exclusive use of 192250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sync adapters. 192350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 192450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="StreamPhotos">Social stream photos</h3> 192550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 19266d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov The android.provider.ContactsContract.StreamItemPhotos table stores photos associated 192750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main with a stream item. The table's 19286d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID column 192950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main links to values in the {@link android.provider.BaseColumns#_ID} column of 19306d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItems table. Photo references are stored in the 193150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main table in these columns: 193250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 193350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 193450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 19356d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotos#PHOTO column (a BLOB). 193650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 193750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 193850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A binary representation of the photo, resized by the provider for storage and display. 193950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main This column is available for backwards compatibility with previous versions of the Contacts 194050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Provider that used it for storing photos. However, in the current version 194150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main you should not use this column to store photos. Instead, use 19426d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov either android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID or 19436d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI (both of 194450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which are described in the following points) to store photos in a file. This column now 194550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contains a thumbnail of the photo, which is available for reading. 194650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 194750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 19486d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID 194950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 195050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 195150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A numeric identifier of a photo for a raw contact. Append this value to the constant 195250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.DisplayPhoto#CONTENT_URI DisplayPhoto.CONTENT_URI} 195350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to get a content URI pointing to a single photo file, and then call 195450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) 195550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main openAssetFileDescriptor()} to get a handle to the photo file. 195650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 195750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt> 19586d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI 195950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dt> 196050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 196150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A content URI pointing directly to the photo file for the photo represented by this row. 196250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Call {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) 196350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main openAssetFileDescriptor()} with this URI to get a handle to the photo file. 196450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 196550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 196650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="SocialStreamTables">Using the social stream tables</h3> 196750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 196850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main These tables work the same as the other main tables in the Contacts Provider, except that: 196950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 197050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 197150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 197250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main These tables require additional access permissions. To read from them, your application 19736d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov must have the permission android.Manifest.permission#READ_SOCIAL_STREAM. To 197450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main modify them, your application must have the permission 19756d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.Manifest.permission#WRITE_SOCIAL_STREAM. 197650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 197750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 19786d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov For the android.provider.ContactsContract.StreamItems table, the number of rows 197950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main stored for each raw contact is limited. Once this limit is reached, 198050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the Contacts Provider makes space for new stream item rows by automatically deleting 198150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the rows having the oldest 19826d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP. To get the 198350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main limit, issue a query to the content URI 19846d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI. You can leave 198550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main all the arguments other than the content URI set to <code>null</code>. The query 198650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main returns a Cursor containing a single row, with the single column 19876d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItems#MAX_ITEMS. 198850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 198950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 199050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 199150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 19926d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov The class android.provider.ContactsContract.StreamItems.StreamItemPhotos defines a 19936d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov sub-table of android.provider.ContactsContract.StreamItemPhotos containing the photo 199450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main rows for a single stream item. 199550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 199650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="SocialStreamInteraction">Social stream interactions</h3> 199750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 199850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The social stream data managed by the Contacts Provider, in conjunction with the 199950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main device's contacts application, offers a powerful way to connect your social networking system 200050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main with existing contacts. The following features are available: 200150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 200250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 200350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 200450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main By syncing your social networking service to the Contacts Provider with a sync 200550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main adapter, you can retrieve recent activity for a user's contacts and store it in 20066d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov the android.provider.ContactsContract.StreamItems and 20076d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotos tables for later use. 200850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 200950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 201050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Besides regular synchronization, you can trigger your sync adapter to retrieve 201150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main additional data when the user selects a contact to view. This allows your sync adapter 201250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to retrieve high-resolution photos and the most recent stream items for the contact. 201350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 201450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 201550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main By registering a notification with the device's contacts application and the Contacts 201650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Provider, you can <em>receive</em> an intent when a contact is viewed, and at that point 201750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main update the contact's status from your service. This approach may be faster and use less 201850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main bandwidth than doing a full sync with a sync adapter. 201950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 202050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 202150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Users can add a contact to your social networking service while looking at the contact 202250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main in the device's contacts application. You enable this with the "invite contact" feature, 202350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main which you enable with a combination of an activity that adds an existing contact to your 202450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main network, and an XML file that provides the device's contacts application and the 202550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Contacts Provider with the details of your application. 202650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 202750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 202850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 202950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Regular synchronization of stream items with the Contacts Provider is the same as 203050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main other synchronizations. To learn more about synchronization, see the section 203150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#SyncAdapters">Contacts Provider Sync Adapters</a>. Registering notifications and 203250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main inviting contacts are covered in the next two sections. 203350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 203450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h4>Registering to handle social networking views</h4> 203550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 203650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To register your sync adapter to receive notifications when the user views a contact that's 203750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main managed by your sync adapter: 203850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 203950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 204050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 204150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Create a file named <code>contacts.xml</code> in your project's <code>res/xml/</code> 204250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main directory. If you already have this file, you can skip this step. 204350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 204450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 204550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In this file, add the element 204650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. 204750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If this element already exists, you can skip this step. 204850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 204950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 205050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To register a service that is notified when the user opens a contact's detail page in 205150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the device's contacts application, add the attribute 205250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>viewContactNotifyService="<em>serviceclass</em>"</code> to the element, where 205350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><em>serviceclass</em></code> is the fully-qualified classname of the service 205450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that should receive the intent from the device's contacts application. For the notifier 205550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main service, use a class that extends {@link android.app.IntentService}, to allow the service to 205650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main receive intents. The data in the incoming intent contains the content URI of the raw 205750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact the user clicked. From the notifier service, you can bind to and then call your 205850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sync adapter to update the data for the raw contact. 205950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 206050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 206150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 206250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To register an activity to be called when the user clicks on a stream item or photo or both: 206350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 206450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 206550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 206650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Create a file named <code>contacts.xml</code> in your project's <code>res/xml/</code> 206750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main directory. If you already have this file, you can skip this step. 206850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 206950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 207050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In this file, add the element 207150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. 207250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If this element already exists, you can skip this step. 207350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 207450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 207550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To register one of your activities to handle the user clicking on a stream item in the 207650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main device's contacts application, add the attribute 207750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>viewStreamItemActivity="<em>activityclass</em>"</code> to the element, where 207850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><em>activityclass</em></code> is the fully-qualified classname of the activity 207950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that should receive the intent from the device's contacts application. 208050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 208150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 208250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To register one of your activities to handle the user clicking on a stream photo in the 208350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main device's contacts application, add the attribute 208450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>viewStreamItemPhotoActivity="<em>activityclass</em>"</code> to the element, where 208550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><em>activityclass</em></code> is the fully-qualified classname of the activity 208650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that should receive the intent from the device's contacts application. 208750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 208850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 208950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 209050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The <code><ContactsAccountType></code> element is described in more detail in the 209150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main section <a href="#SocialStreamAcctType"><ContactsAccountType> element</a>. 209250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 209350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 209450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The incoming intent contains the content URI of the item or photo that the user clicked. 209550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main To have separate activities for text items and for photos, use both attributes in the same file. 209650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 209750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h4>Interacting with your social networking service</h4> 209850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 209950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Users don't have to leave the device's contacts application to invite a contact to your social 210050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main networking site. Instead, you can have the device's contacts app send an intent for inviting the 210150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact to one of your activities. To set this up: 210250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 210350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 210450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 210550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Create a file named <code>contacts.xml</code> in your project's <code>res/xml/</code> 210650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main directory. If you already have this file, you can skip this step. 210750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 210850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 210950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main In this file, add the element 211050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. 211150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If this element already exists, you can skip this step. 211250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 211350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 211450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Add the following attributes: 211550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 211650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><code>inviteContactActivity="<em>activityclass</em>"</code></li> 211750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li> 211850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>inviteContactActionLabel="@string/<em>invite_action_label</em>"</code> 211950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 212050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 212150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The <code><em>activityclass</em></code> value is the fully-qualified classname of the 212250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main activity that should receive the intent. The <code><em>invite_action_label</em></code> 212350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main value is a text string that's displayed in the <strong>Add Connection</strong> menu in the 212450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main device's contacts application. 212550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </li> 212650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 212750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"> 212850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Note:</strong> <code>ContactsSource</code> is a deprecated tag name for 212950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>ContactsAccountType</code>. 213050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 213150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="ContactsFile">contacts.xml reference</h3> 213250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 213350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The file <code>contacts.xml</code> contains XML elements that control the interaction of your 213450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sync adapter and application with the contacts application and the Contacts Provider. These 213550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main elements are described in the following sections. 213650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 213750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h4 id="SocialStreamAcctType"><ContactsAccountType> element</h4> 213850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 213950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The <code><ContactsAccountType></code> element controls the interaction of your 214050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main application with the contacts application. It has the following syntax: 214150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 214250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 214350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ContactsAccountType 214450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main xmlns:android="http://schemas.android.com/apk/res/android" 214550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main inviteContactActivity="<em>activity_name</em>" 214650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main inviteContactActionLabel="<em>invite_command_text</em>" 214750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main viewContactNotifyService="<em>view_notify_service</em>" 214850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main viewGroupActivity="<em>group_view_activity</em>" 214950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main viewGroupActionLabel="<em>group_action_text</em>" 215050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main viewStreamItemActivity="<em>viewstream_activity_name</em>" 215150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main viewStreamItemPhotoActivity="<em>viewphotostream_activity_name</em>"> 215250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 215350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 215450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>contained in:</strong> 215550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 215650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 215750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>res/xml/contacts.xml</code> 215850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 215950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 216050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>can contain:</strong> 216150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 216250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 216350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong><code><ContactsDataKind></code></strong> 216450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 216550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 216650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Description:</strong> 216750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 216850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 216950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Declares Android components and UI labels that allow users to invite one of their contacts to 217050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main a social network, notify users when one of their social networking streams is updated, and 217150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main so forth. 217250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 217350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 217450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Notice that the attribute prefix <code>android:</code> is not necessary for the attributes 217550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of <code><ContactsAccountType></code>. 217650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 217750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 217850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Attributes:</strong> 217950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 218050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 218150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code inviteContactActivity}</dt> 218250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 218350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The fully-qualified class name of the activity in your application that you want to 218450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main activate when the user selects <strong>Add connection</strong> from the device's 218550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts application. 218650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 218750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code inviteContactActionLabel}</dt> 218850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 218950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A text string that is displayed for the activity specified in 219050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@code inviteContactActivity}, in the <strong>Add connection</strong> menu. 219150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For example, you can use the string "Follow in my network". You can use a string resource 219250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main identifier for this label. 219350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 219450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code viewContactNotifyService}</dt> 219550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 219650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The fully-qualified class name of a service in your application that should receive 219750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main notifications when the user views a contact. This notification is sent by the device's 219850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts application; it allows your application to postpone data-intensive operations 219950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main until they're needed. For example, your application can respond to this notification 220050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main by reading in and displaying the contact's high-resolution photo and most recent 220150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main social stream items. This feature is described in more detail in the section 220250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#SocialStreamInteraction">Social stream interactions</a>. You can see an 220350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main example of the notification service in the <code>NotifierService.java</code> file in the 220450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a> 220550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main sample app. 220650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 220750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code viewGroupActivity}</dt> 220850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 220950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The fully-qualified class name of an activity in your application that can display 221050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main group information. When the user clicks the group label in the device's contacts 221150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main application, the UI for this activity is displayed. 221250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 221350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code viewGroupActionLabel}</dt> 221450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 221550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The label that the contacts application displays for a UI control that allows 221650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the user to look at groups in your application. 221750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 221850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main For example, if you install the Google+ application on your device and you sync 221950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Google+ with the contacts application, you'll see Google+ circles listed as groups 222050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main in your contacts application's <strong>Groups</strong> tab. If you click on a 222150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Google+ circle, you'll see people in that circle listed as a "group". At the top of 222250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the display, you'll see a Google+ icon; if you click it, control switches to the 222350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Google+ app. The contacts application does this with the 222450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@code viewGroupActivity}, using the Google+ icon as the value of 222550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@code viewGroupActionLabel}. 222650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 222750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p> 222850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main A string resource identifier is allowed for this attribute. 222950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </p> 223050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 223150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code viewStreamItemActivity}</dt> 223250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 223350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The fully-qualified class name of an activity in your application that the device's 223450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts application launches when the user clicks a stream item for a raw contact. 223550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 223650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code viewStreamItemPhotoActivity}</dt> 223750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 223850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The fully-qualified class name of an activity in your application that the device's 223950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contacts application launches when the user clicks a photo in the stream item 224050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main for a raw contact. 224150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 224250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 224350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h4 id="SocialStreamDataKind"><ContactsDataKind> element</h4> 224450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 224550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The <code><ContactsDataKind></code> element controls the display of your application's 224650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main custom data rows in the contacts application's UI. It has the following syntax: 224750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 224850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 224950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ContactsDataKind 225050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:mimeType="<em>MIMEtype</em>" 225150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:icon="<em>icon_resources</em>" 225250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:summaryColumn="<em>column_name</em>" 225350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:detailColumn="<em>column_name</em>"> 225450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 225550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 225650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>contained in:</strong> 225750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 225850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><ContactsAccountType></code> 225950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 226050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Description:</strong> 226150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 226250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 226350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Use this element to have the contacts application display the contents of a custom data row as 226450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main part of the details of a raw contact. Each <code><ContactsDataKind></code> child element 226550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of <code><ContactsAccountType></code> represents a type of custom data row that your sync 226650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main adapter adds to the {@link android.provider.ContactsContract.Data} table. Add one 226750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code><ContactsDataKind></code> element for each custom MIME type you use. You don't have 226850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to add the element if you have a custom data row for which you don't want to display data. 226950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 227050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 227150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Attributes:</strong> 227250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 227350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<dl> 227450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code android:mimeType}</dt> 227550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 227650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The custom MIME type you've defined for one of your custom data row types in the 227750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} table. For example, the value 227850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <code>vnd.android.cursor.item/vnd.example.locationstatus</code> could be a custom 227950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main MIME type for a data row that records a contact's last known location. 228050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 228150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code android:icon}</dt> 228250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 228350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main An Android 228450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> 228550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main that the contacts application displays next to your data. Use this to indicate to the 228650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main user that the data comes from your service. 228750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 228850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code android:summaryColumn}</dt> 228950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 229050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The column name for the first of two values retrieved from the data row. The 229150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main value is displayed as the first line of the entry for this data row. The first line is 229250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main intended to be used as a summary of the data, but that is optional. See also 229350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <a href="#detailColumn">android:detailColumn</a>. 229450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 229550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dt>{@code android:detailColumn}</dt> 229650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <dd> 229750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The column name for the second of two values retrieved from the data row. The value is 229850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main displayed as the second line of the entry for this data row. See also 229950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@code android:summaryColumn}. 230050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </dd> 230150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</dl> 230250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="AdditionalFeatures">Additional Contacts Provider Features</h2> 230350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 230450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Besides the main features described in previous sections, the Contacts Provider offers 230550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main these useful features for working with contacts data: 230650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 230750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <ul> 230850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Contact groups</li> 230950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Photo features</li> 231050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </ul> 231150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="Groups">Contact groups</h3> 231250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 231350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The Contacts Provider can optionally label collections of related contacts with 231450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>group</strong> data. If the server associated with a user account 231550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main wants to maintain groups, the sync adapter for the account's account type should transfer 231650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main groups data between the Contacts Provider and the server. When users add a new contact to the 231750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main server and then put this contact in a new group, the sync adapter must add the new group 231850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to the {@link android.provider.ContactsContract.Groups} table. The group or groups a raw 231950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main contact belongs to are stored in the {@link android.provider.ContactsContract.Data} table, using 232050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership} MIME type. 232150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 232250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 232350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main If you're designing a sync adapter that will add raw contact data from 232450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main server to the Contacts Provider, and you aren't using groups, then you need to tell the 232550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Provider to make your data visible. In the code that is executed when a user adds an account 232650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main to the device, update the {@link android.provider.ContactsContract.Settings} 232750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main row that the Contacts Provider adds for the account. In this row, set the value of the 232850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE 232950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Settings.UNGROUPED_VISIBLE} column to 1. When you do this, the Contacts Provider will always 233050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main make your contacts data visible, even if you don't use groups. 233150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 233250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h3 id="Photos">Contact photos</h3> 233350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 233450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The {@link android.provider.ContactsContract.Data} table stores photos as rows with MIME type 233550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE 233650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Photo.CONTENT_ITEM_TYPE}. The row's 233750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContactsColumns#CONTACT_ID} column is linked to the 233850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.BaseColumns#_ID} column of the raw contact to which it belongs. 233950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The class {@link android.provider.ContactsContract.Contacts.Photo} defines a sub-table of 234050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Contacts} containing photo information for a contact's 234150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main primary photo, which is the primary photo of the contact's primary raw contact. Similarly, 234250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main the class {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} defines a sub-table 234350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main of {@link android.provider.ContactsContract.RawContacts} containing photo information for a 234450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main raw contact's primary photo. 234550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 234650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 234750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main The reference documentation for {@link android.provider.ContactsContract.Contacts.Photo} and 234850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} contain examples of 234950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main retrieving photo information. There is no convenience class for retrieving the primary 235050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main thumbnail for a raw contact, but you can send a query to the 235150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.Data} table, selecting on the raw contact's 235250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.BaseColumns#_ID}, the 235350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE 235450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Photo.CONTENT_ITEM_TYPE}, and the {@link android.provider.ContactsContract.Data#IS_PRIMARY} 235550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main column to find the raw contact's primary photo row. 235650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 235750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p> 235850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Social stream data for a person may also include photos. These are stored in the 23596d2c0e5ee2f717d4a5c00df08aca21c76eea8278Svetoslav Ganov android.provider.ContactsContract.StreamItemPhotos table, which is described in more 236050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main detail in the section <a href="#StreamPhotos">Social stream photos</a>. 236150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</p> 2362