Merge "Improve ContactsContract documentation, esp. of Data inner class"

import android.content.ContentUris;

import android.content.ContentValues;

import android.content.Context;

import android.content.Intent;

import android.content.CursorEntityIterator;

import android.content.EntityIterator;

import android.content.Entity;

import android.content.EntityIterator;

import android.content.Intent;

import android.content.res.Resources;

import android.database.Cursor;

import android.database.DatabaseUtils;

 * </li>

 * <li>

 * A row in the {@link RawContacts} table represents a set of Data describing a

 * person and associated with a single account.

 * person and associated with a single account (for example, a single Gmail

 * account).

 * </li>

 * <li>

 * A row in the {@link Contacts} table represents an aggregate of one or more

    }

    /**

     * Columns of {@link ContactsContract.Contacts} that track the user's

     * preferences for, or interactions with, the contact.

     *

     * @see Contacts

     * @see RawContacts

     * @see ContactsContract.Data

        public static final String STARRED = "starred";

        /**

         * A custom ringtone associated with a contact. Not always present.

         * URI for a custom ringtone associated with the contact. If null or missing,

         * the default ringtone is used.

         * <P>Type: TEXT (URI to the ringtone)</P>

         */

        public static final String CUSTOM_RINGTONE = "custom_ringtone";

        /**

         * Whether the contact should always be sent to voicemail. Not always

         * present.

         * Whether the contact should always be sent to voicemail. If missing,

         * defaults to false.

         * <P>Type: INTEGER (0 for false, 1 for true)</P>

         */

        public static final String SEND_TO_VOICEMAIL = "send_to_voicemail";

    }

    /**

     * Columns of {@link ContactsContract.Contacts} that refer to intrinsic

     * properties of the contact, as opposed to the user-specified options

     * found in {@link ContactOptionsColumns}.

     *

     * @see Contacts

     * @see ContactsContract.Data

     * @see PhoneLookup

    }

    /**

     * Contact name and contact name metadata columns in the RawContacts table.

     *

     * @see Contacts

     * @see RawContacts

     * @hide

        @Deprecated

        public static final String PRESENCE_STATUS = PRESENCE;

        /*

         * Presence Status definition

        /**

         * An allowed value of {@link #PRESENCE}.

         */

        int OFFLINE = 0;

        /**

         * An allowed value of {@link #PRESENCE}.

         */

        int INVISIBLE = 1;

        /**

         * An allowed value of {@link #PRESENCE}.

         */

        int AWAY = 2;

        /**

         * An allowed value of {@link #PRESENCE}.

         */

        int IDLE = 3;

        /**

         * An allowed value of {@link #PRESENCE}.

         */

        int DO_NOT_DISTURB = 4;

        /**

         * An allowed value of {@link #PRESENCE}.

         */

        int AVAILABLE = 5;

        /**

        /**

         * @deprecated use {@link #STATUS}

         */

        @Deprecated

        public static final String PRESENCE_CUSTOM_STATUS = STATUS;

        /**

        public static final String RAW_CONTACT_ID = "raw_contact_id";

        /**

         * Whether this is the primary entry of its kind for the raw contact it belongs to

         * Whether this is the primary entry of its kind for the raw contact it belongs to.

         * <P>Type: INTEGER (if set, non-0 means true)</P>

         */

        public static final String IS_PRIMARY = "is_primary";

        public static final String DATA13 = "data13";

        /** Generic data column, the meaning is {@link #MIMETYPE} specific */

        public static final String DATA14 = "data14";

        /** Generic data column, the meaning is {@link #MIMETYPE} specific */

        /**

         * Generic data column, the meaning is {@link #MIMETYPE} specific. By convention,

         * this field is used to store BLOBs (binary data).

         */

        public static final String DATA15 = "data15";

        /** Generic column for use by sync adapters. */

    /**

     * <p>

     * Constants for the data table, which contains data points tied to a raw

     * contact. For example, a phone number or email address.

     * contact.  Each row of the data table is typically used to store a single

     * piece of contact

     * information (such as a phone number) and its

     * associated metadata (such as whether it is a work or home number).

     * </p>

     * <h3>Data kinds</h3>

     * <p>

     * Data is a generic table that can hold all kinds of data. Sync adapters

     * and applications can introduce their own data kinds. The kind of data

     * stored in a particular row is determined by the mime type in the row.

     * Fields from {@link #DATA1} through {@link #DATA15} are generic columns

     * whose specific use is determined by the kind of data stored in the row.

     * Data is a generic table that can hold any kind of contact data.

     * The kind of data stored in a given row is specified by the row's

     * {@link #MIMETYPE} value, which determines the meaning of the

     * generic columns {@link #DATA1} through

     * {@link #DATA15}.

     * For example, if the data kind is

     * {@link CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE}, then DATA1 stores the

     * {@link CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE}, then the column

     * {@link #DATA1} stores the

     * phone number, but if the data kind is

     * {@link CommonDataKinds.Email Email.CONTENT_ITEM_TYPE}, then DATA1 stores the

     * email address.

     * {@link CommonDataKinds.Email Email.CONTENT_ITEM_TYPE}, then {@link #DATA1}

     * stores the email address.

     * Sync adapters and applications can introduce their own data kinds.

     * </p>

     * <p>

     * ContactsContract defines a small number of common data kinds, e.g.

     * ContactsContract defines a small number of pre-defined data kinds, e.g.

     * {@link CommonDataKinds.Phone}, {@link CommonDataKinds.Email} etc. As a

     * convenience, these classes define data kind specific aliases for DATA1 etc.

     * For example, {@link CommonDataKinds.Phone Phone.NUMBER} is the same as

     * By convention, {@link #DATA15} is used for storing BLOBs (binary data).

     * </p>

     * <p>

     * Typically you should refrain from introducing new kinds of data for 3rd

     * party account types. For example, if you add a data row for

     * Typically you should refrain from introducing new kinds of data for an other

     * party's account types. For example, if you add a data row for

     * "favorite song" to a raw contact owned by a Google account, it will not

     * get synced to the server, because the Google sync adapter does not know

     * how to handle this data kind. Thus new data kinds are typically

     * </dd>

     * </dl>

     * <h2>Columns</h2>

     * <p>

     * Many columns are available via a {@link Data#CONTENT_URI} query.  For best performance you

     * should explicitly specify a projection to only those columns that you need.

     * </p>

     * <table class="jd-sumtable">

     * <tr>

     * <th colspan='4'>Data</th>

     * <td style="width: 20em;">{@link #_ID}</td>

     * <td style="width: 5em;">read-only</td>

     * <td>Row ID. Sync adapter should try to preserve row IDs during updates. In other words,

     * it would be a bad idea to delete and reinsert a data rows. A sync adapter should

     * it would be a bad idea to delete and reinsert a data row. A sync adapter should

     * always do an update instead.</td>

     * </tr>

     * <tr>

     * <td>long</td>

     * <td>{@link #RAW_CONTACT_ID}</td>

     * <td>read/write-once</td>

     * <td>A reference to the {@link RawContacts#_ID} that this data belongs to.</td>

     * </tr>

     * <tr>

     * <td>long</td>

     * <td>{@link #CONTACT_ID}</td>

     * <td>read-only</td>

     * <td>A reference to the {@link ContactsContract.Contacts#_ID} that this data row belongs

     * to. It is obtained through a join with RawContacts.</td>

     * <td>The id of the row in the {@link RawContacts} table that this data belongs to.</td>

     * </tr>

     * <tr>

     * <td>int</td>

     * <td>{@link #IS_PRIMARY}</td>

     * <td>read/write</td>

     * <td>Whether this is the primary entry of its kind for the raw contact it belongs to.

     * "1" if true, "0" if false.</td>

     * "1" if true, "0" if false.

     * </td>

     * </tr>

     * <tr>

     * <td>int</td>

     * <td>read/write</td>

     * <td>Whether this is the primary entry of its kind for the aggregate

     * contact it belongs to. Any data record that is "super primary" must

     * also be "primary".</td>

     * also be "primary".  For example, the super-primary entry may be

     * interpreted as the default contact value of its kind (for example,

     * the default phone number to use for the contact).</td>

     * </tr>

     * <tr>

     * <td>int</td>

     * {@link #DATA15}

     * </td>

     * <td>read/write</td>

     * <td>Generic data columns, the meaning is {@link #MIMETYPE} specific.</td>

     * <td>

     * <p>

     * Generic data columns.  The meaning of each column is determined by the

     * {@link #MIMETYPE}.  By convention, {@link #DATA15} is used for storing

     * BLOBs (binary data).

     * </p>

     * <p>

     * Data columns whose meaning is not explicitly defined for a given MIMETYPE

     * should not be used.  There is no guarantee that any sync adapter will

     * preserve them.  Sync adapters themselves should not use such columns either,

     * but should instead use {@link #SYNC1}-{@link #SYNC4}.

     * </p>

     * </td>

     * </tr>

     * <tr>

     * <td>Any type</td>

     * </tr>

     * </table>

     *

     * <p>

     * Some columns from the most recent associated status update are also available

     * through an implicit join.

     * </p>

     * <table class="jd-sumtable">

     * <tr>

     * <th colspan='4'>Join with {@link StatusUpdates}</th>

     * </table>

     *

     * <p>

     * Columns from the associated raw contact are also available through an

     * implicit join.

     * Some columns from the associated raw contact are also available through an

     * implicit join.  The other columns are excluded as uninteresting in this

     * context.

     * </p>

     *

     * <table class="jd-sumtable">

     * <tr>

     * <th colspan='4'>Join with {@link RawContacts}</th>

     * <th colspan='4'>Join with {@link ContactsContract.RawContacts}</th>

     * </tr>

     * <tr>

     * <td style="width: 7em;">int</td>

     * <td style="width: 20em;">{@link #AGGREGATION_MODE}</td>

     * <td style="width: 7em;">long</td>

     * <td style="width: 20em;">{@link #CONTACT_ID}</td>

     * <td style="width: 5em;">read-only</td>

     * <td>The id of the row in the {@link Contacts} table that this data belongs

     * to.</td>

     * </tr>

     * <tr>

     * <td>int</td>

     * <td>{@link #AGGREGATION_MODE}</td>

     * <td>read-only</td>

     * <td>See {@link RawContacts}.</td>

     * </tr>

     * <tr>

     * </table>

     *

     * <p>

     * Columns from the associated aggregated contact are also available through an

     * implicit join.

     * The ID column for the associated aggregated contact table

     * {@link ContactsContract.Contacts} is available

     * via the implicit join to the {@link RawContacts} table, see above.

     * The remaining columns from this table are also

     * available, through an implicit join.  This

     * facilitates lookup by

     * the value of a single data element, such as the email address.

     * </p>

     *

     * <table class="jd-sumtable">

     * <tr>

     * <th colspan='4'>Join with {@link Contacts}</th>

     * <th colspan='4'>Join with {@link ContactsContract.Contacts}</th>

     * </tr>

     * <tr>

     * <td style="width: 7em;">String</td>

        private Data() {}

        /**

         * The content:// style URI for this table

         * The content:// style URI for this table, which requests a directory

         * of data rows matching the selection criteria.

         */

        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data");

        /**

         * The MIME type of {@link #CONTENT_URI} providing a directory of data.

         * The MIME type of the results from {@link #CONTENT_URI}.

         */

        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data";

        /**

         * <p>

         * If {@link #FOR_EXPORT_ONLY} is explicitly set to "1", returned Cursor toward

         * Data.CONTENT_URI contains only exportable data.

         *

         * </p>

         * <p>

         * This flag is useful (currently) only for vCard exporter in Contacts app, which

         * needs to exclude "un-exportable" data from available data to export, while

         * Contacts app itself has priviledge to access all data including "un-exportable"

         * ones and providers return all of them regardless of the callers' intention.

         * <P>Type: INTEGER</p>

         * </p>

         * <p>

         * Type: INTEGER

         * </p>

         *

         * @hide Maybe available only in Eclair and not really ready for public use.

         * TODO: remove, or implement this feature completely. As of now (Eclair),

        public static final String FOR_EXPORT_ONLY = "for_export_only";

        /**

         * <p>

         * Build a {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}

         * style {@link Uri} for the parent {@link android.provider.ContactsContract.Contacts}

         * entry of the given {@link ContactsContract.Data} entry.

         * </p>

         * <p>

         * Returns the Uri for the contact in the first entry returned by

         * {@link ContentResolver#query(Uri, String[], String, String[], String)}

         * for the provided {@code dataUri}.  If the query returns null or empty

         * results, silently returns null.

         * </p>

         */

        public static Uri getContactLookupUri(ContentResolver resolver, Uri dataUri) {

            final Cursor cursor = resolver.query(dataUri, new String[] {

    /**

     * <p>

     * Constants for the raw contacts entities table, which can be though of as

     * Constants for the raw contacts entities table, which can be thought of as

     * an outer join of the raw_contacts table with the data table.  It is a strictly

     * read-only table.

     * </p>