ContactsContract.java revision 5f123bdcde61b9fdcd58952882c621c34a727e10 
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.graphics.BitmapFactory;
20import android.net.Uri;
21
22/**
23 * The contract between the contacts provider and applications. Contains definitions
24 * for the supported URIs and columns.
25 *
26 * @hide
27 */
28public final class ContactsContract {
29    /** The authority for the contacts provider */
30    public static final String AUTHORITY = "com.android.contacts";
31    /** A content:// style uri to the authority for the contacts provider */
32    public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY);
33
34    public interface AggregatesColumns {
35        /**
36         * The display name for the contact.
37         * <P>Type: TEXT</P>
38         */
39        public static final String DISPLAY_NAME = "display_name";
40
41        /**
42         * The number of times a person has been contacted
43         * <P>Type: INTEGER</P>
44         */
45        public static final String TIMES_CONTACTED = "times_contacted";
46
47        /**
48         * The last time a person was contacted.
49         * <P>Type: INTEGER</P>
50         */
51        public static final String LAST_TIME_CONTACTED = "last_time_contacted";
52
53        /**
54         * Is the contact starred?
55         * <P>Type: INTEGER (boolean)</P>
56         */
57        public static final String STARRED = "starred";
58
59        /**
60         * Reference to the row in the data table holding the primary phone number.
61         * <P>Type: INTEGER REFERENCES data(_id)</P>
62         */
63        public static final String PRIMARY_PHONE_ID = "primary_phone_id";
64
65        /**
66         * Reference to the row in the data table holding the primary email address.
67         * <P>Type: INTEGER REFERENCES data(_id)</P>
68         */
69        public static final String PRIMARY_EMAIL_ID = "primary_email_id";
70
71        /**
72         * Reference to the row in the data table holding the photo.
73         * <P>Type: INTEGER REFERENCES data(_id)</P>
74         */
75        public static final String PHOTO_ID = "photo_id";
76
77        /**
78         * Reference to a row containing custom ringtone and send to voicemail information.
79         * <P>Type: INTEGER REFERENCES data(_id)</P>
80         */
81        public static final String CUSTOM_RINGTONE_ID = "custom_ringtone_id";
82    }
83
84    /**
85     * Constants for the aggregates table, which contains a record per group
86     * of contact representing the same person.
87     */
88    public static final class Aggregates implements BaseColumns, AggregatesColumns {
89        /**
90         * This utility class cannot be instantiated
91         */
92        private Aggregates()  {}
93
94        /**
95         * The content:// style URI for this table
96         */
97        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "aggregates");
98
99        /**
100         * The MIME type of {@link #CONTENT_URI} providing a directory of
101         * people.
102         */
103        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/person_aggregate";
104
105        /**
106         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
107         * person.
108         */
109        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/person_aggregate";
110
111        /**
112         * A sub-directory of a single contact aggregate that contains all of their
113         * {@link Data} rows.
114         */
115        public static final class Data implements BaseColumns, DataColumns {
116            /**
117             * no public constructor since this is a utility class
118             */
119            private Data() {}
120
121            /**
122             * The directory twig for this sub-table
123             */
124            public static final String CONTENT_DIRECTORY = "data";
125        }
126    }
127
128
129    /**
130     * Constants for the contacts table, which contains the base contact information.
131     */
132    public static final class Contacts implements BaseColumns {
133        /**
134         * This utility class cannot be instantiated
135         */
136        private Contacts()  {}
137
138        /**
139         * A reference to the {@link Aggregates#_ID} that this data belongs to.
140         */
141        public static final String AGGREGATE_ID = "aggregate_id";
142
143        /**
144         * The content:// style URI for this table
145         */
146        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "contacts");
147
148        /**
149         * The content:// style URL for filtering people by email address. The
150         * filter argument should be passed as an additional path segment after
151         * this URI.
152         *
153         * @hide
154         */
155        public static final Uri CONTENT_FILTER_EMAIL_URI = Uri.withAppendedPath(CONTENT_URI, "filter_email");
156
157        /**
158         * The MIME type of {@link #CONTENT_URI} providing a directory of
159         * people.
160         */
161        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/person";
162
163        /**
164         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
165         * person.
166         */
167        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/person";
168
169        /**
170         * A sub-directory of a single contact that contains all of their {@link Data} rows.
171         * To access this directory append
172         */
173        public static final class Data implements BaseColumns, DataColumns {
174            /**
175             * no public constructor since this is a utility class
176             */
177            private Data() {}
178
179            /**
180             * The directory twig for this sub-table
181             */
182            public static final String CONTENT_DIRECTORY = "data";
183        }
184    }
185
186    private interface DataColumns {
187        /**
188         * The package name that defines this type of data.
189         */
190        public static final String PACKAGE = "package";
191
192        /**
193         * The mime-type of the item represented by this row.
194         */
195        public static final String MIMETYPE = "mimetype";
196
197        /**
198         * A reference to the {@link android.provider.ContactsContract.Contacts#_ID}
199         * that this data belongs to.
200         */
201        public static final String CONTACT_ID = "contact_id";
202
203        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
204        public static final String DATA1 = "data1";
205        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
206        public static final String DATA2 = "data2";
207        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
208        public static final String DATA3 = "data3";
209        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
210        public static final String DATA4 = "data4";
211        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
212        public static final String DATA5 = "data5";
213        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
214        public static final String DATA6 = "data6";
215        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
216        public static final String DATA7 = "data7";
217        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
218        public static final String DATA8 = "data8";
219        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
220        public static final String DATA9 = "data9";
221        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
222        public static final String DATA10 = "data10";
223    }
224
225    /**
226     * Constants for the data table, which contains data points tied to a contact.
227     * For example, a phone number or email address. Each row in this table contains a type
228     * definition and some generic columns. Each data type can define the meaning for each of
229     * the generic columns.
230     */
231    public static final class Data implements BaseColumns, DataColumns {
232        /**
233         * This utility class cannot be instantiated
234         */
235        private Data() {}
236
237        /**
238         * The content:// style URI for this table
239         */
240        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data");
241
242        /**
243         * The MIME type of {@link #CONTENT_URI} providing a directory of data.
244         */
245        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data";
246    }
247
248    /**
249     * A table that represents the result of looking up a phone number, for example for caller ID.
250     * The table joins that data row for the phone number with the contact that owns the number.
251     * To perform a lookup you must append the number you want to find to {@link #CONTENT_URI}.
252     */
253    public static final class PhoneLookup implements BaseColumns, DataColumns, AggregatesColumns {
254        /**
255         * This utility class cannot be instantiated
256         */
257        private PhoneLookup() {}
258
259        /**
260         * The content:// style URI for this table. Append the phone number you want to lookup
261         * to this URI and query it to perform a lookup. For example:
262         *
263         * {@code
264         * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_URI, phoneNumber);
265         * }
266         */
267        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "phone_lookup");
268    }
269
270    /**
271     * Container for definitions of common data types stored in the {@link Data} table.
272     */
273    public static final class CommonDataKinds {
274        /**
275         * The {@link Data#PACKAGE} value for common data that should be shown
276         * using a default style.
277         */
278        public static final String PACKAGE_COMMON = "common";
279
280        /**
281         * Columns common across the specific types.
282         */
283        private interface BaseCommonColumns {
284            /**
285             * The package name that defines this type of data.
286             */
287            public static final String PACKAGE = "package";
288
289            /**
290             * The mime-type of the item represented by this row.
291             */
292            public static final String MIMETYPE = "mimetype";
293
294            /**
295             * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} that this
296             * data belongs to.
297             */
298            public static final String CONTACT_ID = "contact_id";
299        }
300
301        /**
302         * Columns common across the specific types.
303         */
304        private interface CommonColumns {
305            /**
306             * The type of data, for example Home or Work.
307             * <P>Type: INTEGER</P>
308             */
309            public static final String TYPE = "data1";
310
311            /**
312             * The user defined label for the the contact method.
313             * <P>Type: TEXT</P>
314             */
315            public static final String LABEL = "data2";
316
317            /**
318             * The data for the contact method.
319             * <P>Type: TEXT</P>
320             */
321            public static final String DATA = "data3";
322
323            /**
324             * Whether this is the primary entry of its kind for the contact it belongs to
325             * <P>Type: INTEGER (if set, non-0 means true)</P>
326             */
327            public static final String ISPRIMARY = "data4";
328        }
329
330        /**
331         * Parts of the name.
332         */
333        public static final class StructuredName {
334            private StructuredName() {}
335
336            /** Mime-type used when storing this in data table. */
337            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/name";
338
339            /**
340             * The contact's honorific prefix, e.g. "Sir"
341             */
342            public static final String PREFIX = "data1";
343
344            /**
345             * The given name for the contact.
346             * <P>Type: TEXT</P>
347             */
348            public static final String GIVEN_NAME = "data2";
349
350            /**
351             * The contact's middle name
352             * <P>Type: TEXT</P>
353             */
354            public static final String MIDDLE_NAME = "data3";
355
356            /**
357             * The family name for the contact.
358             * <P>Type: TEXT</P>
359             */
360            public static final String FAMILY_NAME = "data4";
361
362            /**
363             * The contact's honorific suffix, e.g. "Jr"
364             */
365            public static final String SUFFIX = "data5";
366
367            /**
368             * The phonetic version of the given name for the contact.
369             * <P>Type: TEXT</P>
370             */
371            public static final String PHONETIC_GIVEN_NAME = "data6";
372
373            /**
374             * The phonetic version of the additional name for the contact.
375             * <P>Type: TEXT</P>
376             */
377            public static final String PHONETIC_MIDDLE_NAME = "data7";
378
379            /**
380             * The phonetic version of the family name for the contact.
381             * <P>Type: TEXT</P>
382             */
383            public static final String PHONETIC_FAMILY_NAME = "data8";
384
385            /**
386             * The name that should be used to display the contact.
387             * <P>Type: TEXT</P>
388             */
389            public static final String DISPLAY_NAME = "data9";
390        }
391
392        /**
393         * A nickname.
394         */
395        public static final class Nickname {
396            private Nickname() {}
397
398            /** Mime-type used when storing this in data table. */
399            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/nickname";
400
401            /**
402             * The type of data, for example Home or Work.
403             * <P>Type: INTEGER</P>
404             */
405            public static final String TYPE = "data1";
406
407            public static final int TYPE_CUSTOM = 1;
408            public static final int TYPE_DEFAULT = 2;
409            public static final int TYPE_OTHER_NAME = 3;
410            public static final int TYPE_MAINDEN_NAME = 4;
411            public static final int TYPE_SHORT_NAME = 5;
412            public static final int TYPE_INITIALS = 6;
413
414            /**
415             * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}.
416             * <P>Type: TEXT</P>
417             */
418            public static final String LABEL = "data2";
419
420            /**
421             * The name itself
422             */
423            public static final String NAME = "data3";
424        }
425
426        /**
427         * Common data definition for telephone numbers.
428         */
429        public static final class Phone implements BaseCommonColumns, CommonColumns {
430            private Phone() {}
431
432            /** Mime-type used when storing this in data table. */
433            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone";
434
435            public static final int TYPE_CUSTOM = 0;
436            public static final int TYPE_HOME = 1;
437            public static final int TYPE_MOBILE = 2;
438            public static final int TYPE_WORK = 3;
439            public static final int TYPE_FAX_WORK = 4;
440            public static final int TYPE_FAX_HOME = 5;
441            public static final int TYPE_PAGER = 6;
442            public static final int TYPE_OTHER = 7;
443
444            /**
445             * The phone number as the user entered it.
446             * <P>Type: TEXT</P>
447             */
448            public static final String NUMBER = "data3";
449
450        }
451
452        /**
453         * Common data definition for email addresses.
454         */
455        public static final class Email implements BaseCommonColumns, CommonColumns {
456            private Email() {}
457
458            /** Mime-type used when storing this in data table. */
459            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/email";
460
461            public static final int TYPE_CUSTOM = 0;
462            public static final int TYPE_HOME = 1;
463            public static final int TYPE_WORK = 2;
464            public static final int TYPE_OTHER = 3;
465
466        }
467
468        /**
469         * Common data definition for postal addresses.
470         */
471        public static final class Postal implements BaseCommonColumns, CommonColumns {
472            private Postal() {}
473
474            /** Mime-type used when storing this in data table. */
475            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/postal-address";
476
477            public static final int TYPE_CUSTOM = 0;
478            public static final int TYPE_HOME = 1;
479            public static final int TYPE_WORK = 2;
480            public static final int TYPE_OTHER = 3;
481        }
482
483       /**
484        * Common data definition for IM addresses.
485        */
486        public static final class Im implements BaseCommonColumns, CommonColumns {
487            private Im() {}
488
489            /** Mime-type used when storing this in data table. */
490            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im";
491
492            public static final int TYPE_CUSTOM = 0;
493            public static final int TYPE_HOME = 1;
494            public static final int TYPE_WORK = 2;
495            public static final int TYPE_OTHER = 3;
496
497            public static final String PROTOCOL = "data5";
498
499            /**
500             * The predefined IM protocol types. The protocol can either be non-present, one
501             * of these types, or a free-form string. These cases are encoded in the PROTOCOL
502             * column as:
503             *  - null
504             *  - pre:<an integer, one of the protocols below>
505             *  - custom:<a string>
506             */
507            public static final int PROTOCOL_AIM = 0;
508            public static final int PROTOCOL_MSN = 1;
509            public static final int PROTOCOL_YAHOO = 2;
510            public static final int PROTOCOL_SKYPE = 3;
511            public static final int PROTOCOL_QQ = 4;
512            public static final int PROTOCOL_GOOGLE_TALK = 5;
513            public static final int PROTOCOL_ICQ = 6;
514            public static final int PROTOCOL_JABBER = 7;
515        }
516
517        /**
518         * Common data definition for organizations.
519         */
520        public static final class Organization implements BaseCommonColumns {
521            private Organization() {}
522
523            /** Mime-type used when storing this in data table. */
524            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/organization";
525
526            /**
527             * The type of data, for example Home or Work.
528             * <P>Type: INTEGER</P>
529             */
530            public static final String TYPE = "data1";
531
532            public static final int TYPE_CUSTOM = 0;
533            public static final int TYPE_HOME = 1;
534            public static final int TYPE_WORK = 2;
535            public static final int TYPE_OTHER = 3;
536
537            /**
538             * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}.
539             * <P>Type: TEXT</P>
540             */
541            public static final String LABEL = "data2";
542
543            /**
544             * The company as the user entered it.
545             * <P>Type: TEXT</P>
546             */
547            public static final String COMPANY = "data3";
548
549            /**
550             * The position title at this company as the user entered it.
551             * <P>Type: TEXT</P>
552             */
553            public static final String TITLE = "data4";
554
555            /**
556             * Whether this is the primary organization
557             * <P>Type: INTEGER (if set, non-0 means true)</P>
558             */
559            public static final String ISPRIMARY = "data5";
560
561        }
562
563        /**
564         * Photo of the contact.
565         */
566        public static final class Photo implements BaseCommonColumns {
567            private Photo() {}
568
569            /** Mime-type used when storing this in data table. */
570            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/photo";
571
572            /**
573             * Thumbnail photo of the contact. This is the raw bytes of an image
574             * that could be inflated using {@link BitmapFactory}.
575             * <p>
576             * Type: BLOB
577             */
578            public static final String PHOTO = "data1";
579        }
580
581        /**
582         * Notes about the contact.
583         */
584        public static final class Note implements BaseCommonColumns {
585            private Note() {}
586
587            /** Mime-type used when storing this in data table. */
588            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/note";
589
590            /**
591             * The note text.
592             * <P>Type: TEXT</P>
593             */
594            public static final String NOTE = "data1";
595        }
596
597        public static final class CustomRingtone implements BaseCommonColumns {
598            private CustomRingtone() {}
599
600            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/custom_ringtone";
601
602            /**
603             * Whether to send the number to voicemail.
604             * <P>Type: INTEGER (if set, non-0 means true)</P>
605             */
606            public static final String SEND_TO_VOICEMAIL = "data1";
607
608            /**
609             * The ringtone uri.
610             * <P>Type: TEXT</P>
611             */
612            public static final String RINGTONE_URI = "data2";
613        }
614    }
615
616}
617