ContactsContract.java revision dd768a6a736bc202b62aa20f3282b3cfb285dc7f 
1/*
2 * Copyright (C) 2009 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License
15 */
16
17package android.provider;
18
19import android.accounts.Account;
20import android.content.ContentProviderClient;
21import android.content.ContentProviderOperation;
22import android.content.ContentResolver;
23import android.content.ContentUris;
24import android.content.Context;
25import android.content.Intent;
26import android.content.res.Resources;
27import android.database.Cursor;
28import android.graphics.BitmapFactory;
29import android.graphics.Rect;
30import android.net.Uri;
31import android.os.RemoteException;
32import android.text.TextUtils;
33import android.util.Pair;
34import android.view.View;
35
36import java.io.ByteArrayInputStream;
37import java.io.InputStream;
38
39/**
40 * The contract between the contacts provider and applications. Contains definitions
41 * for the supported URIs and columns.
42 *
43 * @hide pending API council approval
44 */
45public final class ContactsContract {
46    /** The authority for the contacts provider */
47    public static final String AUTHORITY = "com.android.contacts";
48    /** A content:// style uri to the authority for the contacts provider */
49    public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY);
50
51    /**
52     * An optional insert, update or delete URI parameter that allows the caller
53     * to specify that it is a sync adapter. The default value is false. If true
54     * the dirty flag is not automatically set and the "syncToNetwork" parameter
55     * is set to false when calling
56     * {@link ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver, boolean)}.
57     */
58    public static final String CALLER_IS_SYNCADAPTER = "caller_is_syncadapter";
59
60    public interface SyncStateColumns extends SyncStateContract.Columns {
61    }
62
63    public static final class SyncState {
64        /**
65         * This utility class cannot be instantiated
66         */
67        private SyncState() {}
68
69        public static final String CONTENT_DIRECTORY =
70                SyncStateContract.Constants.CONTENT_DIRECTORY;
71
72        /**
73         * The content:// style URI for this table
74         */
75        public static final Uri CONTENT_URI =
76                Uri.withAppendedPath(AUTHORITY_URI, CONTENT_DIRECTORY);
77
78        /**
79         * @see android.provider.SyncStateContract.Helpers#get
80         */
81        public static byte[] get(ContentProviderClient provider, Account account)
82                throws RemoteException {
83            return SyncStateContract.Helpers.get(provider, CONTENT_URI, account);
84        }
85
86        /**
87         * @see android.provider.SyncStateContract.Helpers#get
88         */
89        public static Pair<Uri, byte[]> getWithUri(ContentProviderClient provider, Account account)
90                throws RemoteException {
91            return SyncStateContract.Helpers.getWithUri(provider, CONTENT_URI, account);
92        }
93
94        /**
95         * @see android.provider.SyncStateContract.Helpers#set
96         */
97        public static void set(ContentProviderClient provider, Account account, byte[] data)
98                throws RemoteException {
99            SyncStateContract.Helpers.set(provider, CONTENT_URI, account, data);
100        }
101
102        /**
103         * @see android.provider.SyncStateContract.Helpers#newSetOperation
104         */
105        public static ContentProviderOperation newSetOperation(Account account, byte[] data) {
106            return SyncStateContract.Helpers.newSetOperation(CONTENT_URI, account, data);
107        }
108    }
109
110    /**
111     * Generic columns for use by sync adapters. The specific functions of
112     * these columns are private to the sync adapter. Other clients of the API
113     * should not attempt to either read or write this column.
114     */
115    private interface BaseSyncColumns {
116
117        /** Generic column for use by sync adapters. */
118        public static final String SYNC1 = "sync1";
119        /** Generic column for use by sync adapters. */
120        public static final String SYNC2 = "sync2";
121        /** Generic column for use by sync adapters. */
122        public static final String SYNC3 = "sync3";
123        /** Generic column for use by sync adapters. */
124        public static final String SYNC4 = "sync4";
125    }
126
127    /**
128     * Columns that appear when each row of a table belongs to a specific
129     * account, including sync information that an account may need.
130     */
131    private interface SyncColumns extends BaseSyncColumns {
132        /**
133         * The name of the account instance to which this row belongs.
134         * <P>Type: TEXT</P>
135         */
136        public static final String ACCOUNT_NAME = "account_name";
137
138        /**
139         * The type of account to which this row belongs, which when paired with
140         * {@link #ACCOUNT_NAME} identifies a specific account.
141         * <P>Type: TEXT</P>
142         */
143        public static final String ACCOUNT_TYPE = "account_type";
144
145        /**
146         * String that uniquely identifies this row to its source account.
147         * <P>Type: TEXT</P>
148         */
149        public static final String SOURCE_ID = "sourceid";
150
151        /**
152         * Version number that is updated whenever this row or its related data
153         * changes.
154         * <P>Type: INTEGER</P>
155         */
156        public static final String VERSION = "version";
157
158        /**
159         * Flag indicating that {@link #VERSION} has changed, and this row needs
160         * to be synchronized by its owning account.
161         * <P>Type: INTEGER (boolean)</P>
162         */
163        public static final String DIRTY = "dirty";
164    }
165
166    public interface ContactOptionsColumns {
167        /**
168         * The number of times a person has been contacted
169         * <P>Type: INTEGER</P>
170         */
171        public static final String TIMES_CONTACTED = "times_contacted";
172
173        /**
174         * The last time a person was contacted.
175         * <P>Type: INTEGER</P>
176         */
177        public static final String LAST_TIME_CONTACTED = "last_time_contacted";
178
179        /**
180         * Is the contact starred?
181         * <P>Type: INTEGER (boolean)</P>
182         */
183        public static final String STARRED = "starred";
184
185        /**
186         * A custom ringtone associated with a person. Not always present.
187         * <P>Type: TEXT (URI to the ringtone)</P>
188         */
189        public static final String CUSTOM_RINGTONE = "custom_ringtone";
190
191        /**
192         * Whether the person should always be sent to voicemail. Not always
193         * present.
194         * <P>Type: INTEGER (0 for false, 1 for true)</P>
195         */
196        public static final String SEND_TO_VOICEMAIL = "send_to_voicemail";
197    }
198
199    private interface ContactsColumns {
200        /**
201         * The display name for the contact.
202         * <P>Type: TEXT</P>
203         */
204        public static final String DISPLAY_NAME = "display_name";
205
206        /**
207         * Reference to the row in the data table holding the photo.
208         * <P>Type: INTEGER REFERENCES data(_id)</P>
209         */
210        public static final String PHOTO_ID = "photo_id";
211
212        /**
213         * Lookup value that reflects the {@link Groups#GROUP_VISIBLE} state of
214         * any {@link CommonDataKinds.GroupMembership} for this contact.
215         */
216        public static final String IN_VISIBLE_GROUP = "in_visible_group";
217
218        /**
219         * Contact presence status.  See {@link android.provider.Im.CommonPresenceColumns}
220         * for individual status definitions.  This column is only returned if explicitly
221         * requested in the query projection.
222         * <p>Type: NUMBER</p>
223         */
224        public static final String PRESENCE_STATUS = Presence.PRESENCE_STATUS;
225
226        /**
227         * Contact presence custom status. This column is only returned if explicitly
228         * requested in the query projection.
229         * <p>Type: TEXT</p>
230         */
231        public static final String PRESENCE_CUSTOM_STATUS = Presence.PRESENCE_CUSTOM_STATUS;
232
233        /**
234         * An indicator of whether this contact has at least one phone number. "1" if there is
235         * at least one phone number, "0" otherwise.
236         * <P>Type: INTEGER</P>
237         */
238        public static final String HAS_PHONE_NUMBER = "has_phone_number";
239
240        /**
241         * An opaque value that contains hints on how to find the contact if
242         * its row id changed as a result of a sync or aggregation.
243         */
244        public static final String LOOKUP_KEY = "lookup";
245    }
246
247    /**
248     * Constants for the contacts table, which contains a record per group
249     * of raw contact representing the same person.
250     */
251    public static class Contacts implements BaseColumns, ContactsColumns,
252            ContactOptionsColumns {
253        /**
254         * This utility class cannot be instantiated
255         */
256        private Contacts()  {}
257
258        /**
259         * The content:// style URI for this table
260         */
261        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "contacts");
262
263        /**
264         * A content:// style URI for this table that should be used to create
265         * shortcuts or otherwise create long-term links to contacts. This URI
266         * should always be followed by a "/" and the contact's {@link #LOOKUP_KEY}.
267         * It can optionally also have a "/" and last known contact ID appended after
268         * that. This "complete" format is an important optimization and is highly recommended.
269         * <p>
270         * As long as the contact's row ID remains the same, this URI is
271         * equivalent to {@link #CONTENT_URI}. If the contact's row ID changes
272         * as a result of a sync or aggregation, this URI will look up the
273         * contact using indirect information (sync IDs or constituent raw
274         * contacts).
275         * <p>
276         * Lookup key should be appended unencoded - it is stored in the encoded
277         * form, ready for use in a URI.
278         */
279        public static final Uri CONTENT_LOOKUP_URI = Uri.withAppendedPath(CONTENT_URI,
280                "lookup");
281
282        /**
283         * Builds a {@link #CONTENT_LOOKUP_URI} style {@link Uri} describing the
284         * requested {@link Contacts} entry.
285         *
286         * @param contactUri A {@link #CONTENT_URI} row, or an existing
287         *            {@link #CONTENT_LOOKUP_URI} to attempt refreshing.
288         */
289        public static Uri getLookupUri(ContentResolver resolver, Uri contactUri) {
290            final Cursor c = resolver.query(contactUri, new String[] {
291                    Contacts.LOOKUP_KEY, Contacts._ID
292            }, null, null, null);
293            if (c == null) {
294                return null;
295            }
296
297            try {
298                if (c.moveToFirst()) {
299                    final String lookupKey = c.getString(0);
300                    final long contactId = c.getLong(1);
301                    return getLookupUri(contactId, lookupKey);
302                }
303            } finally {
304                c.close();
305            }
306            return null;
307        }
308
309        /**
310         * Build a {@link #CONTENT_LOOKUP_URI} lookup {@link Uri} using the
311         * given {@link Contacts#_ID} and {@link Contacts#LOOKUP_KEY}.
312         */
313        public static Uri getLookupUri(long contactId, String lookupKey) {
314            return ContentUris.withAppendedId(Uri.withAppendedPath(Contacts.CONTENT_LOOKUP_URI,
315                    lookupKey), contactId);
316        }
317
318        /**
319         * Computes a content URI (see {@link #CONTENT_URI}) given a lookup URI.
320         * <p>
321         * Returns null if the contact cannot be found.
322         */
323        public static Uri lookupContact(ContentResolver resolver, Uri lookupUri) {
324            if (lookupUri == null) {
325                return null;
326            }
327
328            Cursor c = resolver.query(lookupUri, new String[]{Contacts._ID}, null, null, null);
329            if (c == null) {
330                return null;
331            }
332
333            try {
334                if (c.moveToFirst()) {
335                    long contactId = c.getLong(0);
336                    return ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId);
337                }
338            } finally {
339                c.close();
340            }
341            return null;
342        }
343
344        /**
345         * The content:// style URI used for "type-to-filter" functionality on the
346         * {@link #CONTENT_URI} URI. The filter string will be used to match
347         * various parts of the contact name. The filter argument should be passed
348         * as an additional path segment after this URI.
349         */
350        public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(
351                CONTENT_URI, "filter");
352
353        /**
354         * The content:// style URI for this table joined with useful data from
355         * {@link Data}, filtered to include only starred contacts
356         * and the most frequently contacted contacts.
357         */
358        public static final Uri CONTENT_STREQUENT_URI = Uri.withAppendedPath(
359                CONTENT_URI, "strequent");
360
361        /**
362         * The content:// style URI used for "type-to-filter" functionality on the
363         * {@link #CONTENT_STREQUENT_URI} URI. The filter string will be used to match
364         * various parts of the contact name. The filter argument should be passed
365         * as an additional path segment after this URI.
366         */
367        public static final Uri CONTENT_STREQUENT_FILTER_URI = Uri.withAppendedPath(
368                CONTENT_STREQUENT_URI, "filter");
369
370        public static final Uri CONTENT_GROUP_URI = Uri.withAppendedPath(
371                CONTENT_URI, "group");
372
373        /**
374         * The MIME type of {@link #CONTENT_URI} providing a directory of
375         * people.
376         */
377        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/contact";
378
379        /**
380         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
381         * person.
382         */
383        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contact";
384
385        /**
386         * A sub-directory of a single contact that contains all of the constituent raw contact
387         * {@link Data} rows.
388         */
389        public static final class Data implements BaseColumns, DataColumns {
390            /**
391             * no public constructor since this is a utility class
392             */
393            private Data() {}
394
395            /**
396             * The directory twig for this sub-table
397             */
398            public static final String CONTENT_DIRECTORY = "data";
399        }
400
401        /**
402         * A sub-directory of a single contact aggregate that contains all aggregation suggestions
403         * (other contacts).  The aggregation suggestions are computed based on approximate
404         * data matches with this contact.
405         */
406        public static final class AggregationSuggestions implements BaseColumns, ContactsColumns {
407            /**
408             * No public constructor since this is a utility class
409             */
410            private AggregationSuggestions() {}
411
412            /**
413             * The directory twig for this sub-table
414             */
415            public static final String CONTENT_DIRECTORY = "suggestions";
416        }
417
418        /**
419         * A sub-directory of a single contact that contains the contact's primary photo.
420         */
421        public static final class Photo implements BaseColumns, DataColumns {
422            /**
423             * no public constructor since this is a utility class
424             */
425            private Photo() {}
426
427            /**
428             * The directory twig for this sub-table
429             */
430            public static final String CONTENT_DIRECTORY = "photo";
431        }
432
433        /**
434         * Opens an InputStream for the person's default photo and returns the
435         * photo as a Bitmap stream.
436         *
437         * @param contactUri the contact whose photo should be used
438         */
439        public static InputStream openContactPhotoInputStream(ContentResolver cr, Uri contactUri) {
440            Uri photoUri = Uri.withAppendedPath(contactUri, Photo.CONTENT_DIRECTORY);
441            if (photoUri == null) {
442                return null;
443            }
444            Cursor cursor = cr.query(photoUri,
445                    new String[]{ContactsContract.CommonDataKinds.Photo.PHOTO}, null, null, null);
446            try {
447                if (cursor == null || !cursor.moveToNext()) {
448                    return null;
449                }
450                byte[] data = cursor.getBlob(0);
451                if (data == null) {
452                    return null;
453                }
454                return new ByteArrayInputStream(data);
455            } finally {
456                if (cursor != null) {
457                    cursor.close();
458                }
459            }
460        }
461    }
462
463    private interface RawContactsColumns {
464        /**
465         * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} that this
466         * data belongs to.
467         * <P>Type: INTEGER</P>
468         */
469        public static final String CONTACT_ID = "contact_id";
470
471        /**
472         * Flag indicating that this {@link RawContacts} entry and its children has
473         * been restricted to specific platform apps.
474         * <P>Type: INTEGER (boolean)</P>
475         *
476         * @hide until finalized in future platform release
477         */
478        public static final String IS_RESTRICTED = "is_restricted";
479
480        /**
481         * The aggregation mode for this contact.
482         * <P>Type: INTEGER</P>
483         */
484        public static final String AGGREGATION_MODE = "aggregation_mode";
485
486        /**
487         * The "deleted" flag: "0" by default, "1" if the row has been marked
488         * for deletion. When {@link android.content.ContentResolver#delete} is
489         * called on a raw contact, it is marked for deletion and removed from its
490         * aggregate contact. The sync adaptor deletes the raw contact on the server and
491         * then calls ContactResolver.delete once more, this time passing the
492         * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to finalize
493         * the data removal.
494         * <P>Type: INTEGER</P>
495         */
496        public static final String DELETED = "deleted";
497    }
498
499    /**
500     * Constants for the raw_contacts table, which contains the base contact
501     * information per sync source. Sync adapters and contact management apps
502     * are the primary consumers of this API.
503     */
504    public static final class RawContacts implements BaseColumns, RawContactsColumns,
505            ContactOptionsColumns, SyncColumns  {
506        /**
507         * This utility class cannot be instantiated
508         */
509        private RawContacts() {
510        }
511
512        /**
513         * The content:// style URI for this table
514         */
515        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "raw_contacts");
516
517        /**
518         * The MIME type of {@link #CONTENT_URI} providing a directory of
519         * people.
520         */
521        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/raw_contact";
522
523        /**
524         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
525         * person.
526         */
527        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/raw_contact";
528
529        /**
530         * Aggregation mode: aggregate asynchronously.
531         */
532        public static final int AGGREGATION_MODE_DEFAULT = 0;
533
534        /**
535         * Aggregation mode: aggregate at the time the raw contact is inserted/updated.
536         */
537        public static final int AGGREGATION_MODE_IMMEDIATE = 1;
538
539        /**
540         * If {@link #AGGREGATION_MODE} is {@link #AGGREGATION_MODE_SUSPENDED}, changes
541         * to the raw contact do not cause its aggregation to be revisited. Note that changing
542         * {@link #AGGREGATION_MODE} from {@link #AGGREGATION_MODE_SUSPENDED} to
543         * {@link #AGGREGATION_MODE_DEFAULT} does not trigger an aggregation pass. Any subsequent
544         * change to the raw contact's data will.
545         */
546        public static final int AGGREGATION_MODE_SUSPENDED = 2;
547
548        /**
549         * Aggregation mode: never aggregate this raw contact (note that the raw contact will not
550         * have a corresponding Aggregate and therefore will not be included in Aggregates
551         * query results.)
552         */
553        public static final int AGGREGATION_MODE_DISABLED = 3;
554
555        /**
556         * Build a {@link Contacts#CONTENT_LOOKUP_URI} style {@link Uri} for the
557         * parent {@link Contacts} entry of the given {@link RawContacts} entry.
558         */
559        public static Uri getContactLookupUri(ContentResolver resolver, Uri rawContactUri) {
560            // TODO: use a lighter query by joining rawcontacts with contacts in provider
561            final Uri dataUri = Uri.withAppendedPath(rawContactUri, Data.CONTENT_DIRECTORY);
562            final Cursor cursor = resolver.query(dataUri, new String[] {
563                    RawContacts.CONTACT_ID, Contacts.LOOKUP_KEY
564            }, null, null, null);
565
566            Uri lookupUri = null;
567            try {
568                if (cursor != null && cursor.moveToFirst()) {
569                    final long contactId = cursor.getLong(0);
570                    final String lookupKey = cursor.getString(1);
571                    return Contacts.getLookupUri(contactId, lookupKey);
572                }
573            } finally {
574                if (cursor != null) cursor.close();
575            }
576            return lookupUri;
577        }
578
579        /**
580         * A sub-directory of a single raw contact that contains all of their {@link Data} rows.
581         * To access this directory append {@link Data#CONTENT_DIRECTORY} to the contact URI.
582         */
583        public static final class Data implements BaseColumns, DataColumns {
584            /**
585             * no public constructor since this is a utility class
586             */
587            private Data() {
588            }
589
590            /**
591             * The directory twig for this sub-table
592             */
593            public static final String CONTENT_DIRECTORY = "data";
594        }
595    }
596
597    private interface DataColumns {
598        /**
599         * The package name to use when creating {@link Resources} objects for
600         * this data row. This value is only designed for use when building user
601         * interfaces, and should not be used to infer the owner.
602         */
603        public static final String RES_PACKAGE = "res_package";
604
605        /**
606         * The MIME type of the item represented by this row.
607         */
608        public static final String MIMETYPE = "mimetype";
609
610        /**
611         * A reference to the {@link RawContacts#_ID}
612         * that this data belongs to.
613         */
614        public static final String RAW_CONTACT_ID = "raw_contact_id";
615
616        /**
617         * Whether this is the primary entry of its kind for the raw contact it belongs to
618         * <P>Type: INTEGER (if set, non-0 means true)</P>
619         */
620        public static final String IS_PRIMARY = "is_primary";
621
622        /**
623         * Whether this is the primary entry of its kind for the aggregate
624         * contact it belongs to. Any data record that is "super primary" must
625         * also be "primary".
626         * <P>Type: INTEGER (if set, non-0 means true)</P>
627         */
628        public static final String IS_SUPER_PRIMARY = "is_super_primary";
629
630        /**
631         * The version of this data record. This is a read-only value. The data column is
632         * guaranteed to not change without the version going up. This value is monotonically
633         * increasing.
634         * <P>Type: INTEGER</P>
635         */
636        public static final String DATA_VERSION = "data_version";
637
638        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
639        public static final String DATA1 = "data1";
640        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
641        public static final String DATA2 = "data2";
642        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
643        public static final String DATA3 = "data3";
644        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
645        public static final String DATA4 = "data4";
646        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
647        public static final String DATA5 = "data5";
648        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
649        public static final String DATA6 = "data6";
650        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
651        public static final String DATA7 = "data7";
652        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
653        public static final String DATA8 = "data8";
654        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
655        public static final String DATA9 = "data9";
656        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
657        public static final String DATA10 = "data10";
658        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
659        public static final String DATA11 = "data11";
660        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
661        public static final String DATA12 = "data12";
662        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
663        public static final String DATA13 = "data13";
664        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
665        public static final String DATA14 = "data14";
666        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
667        public static final String DATA15 = "data15";
668
669        /** Generic column for use by sync adapters. */
670        public static final String SYNC1 = "data_sync1";
671        /** Generic column for use by sync adapters. */
672        public static final String SYNC2 = "data_sync2";
673        /** Generic column for use by sync adapters. */
674        public static final String SYNC3 = "data_sync3";
675        /** Generic column for use by sync adapters. */
676        public static final String SYNC4 = "data_sync4";
677    }
678
679    /**
680     * Constants for the data table, which contains data points tied to a raw contact.
681     * For example, a phone number or email address. Each row in this table contains a type
682     * definition and some generic columns. Each data type can define the meaning for each of
683     * the generic columns.
684     */
685    public static final class Data implements BaseColumns, DataColumns, RawContactsColumns,
686            ContactsColumns, SyncColumns {
687        /**
688         * This utility class cannot be instantiated
689         */
690        private Data() {}
691
692        /**
693         * The content:// style URI for this table
694         */
695        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data");
696
697        /**
698         * The content:// style URI for this table joined with {@link Presence}
699         * data where applicable.
700         *
701         * @hide
702         */
703        public static final Uri CONTENT_WITH_PRESENCE_URI = Uri.withAppendedPath(AUTHORITY_URI,
704                "data_with_presence");
705
706        /**
707         * The MIME type of {@link #CONTENT_URI} providing a directory of data.
708         */
709        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data";
710
711        /**
712         * Build a {@link Contacts#CONTENT_LOOKUP_URI} style {@link Uri} for the
713         * parent {@link Contacts} entry of the given {@link Data} entry.
714         */
715        public static Uri getContactLookupUri(ContentResolver resolver, Uri dataUri) {
716            final Cursor cursor = resolver.query(dataUri, new String[] {
717                    RawContacts.CONTACT_ID, Contacts.LOOKUP_KEY
718            }, null, null, null);
719
720            Uri lookupUri = null;
721            try {
722                if (cursor != null && cursor.moveToFirst()) {
723                    final long contactId = cursor.getLong(0);
724                    final String lookupKey = cursor.getString(1);
725                    return Contacts.getLookupUri(contactId, lookupKey);
726                }
727            } finally {
728                if (cursor != null) cursor.close();
729            }
730            return lookupUri;
731        }
732    }
733
734    private interface PhoneLookupColumns {
735        /**
736         * The phone number as the user entered it.
737         * <P>Type: TEXT</P>
738         */
739        public static final String NUMBER = "number";
740
741        /**
742         * The type of phone number, for example Home or Work.
743         * <P>Type: INTEGER</P>
744         */
745        public static final String TYPE = "type";
746
747        /**
748         * The user defined label for the phone number.
749         * <P>Type: TEXT</P>
750         */
751        public static final String LABEL = "label";
752    }
753
754    /**
755     * A table that represents the result of looking up a phone number, for
756     * example for caller ID. To perform a lookup you must append the number you
757     * want to find to {@link #CONTENT_FILTER_URI}.
758     */
759    public static final class PhoneLookup implements BaseColumns, PhoneLookupColumns,
760            ContactsColumns, ContactOptionsColumns {
761        /**
762         * This utility class cannot be instantiated
763         */
764        private PhoneLookup() {}
765
766        /**
767         * The content:// style URI for this table. Append the phone number you want to lookup
768         * to this URI and query it to perform a lookup. For example:
769         *
770         * {@code
771         * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_URI, phoneNumber);
772         * }
773         */
774        public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(AUTHORITY_URI,
775                "phone_lookup");
776    }
777
778    /**
779     * Additional data mixed in with {@link Im.CommonPresenceColumns} to link
780     * back to specific {@link ContactsContract.Contacts#_ID} entries.
781     */
782    private interface PresenceColumns {
783
784        /**
785         * The unique ID for a row.
786         * <P>Type: INTEGER (long)</P>
787         */
788        public static final String _ID = "presence_id";
789
790        /**
791         * Reference to the {@link Data#_ID} entry that owns this presence.
792         * <P>Type: INTEGER</P>
793         */
794        public static final String DATA_ID = "presence_data_id";
795
796        /**
797         * <p>Type: NUMBER</p>
798         */
799        public static final String PROTOCOL = "protocol";
800
801        /**
802         * Name of the custom protocol.  Should be supplied along with the {@link #PROTOCOL} value
803         * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}.  Should be null or
804         * omitted if {@link #PROTOCOL} value is not
805         * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}.
806         *
807         * <p>Type: NUMBER</p>
808         */
809        public static final String CUSTOM_PROTOCOL = "custom_protocol";
810
811        /**
812         * The IM handle the presence item is for. The handle is scoped to
813         * {@link #PROTOCOL}.
814         * <P>Type: TEXT</P>
815         */
816        public static final String IM_HANDLE = "im_handle";
817
818        /**
819         * The IM account for the local user that the presence data came from.
820         * <P>Type: TEXT</P>
821         */
822        public static final String IM_ACCOUNT = "im_account";
823    }
824
825    public static final class Presence implements PresenceColumns, Im.CommonPresenceColumns {
826        /**
827         * This utility class cannot be instantiated
828         */
829        private Presence() {
830        }
831
832        /**
833         * The content:// style URI for this table
834         */
835        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "presence");
836
837        /**
838         * Gets the resource ID for the proper presence icon.
839         *
840         * @param status the status to get the icon for
841         * @return the resource ID for the proper presence icon
842         */
843        public static final int getPresenceIconResourceId(int status) {
844            switch (status) {
845                case AVAILABLE:
846                    return android.R.drawable.presence_online;
847                case IDLE:
848                case AWAY:
849                    return android.R.drawable.presence_away;
850                case DO_NOT_DISTURB:
851                    return android.R.drawable.presence_busy;
852                case INVISIBLE:
853                    return android.R.drawable.presence_invisible;
854                case OFFLINE:
855                default:
856                    return android.R.drawable.presence_offline;
857            }
858        }
859
860        /**
861         * Returns the precedence of the status code the higher number being the higher precedence.
862         *
863         * @param status The status code.
864         * @return An integer representing the precedence, 0 being the lowest.
865         */
866        public static final int getPresencePrecedence(int status) {
867            // Keep this function here incase we want to enforce a different precedence than the
868            // natural order of the status constants.
869            return status;
870        }
871
872        /**
873         * The MIME type of {@link #CONTENT_URI} providing a directory of
874         * presence details.
875         */
876        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/im-presence";
877
878        /**
879         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
880         * presence detail.
881         */
882        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im-presence";
883    }
884
885    /**
886     * Container for definitions of common data types stored in the {@link Data} table.
887     */
888    public static final class CommonDataKinds {
889        /**
890         * The {@link Data#RES_PACKAGE} value for common data that should be
891         * shown using a default style.
892         */
893        public static final String PACKAGE_COMMON = "common";
894
895        /**
896         * Columns common across the specific types.
897         */
898        private interface BaseCommonColumns {
899            /**
900             * The package name to use when creating {@link Resources} objects for
901             * this data row. This value is only designed for use when building user
902             * interfaces, and should not be used to infer the owner.
903             */
904            public static final String RES_PACKAGE = "res_package";
905
906            /**
907             * The MIME type of the item represented by this row.
908             */
909            public static final String MIMETYPE = "mimetype";
910
911            /**
912             * The {@link RawContacts#_ID} that this data belongs to.
913             */
914            public static final String RAW_CONTACT_ID = "raw_contact_id";
915        }
916
917        /**
918         * The base types that all "Typed" data kinds support.
919         */
920        public interface BaseTypes {
921
922            /**
923             * A custom type. The custom label should be supplied by user.
924             */
925            public static int TYPE_CUSTOM = 0;
926        }
927
928        /**
929         * Columns common across the specific types.
930         */
931        private interface CommonColumns extends BaseTypes{
932            /**
933             * The type of data, for example Home or Work.
934             * <P>Type: INTEGER</P>
935             */
936            public static final String TYPE = "data1";
937
938            /**
939             * The data for the contact method.
940             * <P>Type: TEXT</P>
941             */
942            public static final String DATA = "data2";
943
944            /**
945             * The user defined label for the the contact method.
946             * <P>Type: TEXT</P>
947             */
948            public static final String LABEL = "data3";
949        }
950
951        /**
952         * Parts of the name.
953         */
954        public static final class StructuredName implements BaseCommonColumns {
955            private StructuredName() {}
956
957            /** MIME type used when storing this in data table. */
958            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/name";
959
960            /**
961             * The given name for the contact.
962             * <P>Type: TEXT</P>
963             */
964            public static final String GIVEN_NAME = "data1";
965
966            /**
967             * The family name for the contact.
968             * <P>Type: TEXT</P>
969             */
970            public static final String FAMILY_NAME = "data2";
971
972            /**
973             * The contact's honorific prefix, e.g. "Sir"
974             * <P>Type: TEXT</P>
975             */
976            public static final String PREFIX = "data3";
977
978            /**
979             * The contact's middle name
980             * <P>Type: TEXT</P>
981             */
982            public static final String MIDDLE_NAME = "data4";
983
984            /**
985             * The contact's honorific suffix, e.g. "Jr"
986             */
987            public static final String SUFFIX = "data5";
988
989            /**
990             * The phonetic version of the given name for the contact.
991             * <P>Type: TEXT</P>
992             */
993            public static final String PHONETIC_GIVEN_NAME = "data6";
994
995            /**
996             * The phonetic version of the additional name for the contact.
997             * <P>Type: TEXT</P>
998             */
999            public static final String PHONETIC_MIDDLE_NAME = "data7";
1000
1001            /**
1002             * The phonetic version of the family name for the contact.
1003             * <P>Type: TEXT</P>
1004             */
1005            public static final String PHONETIC_FAMILY_NAME = "data8";
1006
1007            /**
1008             * The name that should be used to display the contact.
1009             * <i>Unstructured component of the name should be consistent with
1010             * its structured representation.</i>
1011             * <p>
1012             * Type: TEXT
1013             */
1014            public static final String DISPLAY_NAME = "data9";
1015        }
1016
1017        /**
1018         * A nickname.
1019         */
1020        public static final class Nickname implements CommonColumns, BaseCommonColumns {
1021            private Nickname() {}
1022
1023            /** MIME type used when storing this in data table. */
1024            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/nickname";
1025
1026            public static final int TYPE_DEFAULT = 1;
1027            public static final int TYPE_OTHER_NAME = 2;
1028            public static final int TYPE_MAINDEN_NAME = 3;
1029            public static final int TYPE_SHORT_NAME = 4;
1030            public static final int TYPE_INITIALS = 5;
1031
1032            /**
1033             * The name itself
1034             */
1035            public static final String NAME = DATA;
1036        }
1037
1038        /**
1039         * Common data definition for telephone numbers.
1040         */
1041        public static final class Phone implements BaseCommonColumns, CommonColumns {
1042            private Phone() {}
1043
1044            /** MIME type used when storing this in data table. */
1045            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone_v2";
1046
1047            /**
1048             * The MIME type of {@link #CONTENT_URI} providing a directory of
1049             * phones.
1050             */
1051            public static final String CONTENT_TYPE = "vnd.android.cursor.dir/phone_v2";
1052
1053            /**
1054             * The content:// style URI for all data records of the
1055             * {@link Phone#CONTENT_ITEM_TYPE} MIME type, combined with the
1056             * associated raw contact and aggregate contact data.
1057             */
1058            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
1059                    "phones");
1060
1061            /**
1062             * The content:// style URL for phone lookup using a filter. The filter returns
1063             * records of MIME type {@link Phone#CONTENT_ITEM_TYPE}. The filter is applied
1064             * to display names as well as phone numbers. The filter argument should be passed
1065             * as an additional path segment after this URI.
1066             */
1067            public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI,
1068                    "filter");
1069
1070            public static final int TYPE_HOME = 1;
1071            public static final int TYPE_MOBILE = 2;
1072            public static final int TYPE_WORK = 3;
1073            public static final int TYPE_FAX_WORK = 4;
1074            public static final int TYPE_FAX_HOME = 5;
1075            public static final int TYPE_PAGER = 6;
1076            public static final int TYPE_OTHER = 7;
1077            public static final int TYPE_CALLBACK = 8;
1078            public static final int TYPE_CAR = 9;
1079            public static final int TYPE_COMPANY_MAIN = 10;
1080            public static final int TYPE_ISDN = 11;
1081            public static final int TYPE_MAIN = 12;
1082            public static final int TYPE_OTHER_FAX = 13;
1083            public static final int TYPE_RADIO = 14;
1084            public static final int TYPE_TELEX = 15;
1085            public static final int TYPE_TTY_TDD = 16;
1086            public static final int TYPE_WORK_MOBILE = 17;
1087            public static final int TYPE_WORK_PAGER = 18;
1088            public static final int TYPE_ASSISTANT = 19;
1089            public static final int TYPE_MMS = 20;
1090
1091            /**
1092             * The phone number as the user entered it.
1093             * <P>Type: TEXT</P>
1094             */
1095            public static final String NUMBER = DATA;
1096
1097            public static final CharSequence getDisplayLabel(Context context, int type,
1098                    CharSequence label, CharSequence[] labelArray) {
1099                CharSequence display = "";
1100
1101                if (type != Phone.TYPE_CUSTOM) {
1102                    CharSequence[] labels = labelArray != null? labelArray
1103                            : context.getResources().getTextArray(
1104                                    com.android.internal.R.array.phoneTypes);
1105                    try {
1106                        display = labels[type - 1];
1107                    } catch (ArrayIndexOutOfBoundsException e) {
1108                        display = labels[Phone.TYPE_CUSTOM];
1109                    }
1110                } else {
1111                    if (!TextUtils.isEmpty(label)) {
1112                        display = label;
1113                    }
1114                }
1115                return display;
1116            }
1117
1118            public static final CharSequence getDisplayLabel(Context context, int type,
1119                    CharSequence label) {
1120                return getDisplayLabel(context, type, label, null);
1121            }
1122        }
1123
1124        /**
1125         * Common data definition for email addresses.
1126         */
1127        public static final class Email implements BaseCommonColumns, CommonColumns {
1128            private Email() {}
1129
1130            /** MIME type used when storing this in data table. */
1131            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/email_v2";
1132
1133            /**
1134             * The content:// style URI for all data records of the
1135             * {@link Email#CONTENT_ITEM_TYPE} MIME type, combined with the
1136             * associated raw contact and aggregate contact data.
1137             */
1138            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
1139                    "emails");
1140
1141            /**
1142             * The content:// style URL for looking up data rows by email address. The
1143             * lookup argument, an email address, should be passed as an additional path segment
1144             * after this URI.
1145             */
1146            public static final Uri CONTENT_LOOKUP_URI = Uri.withAppendedPath(CONTENT_URI,
1147                    "lookup");
1148
1149            @Deprecated
1150            public static final Uri CONTENT_FILTER_EMAIL_URI = CONTENT_LOOKUP_URI;
1151
1152            /**
1153             * The content:// style URL for email lookup using a filter. The filter returns
1154             * records of MIME type {@link Email#CONTENT_ITEM_TYPE}. The filter is applied
1155             * to display names as well as email addresses. The filter argument should be passed
1156             * as an additional path segment after this URI.
1157             */
1158            public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI,
1159                    "filter");
1160
1161            public static final int TYPE_HOME = 1;
1162            public static final int TYPE_WORK = 2;
1163            public static final int TYPE_OTHER = 3;
1164            public static final int TYPE_MOBILE = 4;
1165
1166            /**
1167             * The display name for the email address
1168             * <P>Type: TEXT</P>
1169             */
1170            public static final String DISPLAY_NAME = "data4";
1171        }
1172
1173        /**
1174         * Common data definition for postal addresses.
1175         */
1176        public static final class StructuredPostal implements BaseCommonColumns, CommonColumns {
1177            private StructuredPostal() {
1178            }
1179
1180            /** MIME type used when storing this in data table. */
1181            public static final String CONTENT_ITEM_TYPE =
1182                    "vnd.android.cursor.item/postal-address_v2";
1183
1184            /**
1185             * The MIME type of {@link #CONTENT_URI} providing a directory of
1186             * postal addresses.
1187             */
1188            public static final String CONTENT_TYPE = "vnd.android.cursor.dir/postal-address_v2";
1189
1190            /**
1191             * The content:// style URI for all data records of the
1192             * {@link StructuredPostal#CONTENT_ITEM_TYPE} MIME type.
1193             */
1194            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
1195                    "postals");
1196
1197            public static final int TYPE_HOME = 1;
1198            public static final int TYPE_WORK = 2;
1199            public static final int TYPE_OTHER = 3;
1200
1201            /**
1202             * The full, unstructured postal address. <i>This field must be
1203             * consistent with any structured data.</i>
1204             * <p>
1205             * Type: TEXT
1206             */
1207            public static final String FORMATTED_ADDRESS = DATA;
1208
1209            /**
1210             * Can be street, avenue, road, etc. This element also includes the
1211             * house number and room/apartment/flat/floor number.
1212             * <p>
1213             * Type: TEXT
1214             */
1215            public static final String STREET = "data6";
1216
1217            /**
1218             * Covers actual P.O. boxes, drawers, locked bags, etc. This is
1219             * usually but not always mutually exclusive with street.
1220             * <p>
1221             * Type: TEXT
1222             */
1223            public static final String POBOX = "data7";
1224
1225            /**
1226             * This is used to disambiguate a street address when a city
1227             * contains more than one street with the same name, or to specify a
1228             * small place whose mail is routed through a larger postal town. In
1229             * China it could be a county or a minor city.
1230             * <p>
1231             * Type: TEXT
1232             */
1233            public static final String NEIGHBORHOOD = "data8";
1234
1235            /**
1236             * Can be city, village, town, borough, etc. This is the postal town
1237             * and not necessarily the place of residence or place of business.
1238             * <p>
1239             * Type: TEXT
1240             */
1241            public static final String CITY = "data9";
1242
1243            /**
1244             * A state, province, county (in Ireland), Land (in Germany),
1245             * departement (in France), etc.
1246             * <p>
1247             * Type: TEXT
1248             */
1249            public static final String REGION = "data11";
1250
1251            /**
1252             * Postal code. Usually country-wide, but sometimes specific to the
1253             * city (e.g. "2" in "Dublin 2, Ireland" addresses).
1254             * <p>
1255             * Type: TEXT
1256             */
1257            public static final String POSTCODE = "data12";
1258
1259            /**
1260             * The name or code of the country.
1261             * <p>
1262             * Type: TEXT
1263             */
1264            public static final String COUNTRY = "data13";
1265        }
1266
1267        /**
1268         * Common data definition for IM addresses.
1269         */
1270        public static final class Im implements BaseCommonColumns, CommonColumns {
1271            private Im() {}
1272
1273            /** MIME type used when storing this in data table. */
1274            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im";
1275
1276            public static final int TYPE_HOME = 1;
1277            public static final int TYPE_WORK = 2;
1278            public static final int TYPE_OTHER = 3;
1279
1280            /**
1281             * This column should be populated with one of the defined
1282             * constants, e.g. {@link #PROTOCOL_YAHOO}. If the value of this
1283             * column is {@link #PROTOCOL_CUSTOM}, the {@link #CUSTOM_PROTOCOL}
1284             * should contain the name of the custom protocol.
1285             */
1286            public static final String PROTOCOL = "data5";
1287
1288            public static final String CUSTOM_PROTOCOL = "data6";
1289
1290            /*
1291             * The predefined IM protocol types.
1292             */
1293            public static final int PROTOCOL_CUSTOM = -1;
1294            public static final int PROTOCOL_AIM = 0;
1295            public static final int PROTOCOL_MSN = 1;
1296            public static final int PROTOCOL_YAHOO = 2;
1297            public static final int PROTOCOL_SKYPE = 3;
1298            public static final int PROTOCOL_QQ = 4;
1299            public static final int PROTOCOL_GOOGLE_TALK = 5;
1300            public static final int PROTOCOL_ICQ = 6;
1301            public static final int PROTOCOL_JABBER = 7;
1302            public static final int PROTOCOL_NETMEETING = 8;
1303        }
1304
1305        /**
1306         * Common data definition for organizations.
1307         */
1308        public static final class Organization implements BaseCommonColumns, CommonColumns {
1309            private Organization() {}
1310
1311            /** MIME type used when storing this in data table. */
1312            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/organization";
1313
1314            public static final int TYPE_WORK = 1;
1315            public static final int TYPE_OTHER = 2;
1316
1317            /**
1318             * The company as the user entered it.
1319             * <P>Type: TEXT</P>
1320             */
1321            public static final String COMPANY = DATA;
1322
1323            /**
1324             * The position title at this company as the user entered it.
1325             * <P>Type: TEXT</P>
1326             */
1327            public static final String TITLE = "data4";
1328
1329            /**
1330             * The department at this company as the user entered it.
1331             * <P>Type: TEXT</P>
1332             */
1333            public static final String DEPARTMENT = "data5";
1334
1335            /**
1336             * The job description at this company as the user entered it.
1337             * <P>Type: TEXT</P>
1338             */
1339            public static final String JOB_DESCRIPTION = "data6";
1340
1341            /**
1342             * The symbol of this company as the user entered it.
1343             * <P>Type: TEXT</P>
1344             */
1345            public static final String SYMBOL = "data7";
1346
1347            /**
1348             * The phonetic name of this company as the user entered it.
1349             * <P>Type: TEXT</P>
1350             */
1351            public static final String PHONETIC_NAME = "data8";
1352        }
1353
1354        /**
1355         * Common data definition for miscellaneous information.
1356         */
1357        public static final class Miscellaneous implements BaseCommonColumns {
1358            private Miscellaneous() {}
1359
1360            /** MIME type used when storing this in data table. */
1361            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/misc";
1362
1363            /**
1364             * The birthday as the user entered it.
1365             * <P>Type: TEXT</P>
1366             */
1367            public static final String BIRTHDAY = "data1";
1368
1369            /**
1370             * The nickname as the user entered it.
1371             * <P>Type: TEXT</P>
1372             */
1373            public static final String NICKNAME = "data2";
1374        }
1375
1376        /**
1377         * Common data definition for relations.
1378         */
1379        public static final class Relation implements BaseCommonColumns, CommonColumns {
1380            private Relation() {}
1381
1382            /** MIME type used when storing this in data table. */
1383            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/relation";
1384
1385            public static final int TYPE_ASSISTANT = 1;
1386            public static final int TYPE_BROTHER = 2;
1387            public static final int TYPE_CHILD = 3;
1388            public static final int TYPE_DOMESTIC_PARTNER = 4;
1389            public static final int TYPE_FATHER = 5;
1390            public static final int TYPE_FRIEND = 6;
1391            public static final int TYPE_MANAGER = 7;
1392            public static final int TYPE_MOTHER = 8;
1393            public static final int TYPE_PARENT = 9;
1394            public static final int TYPE_PARTNER = 10;
1395            public static final int TYPE_REFERRED_BY = 11;
1396            public static final int TYPE_RELATIVE = 12;
1397            public static final int TYPE_SISTER = 13;
1398            public static final int TYPE_SPOUSE = 14;
1399
1400            /**
1401             * The name of the relative as the user entered it.
1402             * <P>Type: TEXT</P>
1403             */
1404            public static final String NAME = DATA;
1405        }
1406
1407        /**
1408         * Common data definition for events.
1409         */
1410        public static final class Event implements BaseCommonColumns, CommonColumns {
1411            private Event() {}
1412
1413            /** MIME type used when storing this in data table. */
1414            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/event";
1415
1416            public static final int TYPE_ANNIVERSARY = 1;
1417            public static final int TYPE_OTHER = 2;
1418
1419            /**
1420             * The event start date as the user entered it.
1421             * <P>Type: TEXT</P>
1422             */
1423            public static final String START_DATE = DATA;
1424        }
1425
1426        /**
1427         * Photo of the contact.
1428         */
1429        public static final class Photo implements BaseCommonColumns {
1430            private Photo() {}
1431
1432            /** MIME type used when storing this in data table. */
1433            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/photo";
1434
1435            /**
1436             * Thumbnail photo of the raw contact. This is the raw bytes of an image
1437             * that could be inflated using {@link BitmapFactory}.
1438             * <p>
1439             * Type: BLOB
1440             */
1441            public static final String PHOTO = "data1";
1442        }
1443
1444        /**
1445         * Notes about the contact.
1446         */
1447        public static final class Note implements BaseCommonColumns {
1448            private Note() {}
1449
1450            /** MIME type used when storing this in data table. */
1451            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/note";
1452
1453            /**
1454             * The note text.
1455             * <P>Type: TEXT</P>
1456             */
1457            public static final String NOTE = "data1";
1458        }
1459
1460        /**
1461         * Group Membership.
1462         */
1463        public static final class GroupMembership implements BaseCommonColumns {
1464            private GroupMembership() {}
1465
1466            /** MIME type used when storing this in data table. */
1467            public static final String CONTENT_ITEM_TYPE =
1468                    "vnd.android.cursor.item/group_membership";
1469
1470            /**
1471             * The row id of the group that this group membership refers to. Exactly one of
1472             * this or {@link #GROUP_SOURCE_ID} must be set when inserting a row.
1473             * <P>Type: INTEGER</P>
1474             */
1475            public static final String GROUP_ROW_ID = "data1";
1476
1477            /**
1478             * The sourceid of the group that this group membership refers to.  Exactly one of
1479             * this or {@link #GROUP_ROW_ID} must be set when inserting a row.
1480             * <P>Type: TEXT</P>
1481             */
1482            public static final String GROUP_SOURCE_ID = "group_sourceid";
1483        }
1484
1485        /**
1486         * Website related to the contact.
1487         */
1488        public static final class Website implements BaseCommonColumns, CommonColumns {
1489            private Website() {}
1490
1491            /** MIME type used when storing this in data table. */
1492            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/website";
1493
1494            public static final int TYPE_HOMEPAGE = 1;
1495            public static final int TYPE_BLOG = 2;
1496            public static final int TYPE_PROFILE = 3;
1497            public static final int TYPE_HOME = 4;
1498            public static final int TYPE_WORK = 5;
1499            public static final int TYPE_FTP = 6;
1500            public static final int TYPE_OTHER = 7;
1501
1502            /**
1503             * The website URL string.
1504             * <P>Type: TEXT</P>
1505             */
1506            public static final String URL = "data1";
1507        }
1508    }
1509
1510    // TODO: make this private before unhiding
1511    public interface GroupsColumns {
1512        /**
1513         * The display title of this group.
1514         * <p>
1515         * Type: TEXT
1516         */
1517        public static final String TITLE = "title";
1518
1519        /**
1520         * The package name to use when creating {@link Resources} objects for
1521         * this group. This value is only designed for use when building user
1522         * interfaces, and should not be used to infer the owner.
1523         */
1524        public static final String RES_PACKAGE = "res_package";
1525
1526        /**
1527         * The display title of this group to load as a resource from
1528         * {@link #RES_PACKAGE}, which may be localized.
1529         * <P>Type: TEXT</P>
1530         */
1531        public static final String TITLE_RES = "title_res";
1532
1533        /**
1534         * Notes about the group.
1535         * <p>
1536         * Type: TEXT
1537         */
1538        public static final String NOTES = "notes";
1539
1540        /**
1541         * The ID of this group if it is a System Group, i.e. a group that has a special meaning
1542         * to the sync adapter, null otherwise.
1543         * <P>Type: TEXT</P>
1544         */
1545        public static final String SYSTEM_ID = "system_id";
1546
1547        /**
1548         * The total number of {@link Contacts} that have
1549         * {@link CommonDataKinds.GroupMembership} in this group. Read-only value that is only
1550         * present when querying {@link Groups#CONTENT_SUMMARY_URI}.
1551         * <p>
1552         * Type: INTEGER
1553         */
1554        public static final String SUMMARY_COUNT = "summ_count";
1555
1556        /**
1557         * The total number of {@link Contacts} that have both
1558         * {@link CommonDataKinds.GroupMembership} in this group, and also have phone numbers.
1559         * Read-only value that is only present when querying
1560         * {@link Groups#CONTENT_SUMMARY_URI}.
1561         * <p>
1562         * Type: INTEGER
1563         */
1564        public static final String SUMMARY_WITH_PHONES = "summ_phones";
1565
1566        /**
1567         * Flag indicating if the contacts belonging to this group should be
1568         * visible in any user interface.
1569         * <p>
1570         * Type: INTEGER (boolean)
1571         */
1572        public static final String GROUP_VISIBLE = "group_visible";
1573
1574        /**
1575         * The "deleted" flag: "0" by default, "1" if the row has been marked
1576         * for deletion. When {@link android.content.ContentResolver#delete} is
1577         * called on a raw contact, it is marked for deletion and removed from its
1578         * aggregate contact. The sync adaptor deletes the raw contact on the server and
1579         * then calls ContactResolver.delete once more, this time setting the the
1580         * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to finalize
1581         * the data removal.
1582         * <P>Type: INTEGER</P>
1583         */
1584        public static final String DELETED = "deleted";
1585
1586        /**
1587         * Whether this group should be synced if the SYNC_EVERYTHING settings
1588         * is false for this group's account.
1589         * <p>
1590         * Type: INTEGER (boolean)
1591         */
1592        public static final String SHOULD_SYNC = "should_sync";
1593    }
1594
1595    /**
1596     * Constants for the groups table.
1597     */
1598    public static final class Groups implements BaseColumns, GroupsColumns, SyncColumns {
1599        /**
1600         * This utility class cannot be instantiated
1601         */
1602        private Groups() {
1603        }
1604
1605        /**
1606         * The content:// style URI for this table
1607         */
1608        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "groups");
1609
1610        /**
1611         * The content:// style URI for this table joined with details data from
1612         * {@link Data}.
1613         */
1614        public static final Uri CONTENT_SUMMARY_URI = Uri.withAppendedPath(AUTHORITY_URI,
1615                "groups_summary");
1616
1617        /**
1618         * The MIME type of a directory of groups.
1619         */
1620        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/group";
1621
1622        /**
1623         * The MIME type of a single group.
1624         */
1625        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/group";
1626    }
1627
1628    /**
1629     * Constants for the contact aggregation exceptions table, which contains
1630     * aggregation rules overriding those used by automatic aggregation.  This type only
1631     * supports query and update. Neither insert nor delete are supported.
1632     */
1633    public static final class AggregationExceptions implements BaseColumns {
1634        /**
1635         * This utility class cannot be instantiated
1636         */
1637        private AggregationExceptions() {}
1638
1639        /**
1640         * The content:// style URI for this table
1641         */
1642        public static final Uri CONTENT_URI =
1643                Uri.withAppendedPath(AUTHORITY_URI, "aggregation_exceptions");
1644
1645        /**
1646         * The MIME type of {@link #CONTENT_URI} providing a directory of data.
1647         */
1648        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/aggregation_exception";
1649
1650        /**
1651         * The MIME type of a {@link #CONTENT_URI} subdirectory of an aggregation exception
1652         */
1653        public static final String CONTENT_ITEM_TYPE =
1654                "vnd.android.cursor.item/aggregation_exception";
1655
1656        /**
1657         * The type of exception: {@link #TYPE_KEEP_TOGETHER}, {@link #TYPE_KEEP_SEPARATE} or
1658         * {@link #TYPE_AUTOMATIC}.
1659         *
1660         * <P>Type: INTEGER</P>
1661         */
1662        public static final String TYPE = "type";
1663
1664        /**
1665         * Allows the provider to automatically decide whether the specified raw contacts should
1666         * be included in the same aggregate contact or not.
1667         */
1668        public static final int TYPE_AUTOMATIC = 0;
1669
1670        /**
1671         * Makes sure that the specified raw contacts are included in the same
1672         * aggregate contact.
1673         */
1674        public static final int TYPE_KEEP_TOGETHER = 1;
1675
1676        @Deprecated
1677        public static final int TYPE_KEEP_IN = 1;
1678
1679        /**
1680         * Makes sure that the specified raw contacts are NOT included in the same
1681         * aggregate contact.
1682         */
1683        public static final int TYPE_KEEP_SEPARATE = 2;
1684
1685        @Deprecated
1686        public static final int TYPE_KEEP_OUT = 2;
1687
1688        @Deprecated
1689        public static final String CONTACT_ID = "contact_id";
1690
1691        @Deprecated
1692        public static final String RAW_CONTACT_ID = "raw_contact_id";
1693
1694        /**
1695         * A reference to the {@link RawContacts#_ID} of the raw contact that the rule applies to.
1696         */
1697        public static final String RAW_CONTACT_ID1 = "raw_contact_id1";
1698
1699        /**
1700         * A reference to the other {@link RawContacts#_ID} of the raw contact that the rule
1701         * applies to.
1702         */
1703        public static final String RAW_CONTACT_ID2 = "raw_contact_id2";
1704    }
1705
1706    private interface SettingsColumns {
1707        /**
1708         * The name of the account instance to which this row belongs.
1709         * <P>Type: TEXT</P>
1710         */
1711        public static final String ACCOUNT_NAME = "account_name";
1712
1713        /**
1714         * The type of account to which this row belongs, which when paired with
1715         * {@link #ACCOUNT_NAME} identifies a specific account.
1716         * <P>Type: TEXT</P>
1717         */
1718        public static final String ACCOUNT_TYPE = "account_type";
1719
1720        /**
1721         * Depending on the mode defined by the sync-adapter, this flag controls
1722         * the top-level sync behavior for this data source.
1723         * <p>
1724         * Type: INTEGER (boolean)
1725         */
1726        public static final String SHOULD_SYNC = "should_sync";
1727
1728        /**
1729         * Flag indicating if contacts without any {@link CommonDataKinds.GroupMembership}
1730         * entries should be visible in any user interface.
1731         * <p>
1732         * Type: INTEGER (boolean)
1733         */
1734        public static final String UNGROUPED_VISIBLE = "ungrouped_visible";
1735
1736        /**
1737         * Read-only flag indicating if this {@link #SHOULD_SYNC} or any
1738         * {@link Groups#SHOULD_SYNC} under this account have been marked as
1739         * unsynced.
1740         */
1741        public static final String ANY_UNSYNCED = "any_unsynced";
1742
1743        /**
1744         * Read-only count of {@link Contacts} from a specific source that have
1745         * no {@link CommonDataKinds.GroupMembership} entries.
1746         * <p>
1747         * Type: INTEGER
1748         */
1749        public static final String UNGROUPED_COUNT = "summ_count";
1750
1751        /**
1752         * Read-only count of {@link Contacts} from a specific source that have
1753         * no {@link CommonDataKinds.GroupMembership} entries, and also have phone numbers.
1754         * <p>
1755         * Type: INTEGER
1756         */
1757        public static final String UNGROUPED_WITH_PHONES = "summ_phones";
1758    }
1759
1760    /**
1761     * Contacts-specific settings for various {@link Account}.
1762     */
1763    public static final class Settings implements SettingsColumns {
1764        /**
1765         * This utility class cannot be instantiated
1766         */
1767        private Settings() {
1768        }
1769
1770        /**
1771         * The content:// style URI for this table
1772         */
1773        public static final Uri CONTENT_URI =
1774                Uri.withAppendedPath(AUTHORITY_URI, "settings");
1775
1776        /**
1777         * The MIME-type of {@link #CONTENT_URI} providing a directory of
1778         * settings.
1779         */
1780        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/setting";
1781
1782        /**
1783         * The MIME-type of {@link #CONTENT_URI} providing a single setting.
1784         */
1785        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/setting";
1786    }
1787
1788    /**
1789     * Helper methods to display FastTrack dialogs that allow users to pivot on
1790     * a specific {@link Contacts} entry.
1791     */
1792    public static final class FastTrack {
1793        /**
1794         * Action used to trigger person pivot dialog.
1795         * @hide
1796         */
1797        public static final String ACTION_FAST_TRACK =
1798                "com.android.contacts.action.FAST_TRACK";
1799
1800        /**
1801         * Extra used to specify pivot dialog location in screen coordinates.
1802         * @hide
1803         */
1804        public static final String EXTRA_TARGET_RECT = "target_rect";
1805
1806        /**
1807         * Extra used to specify size of pivot dialog.
1808         * @hide
1809         */
1810        public static final String EXTRA_MODE = "mode";
1811
1812        /**
1813         * Extra used to indicate a list of specific MIME-types to exclude and
1814         * not display. Stored as a {@link String} array.
1815         * @hide
1816         */
1817        public static final String EXTRA_EXCLUDE_MIMES = "exclude_mimes";
1818
1819        /**
1820         * Small FastTrack mode, usually presented with minimal actions.
1821         */
1822        public static final int MODE_SMALL = 1;
1823
1824        /**
1825         * Medium FastTrack mode, includes actions and light summary describing
1826         * the {@link Contacts} entry being shown. This may include social
1827         * status and presence details.
1828         */
1829        public static final int MODE_MEDIUM = 2;
1830
1831        /**
1832         * Large FastTrack mode, includes actions and larger, card-like summary
1833         * of the {@link Contacts} entry being shown. This may include detailed
1834         * information, such as a photo.
1835         */
1836        public static final int MODE_LARGE = 3;
1837
1838        /**
1839         * Trigger a dialog that lists the various methods of interacting with
1840         * the requested {@link Contacts} entry. This may be based on available
1841         * {@link Data} rows under that contact, and may also include social
1842         * status and presence details.
1843         *
1844         * @param context The parent {@link Context} that may be used as the
1845         *            parent for this dialog.
1846         * @param target Specific {@link View} from your layout that this dialog
1847         *            should be centered around. In particular, if the dialog
1848         *            has a "callout" arrow, it will be pointed and centered
1849         *            around this {@link View}.
1850         * @param lookupUri A {@link Contacts#CONTENT_LOOKUP_URI} style
1851         *            {@link Uri} that describes a specific contact to feature
1852         *            in this dialog.
1853         * @param mode Any of {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or
1854         *            {@link #MODE_LARGE}, indicating the desired dialog size,
1855         *            when supported.
1856         * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types
1857         *            to exclude when showing this dialog. For example, when
1858         *            already viewing the contact details card, this can be used
1859         *            to omit the details entry from the dialog.
1860         */
1861        public static void showFastTrack(Context context, View target, Uri lookupUri, int mode,
1862                String[] excludeMimes) {
1863            // Find location and bounds of target view
1864            final int[] location = new int[2];
1865            target.getLocationOnScreen(location);
1866
1867            final Rect rect = new Rect();
1868            rect.left = location[0];
1869            rect.top = location[1];
1870            rect.right = rect.left + target.getWidth();
1871            rect.bottom = rect.top + target.getHeight();
1872
1873            // Trigger with obtained rectangle
1874            showFastTrack(context, rect, lookupUri, mode, excludeMimes);
1875        }
1876
1877        /**
1878         * Trigger a dialog that lists the various methods of interacting with
1879         * the requested {@link Contacts} entry. This may be based on available
1880         * {@link Data} rows under that contact, and may also include social
1881         * status and presence details.
1882         *
1883         * @param context The parent {@link Context} that may be used as the
1884         *            parent for this dialog.
1885         * @param target Specific {@link Rect} that this dialog should be
1886         *            centered around, in screen coordinates. In particular, if
1887         *            the dialog has a "callout" arrow, it will be pointed and
1888         *            centered around this {@link Rect}.
1889         * @param lookupUri A {@link Contacts#CONTENT_LOOKUP_URI} style
1890         *            {@link Uri} that describes a specific contact to feature
1891         *            in this dialog.
1892         * @param mode Any of {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or
1893         *            {@link #MODE_LARGE}, indicating the desired dialog size,
1894         *            when supported.
1895         * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types
1896         *            to exclude when showing this dialog. For example, when
1897         *            already viewing the contact details card, this can be used
1898         *            to omit the details entry from the dialog.
1899         */
1900        public static void showFastTrack(Context context, Rect target, Uri lookupUri, int mode,
1901                String[] excludeMimes) {
1902            // Launch pivot dialog through intent for now
1903            final Intent intent = new Intent(ACTION_FAST_TRACK);
1904            intent.setData(lookupUri);
1905            intent.putExtra(EXTRA_TARGET_RECT, target);
1906            intent.putExtra(EXTRA_MODE, mode);
1907            intent.putExtra(EXTRA_EXCLUDE_MIMES, excludeMimes);
1908            context.startActivity(intent);
1909        }
1910    }
1911
1912    /**
1913     * Contains helper classes used to create or manage {@link android.content.Intent Intents}
1914     * that involve contacts.
1915     */
1916    public static final class Intents {
1917        /**
1918         * This is the intent that is fired when a search suggestion is clicked on.
1919         */
1920        public static final String SEARCH_SUGGESTION_CLICKED =
1921                "android.provider.Contacts.SEARCH_SUGGESTION_CLICKED";
1922
1923        /**
1924         * This is the intent that is fired when a search suggestion for dialing a number
1925         * is clicked on.
1926         */
1927        public static final String SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED =
1928                "android.provider.Contacts.SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED";
1929
1930        /**
1931         * This is the intent that is fired when a search suggestion for creating a contact
1932         * is clicked on.
1933         */
1934        public static final String SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED =
1935                "android.provider.Contacts.SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED";
1936
1937        /**
1938         * Starts an Activity that lets the user pick a contact to attach an image to.
1939         * After picking the contact it launches the image cropper in face detection mode.
1940         */
1941        public static final String ATTACH_IMAGE =
1942                "com.android.contacts.action.ATTACH_IMAGE";
1943
1944        /**
1945         * Takes as input a data URI with a mailto: or tel: scheme. If a single
1946         * contact exists with the given data it will be shown. If no contact
1947         * exists, a dialog will ask the user if they want to create a new
1948         * contact with the provided details filled in. If multiple contacts
1949         * share the data the user will be prompted to pick which contact they
1950         * want to view.
1951         * <p>
1952         * For <code>mailto:</code> URIs, the scheme specific portion must be a
1953         * raw email address, such as one built using
1954         * {@link Uri#fromParts(String, String, String)}.
1955         * <p>
1956         * For <code>tel:</code> URIs, the scheme specific portion is compared
1957         * to existing numbers using the standard caller ID lookup algorithm.
1958         * The number must be properly encoded, for example using
1959         * {@link Uri#fromParts(String, String, String)}.
1960         * <p>
1961         * Any extras from the {@link Insert} class will be passed along to the
1962         * create activity if there are no contacts to show.
1963         * <p>
1964         * Passing true for the {@link #EXTRA_FORCE_CREATE} extra will skip
1965         * prompting the user when the contact doesn't exist.
1966         */
1967        public static final String SHOW_OR_CREATE_CONTACT =
1968                "com.android.contacts.action.SHOW_OR_CREATE_CONTACT";
1969
1970        /**
1971         * Used with {@link #SHOW_OR_CREATE_CONTACT} to force creating a new
1972         * contact if no matching contact found. Otherwise, default behavior is
1973         * to prompt user with dialog before creating.
1974         * <p>
1975         * Type: BOOLEAN
1976         */
1977        public static final String EXTRA_FORCE_CREATE =
1978                "com.android.contacts.action.FORCE_CREATE";
1979
1980        /**
1981         * Used with {@link #SHOW_OR_CREATE_CONTACT} to specify an exact
1982         * description to be shown when prompting user about creating a new
1983         * contact.
1984         * <p>
1985         * Type: STRING
1986         */
1987        public static final String EXTRA_CREATE_DESCRIPTION =
1988            "com.android.contacts.action.CREATE_DESCRIPTION";
1989
1990        /**
1991         * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to specify a
1992         * dialog location using screen coordinates. When not specified, the
1993         * dialog will be centered.
1994         */
1995        @Deprecated
1996        public static final String EXTRA_TARGET_RECT = "target_rect";
1997
1998        /**
1999         * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to specify a
2000         * desired dialog style, usually a variation on size. One of
2001         * {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or {@link #MODE_LARGE}.
2002         */
2003        @Deprecated
2004        public static final String EXTRA_MODE = "mode";
2005
2006        /**
2007         * Value for {@link #EXTRA_MODE} to show a small-sized dialog.
2008         */
2009        @Deprecated
2010        public static final int MODE_SMALL = 1;
2011
2012        /**
2013         * Value for {@link #EXTRA_MODE} to show a medium-sized dialog.
2014         */
2015        @Deprecated
2016        public static final int MODE_MEDIUM = 2;
2017
2018        /**
2019         * Value for {@link #EXTRA_MODE} to show a large-sized dialog.
2020         */
2021        @Deprecated
2022        public static final int MODE_LARGE = 3;
2023
2024        /**
2025         * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to indicate
2026         * a list of specific MIME-types to exclude and not display. Stored as a
2027         * {@link String} array.
2028         */
2029        @Deprecated
2030        public static final String EXTRA_EXCLUDE_MIMES = "exclude_mimes";
2031
2032        /**
2033         * Intents related to the Contacts app UI.
2034         */
2035        public static final class UI {
2036            /**
2037             * The action for the default contacts list tab.
2038             */
2039            public static final String LIST_DEFAULT =
2040                    "com.android.contacts.action.LIST_DEFAULT";
2041
2042            /**
2043             * The action for the contacts list tab.
2044             */
2045            public static final String LIST_GROUP_ACTION =
2046                    "com.android.contacts.action.LIST_GROUP";
2047
2048            /**
2049             * When in LIST_GROUP_ACTION mode, this is the group to display.
2050             */
2051            public static final String GROUP_NAME_EXTRA_KEY = "com.android.contacts.extra.GROUP";
2052
2053            /**
2054             * The action for the all contacts list tab.
2055             */
2056            public static final String LIST_ALL_CONTACTS_ACTION =
2057                    "com.android.contacts.action.LIST_ALL_CONTACTS";
2058
2059            /**
2060             * The action for the contacts with phone numbers list tab.
2061             */
2062            public static final String LIST_CONTACTS_WITH_PHONES_ACTION =
2063                    "com.android.contacts.action.LIST_CONTACTS_WITH_PHONES";
2064
2065            /**
2066             * The action for the starred contacts list tab.
2067             */
2068            public static final String LIST_STARRED_ACTION =
2069                    "com.android.contacts.action.LIST_STARRED";
2070
2071            /**
2072             * The action for the frequent contacts list tab.
2073             */
2074            public static final String LIST_FREQUENT_ACTION =
2075                    "com.android.contacts.action.LIST_FREQUENT";
2076
2077            /**
2078             * The action for the "strequent" contacts list tab. It first lists the starred
2079             * contacts in alphabetical order and then the frequent contacts in descending
2080             * order of the number of times they have been contacted.
2081             */
2082            public static final String LIST_STREQUENT_ACTION =
2083                    "com.android.contacts.action.LIST_STREQUENT";
2084
2085            /**
2086             * A key for to be used as an intent extra to set the activity
2087             * title to a custom String value.
2088             */
2089            public static final String TITLE_EXTRA_KEY =
2090                "com.android.contacts.extra.TITLE_EXTRA";
2091
2092            /**
2093             * Activity Action: Display a filtered list of contacts
2094             * <p>
2095             * Input: Extra field {@link #FILTER_TEXT_EXTRA_KEY} is the text to use for
2096             * filtering
2097             * <p>
2098             * Output: Nothing.
2099             */
2100            public static final String FILTER_CONTACTS_ACTION =
2101                "com.android.contacts.action.FILTER_CONTACTS";
2102
2103            /**
2104             * Used as an int extra field in {@link #FILTER_CONTACTS_ACTION}
2105             * intents to supply the text on which to filter.
2106             */
2107            public static final String FILTER_TEXT_EXTRA_KEY =
2108                "com.android.contacts.extra.FILTER_TEXT";
2109        }
2110
2111        /**
2112         * Convenience class that contains string constants used
2113         * to create contact {@link android.content.Intent Intents}.
2114         */
2115        public static final class Insert {
2116            /** The action code to use when adding a contact */
2117            public static final String ACTION = Intent.ACTION_INSERT;
2118
2119            /**
2120             * If present, forces a bypass of quick insert mode.
2121             */
2122            public static final String FULL_MODE = "full_mode";
2123
2124            /**
2125             * The extra field for the contact name.
2126             * <P>Type: String</P>
2127             */
2128            public static final String NAME = "name";
2129
2130            // TODO add structured name values here.
2131
2132            /**
2133             * The extra field for the contact phonetic name.
2134             * <P>Type: String</P>
2135             */
2136            public static final String PHONETIC_NAME = "phonetic_name";
2137
2138            /**
2139             * The extra field for the contact company.
2140             * <P>Type: String</P>
2141             */
2142            public static final String COMPANY = "company";
2143
2144            /**
2145             * The extra field for the contact job title.
2146             * <P>Type: String</P>
2147             */
2148            public static final String JOB_TITLE = "job_title";
2149
2150            /**
2151             * The extra field for the contact notes.
2152             * <P>Type: String</P>
2153             */
2154            public static final String NOTES = "notes";
2155
2156            /**
2157             * The extra field for the contact phone number.
2158             * <P>Type: String</P>
2159             */
2160            public static final String PHONE = "phone";
2161
2162            /**
2163             * The extra field for the contact phone number type.
2164             * <P>Type: Either an integer value from
2165             * {@link android.provider.Contacts.PhonesColumns PhonesColumns},
2166             *  or a string specifying a custom label.</P>
2167             */
2168            public static final String PHONE_TYPE = "phone_type";
2169
2170            /**
2171             * The extra field for the phone isprimary flag.
2172             * <P>Type: boolean</P>
2173             */
2174            public static final String PHONE_ISPRIMARY = "phone_isprimary";
2175
2176            /**
2177             * The extra field for an optional second contact phone number.
2178             * <P>Type: String</P>
2179             */
2180            public static final String SECONDARY_PHONE = "secondary_phone";
2181
2182            /**
2183             * The extra field for an optional second contact phone number type.
2184             * <P>Type: Either an integer value from
2185             * {@link android.provider.Contacts.PhonesColumns PhonesColumns},
2186             *  or a string specifying a custom label.</P>
2187             */
2188            public static final String SECONDARY_PHONE_TYPE = "secondary_phone_type";
2189
2190            /**
2191             * The extra field for an optional third contact phone number.
2192             * <P>Type: String</P>
2193             */
2194            public static final String TERTIARY_PHONE = "tertiary_phone";
2195
2196            /**
2197             * The extra field for an optional third contact phone number type.
2198             * <P>Type: Either an integer value from
2199             * {@link android.provider.Contacts.PhonesColumns PhonesColumns},
2200             *  or a string specifying a custom label.</P>
2201             */
2202            public static final String TERTIARY_PHONE_TYPE = "tertiary_phone_type";
2203
2204            /**
2205             * The extra field for the contact email address.
2206             * <P>Type: String</P>
2207             */
2208            public static final String EMAIL = "email";
2209
2210            /**
2211             * The extra field for the contact email type.
2212             * <P>Type: Either an integer value from
2213             * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns}
2214             *  or a string specifying a custom label.</P>
2215             */
2216            public static final String EMAIL_TYPE = "email_type";
2217
2218            /**
2219             * The extra field for the email isprimary flag.
2220             * <P>Type: boolean</P>
2221             */
2222            public static final String EMAIL_ISPRIMARY = "email_isprimary";
2223
2224            /**
2225             * The extra field for an optional second contact email address.
2226             * <P>Type: String</P>
2227             */
2228            public static final String SECONDARY_EMAIL = "secondary_email";
2229
2230            /**
2231             * The extra field for an optional second contact email type.
2232             * <P>Type: Either an integer value from
2233             * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns}
2234             *  or a string specifying a custom label.</P>
2235             */
2236            public static final String SECONDARY_EMAIL_TYPE = "secondary_email_type";
2237
2238            /**
2239             * The extra field for an optional third contact email address.
2240             * <P>Type: String</P>
2241             */
2242            public static final String TERTIARY_EMAIL = "tertiary_email";
2243
2244            /**
2245             * The extra field for an optional third contact email type.
2246             * <P>Type: Either an integer value from
2247             * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns}
2248             *  or a string specifying a custom label.</P>
2249             */
2250            public static final String TERTIARY_EMAIL_TYPE = "tertiary_email_type";
2251
2252            /**
2253             * The extra field for the contact postal address.
2254             * <P>Type: String</P>
2255             */
2256            public static final String POSTAL = "postal";
2257
2258            /**
2259             * The extra field for the contact postal address type.
2260             * <P>Type: Either an integer value from
2261             * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns}
2262             *  or a string specifying a custom label.</P>
2263             */
2264            public static final String POSTAL_TYPE = "postal_type";
2265
2266            /**
2267             * The extra field for the postal isprimary flag.
2268             * <P>Type: boolean</P>
2269             */
2270            public static final String POSTAL_ISPRIMARY = "postal_isprimary";
2271
2272            /**
2273             * The extra field for an IM handle.
2274             * <P>Type: String</P>
2275             */
2276            public static final String IM_HANDLE = "im_handle";
2277
2278            /**
2279             * The extra field for the IM protocol
2280             * <P>Type: the result of {@link CommonDataKinds.Im#encodePredefinedImProtocol(int)}
2281             * or {@link CommonDataKinds.Im#encodeCustomImProtocol(String)}.</P>
2282             */
2283            public static final String IM_PROTOCOL = "im_protocol";
2284
2285            /**
2286             * The extra field for the IM isprimary flag.
2287             * <P>Type: boolean</P>
2288             */
2289            public static final String IM_ISPRIMARY = "im_isprimary";
2290        }
2291    }
2292
2293}
2294