@@ -75,7 +77,8 @@ import java.io.InputStream; *
*+ * Pronunciation of the full name in the phonetic alphabet specified by + * {@link #PHONETIC_NAME_STYLE}. + *
+ *+ * The value may be set manually by the user. + * This capability is is of interest only in countries + * with commonly used phonetic + * alphabets, such as Japan and Korea. See PhoneticNameStyle. + *
+ * + * TODO: convert PhoneticNameStyle to a link after it is un-hidden */ public static final String PHONETIC_NAME = "phonetic_name"; /** * Sort key that takes into account locale-based traditions for sorting - * names in address books. More specifically, for Chinese names - * the sort key is the name's Pinyin spelling; for Japanese names + * names in address books. The default + * sort key is {@link #DISPLAY_NAME_PRIMARY}. For Chinese names + * the sort key is the name's Pinyin spelling, and for Japanese names * it is the Hiragana version of the phonetic name. */ public static final String SORT_KEY_PRIMARY = "sort_key"; /** * Sort key based on the alternative representation of the full name, - * specifically the one using the 'family name first' format for + * {@link #DISPLAY_NAME_ALTERNATIVE}. Thus for Western names, + * it is the one using the "family name first" format for * Western names. */ public static final String SORT_KEY_ALTERNATIVE = "sort_key_alt"; @@ -808,7 +834,10 @@ public final class ContactsContract { } /** - * Mark a contact as having been contacted. + * Mark a contact as having been contacted. This updates the + * {@link #TIMES_CONTACTED} and {@link #LAST_TIME_CONTACTED} for the + * contact, plus the corresponding values of any associated raw + * contacts. * * @param resolver the ContentResolver to use * @param contactId the person who was contacted @@ -1050,15 +1079,37 @@ public final class ContactsContract { } /** - * Constants for the raw contacts table, which contains the base contact - * information per sync source. Sync adapters and contact management apps + * Constants for the raw contacts table, which contains one row of contact + * information for each person in each synced account. Sync adapters and + * contact management apps * are the primary consumers of this API. + * + *+ * As soon as a raw contact is inserted or whenever its constituent data + * changes, the provider will check if the raw contact matches other + * existing raw contacts and if so will aggregate it with those. The + * aggregation is reflected in the {@link RawContacts} table by the change of the + * {@link #CONTACT_ID} field, which is the reference to the aggregate contact. + *
+ *+ * Changes to the structured name, organization, phone number, email address, + * or nickname trigger a re-aggregation. + *
+ *+ * See also {@link AggregationExceptions} for a mechanism to control + * aggregation programmatically. + *
+ * *+ * Raw contacts can be inserted incrementally or in a batch. + * The incremental method is more traditional but less efficient. + * It should be used + * only if no {@link Data} values are available at the time the raw contact is created: *
* ContentValues values = new ContentValues();
* values.put(RawContacts.ACCOUNT_TYPE, accountType);
@@ -1066,9 +1117,10 @@ public final class ContactsContract {
* Uri rawContactUri = getContentResolver().insert(RawContacts.CONTENT_URI, values);
* long rawContactId = ContentUris.parseId(rawContactUri);
*
+ *
* - * Once data rows are available, insert those. For example, here's how you would insert - * a name: + * Once {@link Data} values become available, insert those. + * For example, here's how you would insert a name: * *
* values.clear();
@@ -1084,6 +1136,7 @@ public final class ContactsContract {
* and causes at most one aggregation pass.
*
* ArrayList<ContentProviderOperation> ops = Lists.newArrayList();
+ * ...
* int rawContactInsertIndex = ops.size();
* ops.add(ContentProviderOperation.newInsert(RawContacts.CONTENT_URI)
* .withValue(RawContacts.ACCOUNT_TYPE, accountType)
@@ -1100,21 +1153,27 @@ public final class ContactsContract {
*
*
*
- * Please note the use of back reference in the construction of the
- * {@link ContentProviderOperation}. It allows an operation to use the result of
- * a previous operation by referring to it by its index in the batch.
+ * Note the use of {@link ContentProviderOperation.Builder#withValueBackReference(String, int)}
+ * to refer to the as-yet-unknown index value of the raw contact inserted in the
+ * first operation.
*
+ *
* Just as with insert, the update can be done incrementally or as a batch, the - * batch mode being the preferred method.
+ * Raw contacts can be updated incrementally or in a batch. + * Batch mode should be used whenever possible. + * The procedures and considerations are analogous to those documented above for inserts. + *
When a raw contact is deleted, all of its Data rows as well as StatusUpdates, * AggregationExceptions, PhoneLookup rows are deleted automatically. When all raw - * contacts in a Contact are deleted, the Contact itself is also deleted automatically. + * contacts associated with a {@link Contacts} row are deleted, the {@link Contacts} row + * itself is also deleted automatically. *
*- * The invocation of {@code resolver.delete(...)}, does not physically delete - * a raw contacts row. It sets the {@link #DELETED} flag on the raw contact and + * The invocation of {@code resolver.delete(...)}, does not immediately delete + * a raw contacts row. + * Instead, it sets the {@link #DELETED} flag on the raw contact and * removes the raw contact from its aggregate contact. * The sync adapter then deletes the raw contact from the server and * finalizes phone-side deletion by calling {@code resolver.delete(...)} @@ -1124,10 +1183,11 @@ public final class ContactsContract { * is marked for deletion, it will remain on the phone. However it will be * effectively invisible, because it will not be part of any aggregate contact. *
- * Finding all raw contacts in a Contact is easy: + * It is easy to find all raw contacts in a Contact: *
* Cursor c = getContentResolver().query(RawContacts.CONTENT_URI,
* new String[]{RawContacts._ID},
@@ -1136,7 +1196,7 @@ public final class ContactsContract {
*
*
* - * There are two ways to find raw contacts within a specific account, + * To find raw contacts within a specific account, * you can either put the account name and type in the selection or pass them as query * parameters. The latter approach is preferable, especially when you can reuse the * URI: @@ -1178,19 +1238,11 @@ public final class ContactsContract { *
*- * As soon as a raw contact is inserted or whenever its constituent data - * changes, the provider will check if the raw contact matches other - * existing raw contacts and if so will aggregate it with those. From the - * data standpoint, aggregation is reflected in the change of the - * {@link #CONTACT_ID} field, which is the reference to the aggregate contact. - *
- *- * See also {@link AggregationExceptions} for a mechanism to control - * aggregation programmatically. - *
*| RawContacts | @@ -1199,15 +1251,16 @@ public final class ContactsContract { *long | *{@link #_ID} | *read-only | - *Row ID. Sync adapter should try to preserve row IDs during updates. In other words, - * it would be a really bad idea to delete and reinsert a raw contact. A sync adapter should - * always do an update instead. | + *Row ID. Sync adapters should try to preserve row IDs during updates. In other words, + * it is much better for a sync adapter to update a raw contact rather than to delete and + * re-insert it. | *|||
|---|---|---|---|---|---|---|---|---|
| long | *{@link #CONTACT_ID} | *read-only | - *A reference to the {@link ContactsContract.Contacts#_ID} that this raw contact belongs + * | The ID of the row in the {@link ContactsContract.Contacts} table + * that this raw contact belongs * to. Raw contacts are linked to contacts by the aggregation process, which can be controlled * by the {@link #AGGREGATION_MODE} field and {@link AggregationExceptions}. | *The number of times the contact has been contacted. To have an effect * on the corresponding value of the aggregate contact, this field * should be set at the time the raw contact is inserted. - * See {@link ContactsContract.Contacts#markAsContacted}. | + * After that, this value is typically updated via + * {@link ContactsContract.Contacts#markAsContacted}. * *|||
| long | @@ -1247,14 +1301,16 @@ public final class ContactsContract { *The timestamp of the last time the contact was contacted. To have an effect * on the corresponding value of the aggregate contact, this field * should be set at the time the raw contact is inserted. - * See {@link ContactsContract.Contacts#markAsContacted}. | + * After that, this value is typically updated via + * {@link ContactsContract.Contacts#markAsContacted}. + * *|||||||
| int | *{@link #STARRED} | *read/write | *An indicator for favorite contacts: '1' if favorite, '0' otherwise. - * Changing this field immediately effects the corresponding aggregate contact: + * Changing this field immediately affects the corresponding aggregate contact: * if any raw contacts in that aggregate contact are starred, then the contact * itself is marked as starred. | *|||||
| {@link #ACCOUNT_NAME} | *read/write-once | *The name of the account instance to which this row belongs, which when paired with - * {@link #ACCOUNT_TYPE} identifies a specific account. It should be set at the time + * {@link #ACCOUNT_TYPE} identifies a specific account. + * For example, this will be the Gmail address if it is a Google account. + * It should be set at the time * the raw contact is inserted and never changed afterwards. | *||||||
| String | *{@link #ACCOUNT_TYPE} | *read/write-once | - *The type of account to which this row belongs, which when paired with - * {@link #ACCOUNT_NAME} identifies a specific account. It should be set at the time - * the raw contact is inserted and never changed afterwards. | + *
+ * + * The type of account to which this row belongs, which when paired with + * {@link #ACCOUNT_NAME} identifies a specific account. + * It should be set at the time + * the raw contact is inserted and never changed afterwards. + * + *+ * To ensure uniqueness, new account types should be chosen according to the + * Java package naming convention. Thus a Google account is of type "com.google". + * + * |
* ||||
| String | @@ -1302,8 +1370,8 @@ public final class ContactsContract { *String that uniquely identifies this row to its source account. * Typically it is set at the time the raw contact is inserted and never * changed afterwards. The one notable exception is a new raw contact: it - * will have an account name and type, but no source id. This should - * indicated to the sync adapter that a new contact needs to be created + * will have an account name and type, but no source id. This + * indicates to the sync adapter that a new contact needs to be created * server-side and its ID stored in the corresponding SOURCE_ID field on * the phone. * | @@ -1335,7 +1403,8 @@ public final class ContactsContract { *String | *{@link #SYNC1} | *read/write | - *Generic column for use by sync adapters. Content provider + * | Generic column provided for arbitrary use by sync adapters. + * The content provider * stores this information on behalf of the sync adapter but does not * interpret it in any way. * | @@ -1372,46 +1441,70 @@ public final class ContactsContract { } /** - * The content:// style URI for this table + * The content:// style URI for this table, which requests a directory of + * raw contact rows matching the selection criteria. */ public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "raw_contacts"); /** - * The MIME type of {@link #CONTENT_URI} providing a directory of - * people. + * The MIME type of the results from {@link #CONTENT_URI} when a specific + * ID value is not provided, and multiple raw contacts may be returned. */ public static final String CONTENT_TYPE = "vnd.android.cursor.dir/raw_contact"; /** - * The MIME type of a {@link #CONTENT_URI} subdirectory of a single - * person. + * The MIME type of the results when a raw contact ID is appended to {@link #CONTENT_URI}, + * yielding a subdirectory of a single person. */ public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/raw_contact"; /** - * Aggregation mode: aggregate asynchronously. + * Aggregation mode: aggregate immediately after insert or update operation(s) are complete. */ public static final int AGGREGATION_MODE_DEFAULT = 0; /** - * Aggregation mode: aggregate at the time the raw contact is inserted/updated. - * TODO: deprecate. Aggregation is now synchronous, this value is a no-op + * Do not use. + * + * @deprecated in favor of {@link #AGGREGATION_MODE_DEFAULT} */ + @Deprecated public static final int AGGREGATION_MODE_IMMEDIATE = 1; /** - * If {@link #AGGREGATION_MODE} is {@link #AGGREGATION_MODE_SUSPENDED}, changes - * to the raw contact do not cause its aggregation to be revisited. Note that changing + *||