To retrieve something from the Contacts Provider, you need to use the
content provider client class android.content.ContentResolver and its
query() method.
A query requires the *content URI* of the part of the provider you're
trying to query, a *projection* (the list of columns you want to retrieve),
*selection clause* (think SQL WHERE clause without the WHERE keyword),
*selection
arguments*, and a column name to use as the *sort order*. The method
returns an android.database.Cursor object.
Selection clause and selection arguments allow you to parameterize the
clause. For example, you can set the clause to "some_column_name = ?" and
the arguments array to {"Harry Truman"} and the resulting clause should be
interpreted by the provider as "some_column_name = 'Harry Truman'".
Think of a Cursor as a "list" of rows returned from the provider. You
traverse the rows with Cursor.moveToNext(), and get individual columns from
a row with index = Cursor.getColumnIndex(column_name) followed by var =
Cursor.getText(index). There are actually several different "get" methods
for different data types.
Now to the Contacts Provider. It gets tricky, because the definition of
"contact" is more complex (but more flexible) than you may think.
The provider really tracks what are called "raw contacts". A raw contact is
the representation of a person, defined by a name, a user account, and a
user account type. For example, "Harry Truman" for the device owner's
Google Contacts account *[email protected]* is a raw contact. "Harry
Truman" for the device owner's Twitter account *myTwitterID* is a *separate*
raw
contact. All of the raw contacts that seem to be the same person are linked
to a single "Harry Truman" contact. There are two separate tables in
Contacts Provider: RawContacts and Contacts.
Detailed information for a person, such as emails, postal addresses, and
phone numbers, is stored on a raw contact basis; contacts don't have any
independent details other than minor stuff. There can be several detail
rows for each raw contact; in fact, a raw contact can have several email
address rows. The documentation isn't easy to understand, because the Data
table that stores detail information is the *one* table for *every type* of
data row. Email addresses, phone numbers, and postal addresses are all
stored in the same table, even though they obviously need different column
names. The provider implements this by defining generic column names DATA1
through DATA15, and then defining aliases that are type-specific.
To see this, look at the Javadoc for
ContactsContract.CommonDataKinds.Email. At the top, you'll see a table with
the data columns and aliases.
When you access columns, you use the aliases.
The provider, however, makes it much more simple to look at the data. Use
the constants in ContactsContract.Contacts to retrieve the "contact" you're
looking for (or all of them, if you want). Get the _ID value for each
contact row. Use this to retrieve the raw contact. Given that, use the
column names defined in ContactsContract.RawContacts.Entity to retrieve the
detail data for a raw contact. The "entity" is a join of a raw contact and
all of its detail rows.
--
You received this message because you are subscribed to the Google
Groups "Android Developers" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/android-developers?hl=en
