ContactsContract.Data RAW_CONTACT_ID 和CONTACT_ID

According to the Google folks on the list, the recommended method is not to add contacts yourself but rather to use the Intents.Insert intent; this allows the user to confirm the data by hand, and your app will not actually require the CONTACTS_WRITE permission.  They're discouraging.

http://d.android.com/reference/android/provider/ContactsContract.Intent.

That said, the difference between CONTACT_ID and RAW_CONTACT_ID is simple: a contact (identified by CONTACT_ID) is a virtual, combined contact.  This is what the 2.0 Contacts app shows, where you might have information pulled from two different Google accounts /and/ your Facebook account.  A given contact contains one or more 'raw contacts' (identified by RAW_CONTACT_ID), which are the actual individual records from the different accounts.

Let's say I have two Google accounts (work and home) where I have different information for John Example.

At work, I have:

John Example

E-mail: john.exam...@company.com

Phone: 800-555-1212 x200

Phone: 213-555-8888

At home, I have:

John Example:

E-mail: johndo...@gmail.com

Phone: 213-555-8888

Address: 1234 Demonstration Way

         Sampletown, CA

Each of these two records is a 'raw contact.'  However, under 2.0, the contacts app will spot them as the same person (or I could manually join them in the contacts app), and so the 'contact' (containing two raw contacts) will show:

John Example

E-mail: john.exam...@company.com

E-mail: johndo...@gmail.com

Phone: 800-555-1212 x200

Phone: 213-555-8888

Address: 1234 Demonstration Way

         Sampletown, CA

If I edit that contact in the contacts app, I will actually be shown two separate contacts to edit, representing the fact that the virtual contact contains two different record.

If I use the CONTACT, I will get the combined information (though in my query, I may get the 213-555-8888 phone number twice because of the duplication of data across the two accounts).  If I use the RAW_CONTACT, I will get the two separate individual contacts.  Obviously, for reading contact data, the CONTACT is more useful, as you get the most complete information available.  *However,* if you want to write data to a contact, you need be writing to a RAW_CONTACT, rather than the virtual combined contact, and so if I wanted to add a nickname field to John, I'd really need to pick one of the two other contacts to add that data to.

I'm still working on gathering what information on ContactsContract that I can, and organizing an FAQ/set-of-guidelines for the API, so that we have a centralized source of information.