ContactsContract.java revision e85a3e5458be8ff1e47b5a04b4492eb4d284236c
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.app.Activity;
21import android.app.admin.DevicePolicyManager;
22import android.content.ActivityNotFoundException;
23import android.content.ContentProviderClient;
24import android.content.ContentProviderOperation;
25import android.content.ContentResolver;
26import android.content.ContentUris;
27import android.content.ContentValues;
28import android.content.Context;
29import android.content.ContextWrapper;
30import android.content.CursorEntityIterator;
31import android.content.Entity;
32import android.content.EntityIterator;
33import android.content.Intent;
34import android.content.res.AssetFileDescriptor;
35import android.content.res.Resources;
36import android.database.Cursor;
37import android.database.DatabaseUtils;
38import android.graphics.Rect;
39import android.net.Uri;
40import android.os.RemoteException;
41import android.text.TextUtils;
42import android.util.DisplayMetrics;
43import android.util.Pair;
44import android.view.View;
45import android.widget.Toast;
46
47import java.io.ByteArrayInputStream;
48import java.io.IOException;
49import java.io.InputStream;
50import java.util.ArrayList;
51
52/**
53 * <p>
54 * The contract between the contacts provider and applications. Contains
55 * definitions for the supported URIs and columns. These APIs supersede
56 * {@link Contacts}.
57 * </p>
58 * <h3>Overview</h3>
59 * <p>
60 * ContactsContract defines an extensible database of contact-related
61 * information. Contact information is stored in a three-tier data model:
62 * </p>
63 * <ul>
64 * <li>
65 * A row in the {@link Data} table can store any kind of personal data, such
66 * as a phone number or email addresses.  The set of data kinds that can be
67 * stored in this table is open-ended. There is a predefined set of common
68 * kinds, but any application can add its own data kinds.
69 * </li>
70 * <li>
71 * A row in the {@link RawContacts} table represents a set of data describing a
72 * person and associated with a single account (for example, one of the user's
73 * Gmail accounts).
74 * </li>
75 * <li>
76 * A row in the {@link Contacts} table represents an aggregate of one or more
77 * RawContacts presumably describing the same person.  When data in or associated with
78 * the RawContacts table is changed, the affected aggregate contacts are updated as
79 * necessary.
80 * </li>
81 * </ul>
82 * <p>
83 * Other tables include:
84 * </p>
85 * <ul>
86 * <li>
87 * {@link Groups}, which contains information about raw contact groups
88 * such as Gmail contact groups.  The
89 * current API does not support the notion of groups spanning multiple accounts.
90 * </li>
91 * <li>
92 * {@link StatusUpdates}, which contains social status updates including IM
93 * availability.
94 * </li>
95 * <li>
96 * {@link AggregationExceptions}, which is used for manual aggregation and
97 * disaggregation of raw contacts
98 * </li>
99 * <li>
100 * {@link Settings}, which contains visibility and sync settings for accounts
101 * and groups.
102 * </li>
103 * <li>
104 * {@link SyncState}, which contains free-form data maintained on behalf of sync
105 * adapters
106 * </li>
107 * <li>
108 * {@link PhoneLookup}, which is used for quick caller-ID lookup</li>
109 * </ul>
110 */
111@SuppressWarnings("unused")
112public final class ContactsContract {
113    /** The authority for the contacts provider */
114    public static final String AUTHORITY = "com.android.contacts";
115    /** A content:// style uri to the authority for the contacts provider */
116    public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY);
117
118    /**
119     * An optional URI parameter for insert, update, or delete queries
120     * that allows the caller
121     * to specify that it is a sync adapter. The default value is false. If true
122     * {@link RawContacts#DIRTY} is not automatically set and the
123     * "syncToNetwork" parameter is set to false when calling
124     * {@link
125     * ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver, boolean)}.
126     * This prevents an unnecessary extra synchronization, see the discussion of
127     * the delete operation in {@link RawContacts}.
128     */
129    public static final String CALLER_IS_SYNCADAPTER = "caller_is_syncadapter";
130
131    /**
132     * Query parameter that should be used by the client to access a specific
133     * {@link Directory}. The parameter value should be the _ID of the corresponding
134     * directory, e.g.
135     * {@code content://com.android.contacts/data/emails/filter/acme?directory=3}
136     */
137    public static final String DIRECTORY_PARAM_KEY = "directory";
138
139    /**
140     * A query parameter that limits the number of results returned. The
141     * parameter value should be an integer.
142     */
143    public static final String LIMIT_PARAM_KEY = "limit";
144
145    /**
146     * A query parameter specifing a primary account. This parameter should be used with
147     * {@link #PRIMARY_ACCOUNT_TYPE}. The contacts provider handling a query may rely on
148     * this information to optimize its query results.
149     *
150     * For example, in an email composition screen, its implementation can specify an account when
151     * obtaining possible recipients, letting the provider know which account is selected during
152     * the composition. The provider may use the "primary account" information to optimize
153     * the search result.
154     */
155    public static final String PRIMARY_ACCOUNT_NAME = "name_for_primary_account";
156
157    /**
158     * A query parameter specifing a primary account. This parameter should be used with
159     * {@link #PRIMARY_ACCOUNT_NAME}. See the doc in {@link #PRIMARY_ACCOUNT_NAME}.
160     */
161    public static final String PRIMARY_ACCOUNT_TYPE = "type_for_primary_account";
162
163    /**
164     * A boolean parameter for {@link Contacts#CONTENT_STREQUENT_URI} and
165     * {@link Contacts#CONTENT_STREQUENT_FILTER_URI}, which requires the ContactsProvider to
166     * return only phone-related results. For example, frequently contacted person list should
167     * include persons contacted via phone (not email, sms, etc.)
168     */
169    public static final String STREQUENT_PHONE_ONLY = "strequent_phone_only";
170
171    /**
172     * A key to a boolean in the "extras" bundle of the cursor.
173     * The boolean indicates that the provider did not create a snippet and that the client asking
174     * for the snippet should do it (true means the snippeting was deferred to the client).
175     *
176     * @see SearchSnippets
177     */
178    public static final String DEFERRED_SNIPPETING = "deferred_snippeting";
179
180    /**
181     * Key to retrieve the original deferred snippeting from the cursor on the client side.
182     *
183     * @see SearchSnippets
184     * @see #DEFERRED_SNIPPETING
185     */
186    public static final String DEFERRED_SNIPPETING_QUERY = "deferred_snippeting_query";
187
188    /**
189     * A boolean parameter for {@link CommonDataKinds.Phone#CONTENT_URI Phone.CONTENT_URI},
190     * {@link CommonDataKinds.Email#CONTENT_URI Email.CONTENT_URI}, and
191     * {@link CommonDataKinds.StructuredPostal#CONTENT_URI StructuredPostal.CONTENT_URI}.
192     * This enables a content provider to remove duplicate entries in results.
193     */
194    public static final String REMOVE_DUPLICATE_ENTRIES = "remove_duplicate_entries";
195
196    /**
197     * <p>
198     * API for obtaining a pre-authorized version of a URI that normally requires special
199     * permission (beyond READ_CONTACTS) to read.  The caller obtaining the pre-authorized URI
200     * must already have the necessary permissions to access the URI; otherwise a
201     * {@link SecurityException} will be thrown. Unlike {@link Context#grantUriPermission},
202     * this can be used to grant permissions that aren't explicitly required for the URI inside
203     * AndroidManifest.xml. For example, permissions that are only required when reading URIs
204     * that refer to the user's profile.
205     * </p>
206     * <p>
207     * The authorized URI returned in the bundle contains an expiring token that allows the
208     * caller to execute the query without having the special permissions that would normally
209     * be required. The token expires in five minutes.
210     * </p>
211     * <p>
212     * This API does not access disk, and should be safe to invoke from the UI thread.
213     * </p>
214     * <p>
215     * Example usage:
216     * <pre>
217     * Uri profileUri = ContactsContract.Profile.CONTENT_VCARD_URI;
218     * Bundle uriBundle = new Bundle();
219     * uriBundle.putParcelable(ContactsContract.Authorization.KEY_URI_TO_AUTHORIZE, uri);
220     * Bundle authResponse = getContext().getContentResolver().call(
221     *         ContactsContract.AUTHORITY_URI,
222     *         ContactsContract.Authorization.AUTHORIZATION_METHOD,
223     *         null, // String arg, not used.
224     *         uriBundle);
225     * if (authResponse != null) {
226     *     Uri preauthorizedProfileUri = (Uri) authResponse.getParcelable(
227     *             ContactsContract.Authorization.KEY_AUTHORIZED_URI);
228     *     // This pre-authorized URI can be queried by a caller without READ_PROFILE
229     *     // permission.
230     * }
231     * </pre>
232     * </p>
233     *
234     * @hide
235     */
236    public static final class Authorization {
237        /**
238         * The method to invoke to create a pre-authorized URI out of the input argument.
239         */
240        public static final String AUTHORIZATION_METHOD = "authorize";
241
242        /**
243         * The key to set in the outbound Bundle with the URI that should be authorized.
244         */
245        public static final String KEY_URI_TO_AUTHORIZE = "uri_to_authorize";
246
247        /**
248         * The key to retrieve from the returned Bundle to obtain the pre-authorized URI.
249         */
250        public static final String KEY_AUTHORIZED_URI = "authorized_uri";
251    }
252
253    /**
254     * A Directory represents a contacts corpus, e.g. Local contacts,
255     * Google Apps Global Address List or Corporate Global Address List.
256     * <p>
257     * A Directory is implemented as a content provider with its unique authority and
258     * the same API as the main Contacts Provider.  However, there is no expectation that
259     * every directory provider will implement this Contract in its entirety.  If a
260     * directory provider does not have an implementation for a specific request, it
261     * should throw an UnsupportedOperationException.
262     * </p>
263     * <p>
264     * The most important use case for Directories is search.  A Directory provider is
265     * expected to support at least {@link ContactsContract.Contacts#CONTENT_FILTER_URI
266     * Contacts.CONTENT_FILTER_URI}.  If a Directory provider wants to participate
267     * in email and phone lookup functionalities, it should also implement
268     * {@link CommonDataKinds.Email#CONTENT_FILTER_URI CommonDataKinds.Email.CONTENT_FILTER_URI}
269     * and
270     * {@link CommonDataKinds.Phone#CONTENT_FILTER_URI CommonDataKinds.Phone.CONTENT_FILTER_URI}.
271     * </p>
272     * <p>
273     * A directory provider should return NULL for every projection field it does not
274     * recognize, rather than throwing an exception.  This way it will not be broken
275     * if ContactsContract is extended with new fields in the future.
276     * </p>
277     * <p>
278     * The client interacts with a directory via Contacts Provider by supplying an
279     * optional {@code directory=} query parameter.
280     * <p>
281     * <p>
282     * When the Contacts Provider receives the request, it transforms the URI and forwards
283     * the request to the corresponding directory content provider.
284     * The URI is transformed in the following fashion:
285     * <ul>
286     * <li>The URI authority is replaced with the corresponding {@link #DIRECTORY_AUTHORITY}.</li>
287     * <li>The {@code accountName=} and {@code accountType=} parameters are added or
288     * replaced using the corresponding {@link #ACCOUNT_TYPE} and {@link #ACCOUNT_NAME} values.</li>
289     * </ul>
290     * </p>
291     * <p>
292     * Clients should send directory requests to Contacts Provider and let it
293     * forward them to the respective providers rather than constructing
294     * directory provider URIs by themselves. This level of indirection allows
295     * Contacts Provider to implement additional system-level features and
296     * optimizations. Access to Contacts Provider is protected by the
297     * READ_CONTACTS permission, but access to the directory provider is protected by
298     * BIND_DIRECTORY_SEARCH. This permission was introduced at the API level 17, for previous
299     * platform versions the provider should perform the following check to make sure the call
300     * is coming from the ContactsProvider:
301     * <pre>
302     * private boolean isCallerAllowed() {
303     *   PackageManager pm = getContext().getPackageManager();
304     *   for (String packageName: pm.getPackagesForUid(Binder.getCallingUid())) {
305     *     if (packageName.equals("com.android.providers.contacts")) {
306     *       return true;
307     *     }
308     *   }
309     *   return false;
310     * }
311     * </pre>
312     * </p>
313     * <p>
314     * The Directory table is read-only and is maintained by the Contacts Provider
315     * automatically.
316     * </p>
317     * <p>It always has at least these two rows:
318     * <ul>
319     * <li>
320     * The local directory. It has {@link Directory#_ID Directory._ID} =
321     * {@link Directory#DEFAULT Directory.DEFAULT}. This directory can be used to access locally
322     * stored contacts. The same can be achieved by omitting the {@code directory=}
323     * parameter altogether.
324     * </li>
325     * <li>
326     * The local invisible contacts. The corresponding directory ID is
327     * {@link Directory#LOCAL_INVISIBLE Directory.LOCAL_INVISIBLE}.
328     * </li>
329     * </ul>
330     * </p>
331     * <p>Custom Directories are discovered by the Contacts Provider following this procedure:
332     * <ul>
333     * <li>It finds all installed content providers with meta data identifying them
334     * as directory providers in AndroidManifest.xml:
335     * <code>
336     * &lt;meta-data android:name="android.content.ContactDirectory"
337     *               android:value="true" /&gt;
338     * </code>
339     * <p>
340     * This tag should be placed inside the corresponding content provider declaration.
341     * </p>
342     * </li>
343     * <li>
344     * Then Contacts Provider sends a {@link Directory#CONTENT_URI Directory.CONTENT_URI}
345     * query to each of the directory authorities.  A directory provider must implement
346     * this query and return a list of directories.  Each directory returned by
347     * the provider must have a unique combination for the {@link #ACCOUNT_NAME} and
348     * {@link #ACCOUNT_TYPE} columns (nulls are allowed).  Since directory IDs are assigned
349     * automatically, the _ID field will not be part of the query projection.
350     * </li>
351     * <li>Contacts Provider compiles directory lists received from all directory
352     * providers into one, assigns each individual directory a globally unique ID and
353     * stores all directory records in the Directory table.
354     * </li>
355     * </ul>
356     * </p>
357     * <p>Contacts Provider automatically interrogates newly installed or replaced packages.
358     * Thus simply installing a package containing a directory provider is sufficient
359     * to have that provider registered.  A package supplying a directory provider does
360     * not have to contain launchable activities.
361     * </p>
362     * <p>
363     * Every row in the Directory table is automatically associated with the corresponding package
364     * (apk).  If the package is later uninstalled, all corresponding directory rows
365     * are automatically removed from the Contacts Provider.
366     * </p>
367     * <p>
368     * When the list of directories handled by a directory provider changes
369     * (for instance when the user adds a new Directory account), the directory provider
370     * should call {@link #notifyDirectoryChange} to notify the Contacts Provider of the change.
371     * In response, the Contacts Provider will requery the directory provider to obtain the
372     * new list of directories.
373     * </p>
374     * <p>
375     * A directory row can be optionally associated with an existing account
376     * (see {@link android.accounts.AccountManager}). If the account is later removed,
377     * the corresponding directory rows are automatically removed from the Contacts Provider.
378     * </p>
379     */
380    public static final class Directory implements BaseColumns {
381
382        /**
383         * Not instantiable.
384         */
385        private Directory() {
386        }
387
388        /**
389         * The content:// style URI for this table.  Requests to this URI can be
390         * performed on the UI thread because they are always unblocking.
391         */
392        public static final Uri CONTENT_URI =
393                Uri.withAppendedPath(AUTHORITY_URI, "directories");
394
395        /**
396         * The MIME-type of {@link #CONTENT_URI} providing a directory of
397         * contact directories.
398         */
399        public static final String CONTENT_TYPE =
400                "vnd.android.cursor.dir/contact_directories";
401
402        /**
403         * The MIME type of a {@link #CONTENT_URI} item.
404         */
405        public static final String CONTENT_ITEM_TYPE =
406                "vnd.android.cursor.item/contact_directory";
407
408        /**
409         * _ID of the default directory, which represents locally stored contacts.
410         */
411        public static final long DEFAULT = 0;
412
413        /**
414         * _ID of the directory that represents locally stored invisible contacts.
415         */
416        public static final long LOCAL_INVISIBLE = 1;
417
418        /**
419         * The name of the package that owns this directory. Contacts Provider
420         * fill it in with the name of the package containing the directory provider.
421         * If the package is later uninstalled, the directories it owns are
422         * automatically removed from this table.
423         *
424         * <p>TYPE: TEXT</p>
425         */
426        public static final String PACKAGE_NAME = "packageName";
427
428        /**
429         * The type of directory captured as a resource ID in the context of the
430         * package {@link #PACKAGE_NAME}, e.g. "Corporate Directory"
431         *
432         * <p>TYPE: INTEGER</p>
433         */
434        public static final String TYPE_RESOURCE_ID = "typeResourceId";
435
436        /**
437         * An optional name that can be used in the UI to represent this directory,
438         * e.g. "Acme Corp"
439         * <p>TYPE: text</p>
440         */
441        public static final String DISPLAY_NAME = "displayName";
442
443        /**
444         * <p>
445         * The authority of the Directory Provider. Contacts Provider will
446         * use this authority to forward requests to the directory provider.
447         * A directory provider can leave this column empty - Contacts Provider will fill it in.
448         * </p>
449         * <p>
450         * Clients of this API should not send requests directly to this authority.
451         * All directory requests must be routed through Contacts Provider.
452         * </p>
453         *
454         * <p>TYPE: text</p>
455         */
456        public static final String DIRECTORY_AUTHORITY = "authority";
457
458        /**
459         * The account type which this directory is associated.
460         *
461         * <p>TYPE: text</p>
462         */
463        public static final String ACCOUNT_TYPE = "accountType";
464
465        /**
466         * The account with which this directory is associated. If the account is later
467         * removed, the directories it owns are automatically removed from this table.
468         *
469         * <p>TYPE: text</p>
470         */
471        public static final String ACCOUNT_NAME = "accountName";
472
473        /**
474         * One of {@link #EXPORT_SUPPORT_NONE}, {@link #EXPORT_SUPPORT_ANY_ACCOUNT},
475         * {@link #EXPORT_SUPPORT_SAME_ACCOUNT_ONLY}. This is the expectation the
476         * directory has for data exported from it.  Clients must obey this setting.
477         */
478        public static final String EXPORT_SUPPORT = "exportSupport";
479
480        /**
481         * An {@link #EXPORT_SUPPORT} setting that indicates that the directory
482         * does not allow any data to be copied out of it.
483         */
484        public static final int EXPORT_SUPPORT_NONE = 0;
485
486        /**
487         * An {@link #EXPORT_SUPPORT} setting that indicates that the directory
488         * allow its data copied only to the account specified by
489         * {@link #ACCOUNT_TYPE}/{@link #ACCOUNT_NAME}.
490         */
491        public static final int EXPORT_SUPPORT_SAME_ACCOUNT_ONLY = 1;
492
493        /**
494         * An {@link #EXPORT_SUPPORT} setting that indicates that the directory
495         * allow its data copied to any contacts account.
496         */
497        public static final int EXPORT_SUPPORT_ANY_ACCOUNT = 2;
498
499        /**
500         * One of {@link #SHORTCUT_SUPPORT_NONE}, {@link #SHORTCUT_SUPPORT_DATA_ITEMS_ONLY},
501         * {@link #SHORTCUT_SUPPORT_FULL}. This is the expectation the directory
502         * has for shortcuts created for its elements. Clients must obey this setting.
503         */
504        public static final String SHORTCUT_SUPPORT = "shortcutSupport";
505
506        /**
507         * An {@link #SHORTCUT_SUPPORT} setting that indicates that the directory
508         * does not allow any shortcuts created for its contacts.
509         */
510        public static final int SHORTCUT_SUPPORT_NONE = 0;
511
512        /**
513         * An {@link #SHORTCUT_SUPPORT} setting that indicates that the directory
514         * allow creation of shortcuts for data items like email, phone or postal address,
515         * but not the entire contact.
516         */
517        public static final int SHORTCUT_SUPPORT_DATA_ITEMS_ONLY = 1;
518
519        /**
520         * An {@link #SHORTCUT_SUPPORT} setting that indicates that the directory
521         * allow creation of shortcuts for contact as well as their constituent elements.
522         */
523        public static final int SHORTCUT_SUPPORT_FULL = 2;
524
525        /**
526         * One of {@link #PHOTO_SUPPORT_NONE}, {@link #PHOTO_SUPPORT_THUMBNAIL_ONLY},
527         * {@link #PHOTO_SUPPORT_FULL}. This is a feature flag indicating the extent
528         * to which the directory supports contact photos.
529         */
530        public static final String PHOTO_SUPPORT = "photoSupport";
531
532        /**
533         * An {@link #PHOTO_SUPPORT} setting that indicates that the directory
534         * does not provide any photos.
535         */
536        public static final int PHOTO_SUPPORT_NONE = 0;
537
538        /**
539         * An {@link #PHOTO_SUPPORT} setting that indicates that the directory
540         * can only produce small size thumbnails of contact photos.
541         */
542        public static final int PHOTO_SUPPORT_THUMBNAIL_ONLY = 1;
543
544        /**
545         * An {@link #PHOTO_SUPPORT} setting that indicates that the directory
546         * has full-size contact photos, but cannot provide scaled thumbnails.
547         */
548        public static final int PHOTO_SUPPORT_FULL_SIZE_ONLY = 2;
549
550        /**
551         * An {@link #PHOTO_SUPPORT} setting that indicates that the directory
552         * can produce thumbnails as well as full-size contact photos.
553         */
554        public static final int PHOTO_SUPPORT_FULL = 3;
555
556        /**
557         * Notifies the system of a change in the list of directories handled by
558         * a particular directory provider. The Contacts provider will turn around
559         * and send a query to the directory provider for the full list of directories,
560         * which will replace the previous list.
561         */
562        public static void notifyDirectoryChange(ContentResolver resolver) {
563            // This is done to trigger a query by Contacts Provider back to the directory provider.
564            // No data needs to be sent back, because the provider can infer the calling
565            // package from binder.
566            ContentValues contentValues = new ContentValues();
567            resolver.update(Directory.CONTENT_URI, contentValues, null, null);
568        }
569    }
570
571    /**
572     * @hide should be removed when users are updated to refer to SyncState
573     * @deprecated use SyncState instead
574     */
575    @Deprecated
576    public interface SyncStateColumns extends SyncStateContract.Columns {
577    }
578
579    /**
580     * A table provided for sync adapters to use for storing private sync state data for contacts.
581     *
582     * @see SyncStateContract
583     */
584    public static final class SyncState implements SyncStateContract.Columns {
585        /**
586         * This utility class cannot be instantiated
587         */
588        private SyncState() {}
589
590        public static final String CONTENT_DIRECTORY =
591                SyncStateContract.Constants.CONTENT_DIRECTORY;
592
593        /**
594         * The content:// style URI for this table
595         */
596        public static final Uri CONTENT_URI =
597                Uri.withAppendedPath(AUTHORITY_URI, CONTENT_DIRECTORY);
598
599        /**
600         * @see android.provider.SyncStateContract.Helpers#get
601         */
602        public static byte[] get(ContentProviderClient provider, Account account)
603                throws RemoteException {
604            return SyncStateContract.Helpers.get(provider, CONTENT_URI, account);
605        }
606
607        /**
608         * @see android.provider.SyncStateContract.Helpers#get
609         */
610        public static Pair<Uri, byte[]> getWithUri(ContentProviderClient provider, Account account)
611                throws RemoteException {
612            return SyncStateContract.Helpers.getWithUri(provider, CONTENT_URI, account);
613        }
614
615        /**
616         * @see android.provider.SyncStateContract.Helpers#set
617         */
618        public static void set(ContentProviderClient provider, Account account, byte[] data)
619                throws RemoteException {
620            SyncStateContract.Helpers.set(provider, CONTENT_URI, account, data);
621        }
622
623        /**
624         * @see android.provider.SyncStateContract.Helpers#newSetOperation
625         */
626        public static ContentProviderOperation newSetOperation(Account account, byte[] data) {
627            return SyncStateContract.Helpers.newSetOperation(CONTENT_URI, account, data);
628        }
629    }
630
631
632    /**
633     * A table provided for sync adapters to use for storing private sync state data for the
634     * user's personal profile.
635     *
636     * @see SyncStateContract
637     */
638    public static final class ProfileSyncState implements SyncStateContract.Columns {
639        /**
640         * This utility class cannot be instantiated
641         */
642        private ProfileSyncState() {}
643
644        public static final String CONTENT_DIRECTORY =
645                SyncStateContract.Constants.CONTENT_DIRECTORY;
646
647        /**
648         * The content:// style URI for this table
649         */
650        public static final Uri CONTENT_URI =
651                Uri.withAppendedPath(Profile.CONTENT_URI, CONTENT_DIRECTORY);
652
653        /**
654         * @see android.provider.SyncStateContract.Helpers#get
655         */
656        public static byte[] get(ContentProviderClient provider, Account account)
657                throws RemoteException {
658            return SyncStateContract.Helpers.get(provider, CONTENT_URI, account);
659        }
660
661        /**
662         * @see android.provider.SyncStateContract.Helpers#get
663         */
664        public static Pair<Uri, byte[]> getWithUri(ContentProviderClient provider, Account account)
665                throws RemoteException {
666            return SyncStateContract.Helpers.getWithUri(provider, CONTENT_URI, account);
667        }
668
669        /**
670         * @see android.provider.SyncStateContract.Helpers#set
671         */
672        public static void set(ContentProviderClient provider, Account account, byte[] data)
673                throws RemoteException {
674            SyncStateContract.Helpers.set(provider, CONTENT_URI, account, data);
675        }
676
677        /**
678         * @see android.provider.SyncStateContract.Helpers#newSetOperation
679         */
680        public static ContentProviderOperation newSetOperation(Account account, byte[] data) {
681            return SyncStateContract.Helpers.newSetOperation(CONTENT_URI, account, data);
682        }
683    }
684
685    /**
686     * Generic columns for use by sync adapters. The specific functions of
687     * these columns are private to the sync adapter. Other clients of the API
688     * should not attempt to either read or write this column.
689     *
690     * @see RawContacts
691     * @see Groups
692     */
693    protected interface BaseSyncColumns {
694
695        /** Generic column for use by sync adapters. */
696        public static final String SYNC1 = "sync1";
697        /** Generic column for use by sync adapters. */
698        public static final String SYNC2 = "sync2";
699        /** Generic column for use by sync adapters. */
700        public static final String SYNC3 = "sync3";
701        /** Generic column for use by sync adapters. */
702        public static final String SYNC4 = "sync4";
703    }
704
705    /**
706     * Columns that appear when each row of a table belongs to a specific
707     * account, including sync information that an account may need.
708     *
709     * @see RawContacts
710     * @see Groups
711     */
712    protected interface SyncColumns extends BaseSyncColumns {
713        /**
714         * The name of the account instance to which this row belongs, which when paired with
715         * {@link #ACCOUNT_TYPE} identifies a specific account.
716         * <P>Type: TEXT</P>
717         */
718        public static final String ACCOUNT_NAME = "account_name";
719
720        /**
721         * The type of account to which this row belongs, which when paired with
722         * {@link #ACCOUNT_NAME} identifies a specific account.
723         * <P>Type: TEXT</P>
724         */
725        public static final String ACCOUNT_TYPE = "account_type";
726
727        /**
728         * String that uniquely identifies this row to its source account.
729         * <P>Type: TEXT</P>
730         */
731        public static final String SOURCE_ID = "sourceid";
732
733        /**
734         * Version number that is updated whenever this row or its related data
735         * changes.
736         * <P>Type: INTEGER</P>
737         */
738        public static final String VERSION = "version";
739
740        /**
741         * Flag indicating that {@link #VERSION} has changed, and this row needs
742         * to be synchronized by its owning account.
743         * <P>Type: INTEGER (boolean)</P>
744         */
745        public static final String DIRTY = "dirty";
746    }
747
748    /**
749     * Columns of {@link ContactsContract.Contacts} that track the user's
750     * preferences for, or interactions with, the contact.
751     *
752     * @see Contacts
753     * @see RawContacts
754     * @see ContactsContract.Data
755     * @see PhoneLookup
756     * @see ContactsContract.Contacts.AggregationSuggestions
757     */
758    protected interface ContactOptionsColumns {
759        /**
760         * The number of times a contact has been contacted
761         * <P>Type: INTEGER</P>
762         */
763        public static final String TIMES_CONTACTED = "times_contacted";
764
765        /**
766         * The last time a contact was contacted.
767         * <P>Type: INTEGER</P>
768         */
769        public static final String LAST_TIME_CONTACTED = "last_time_contacted";
770
771        /**
772         * Is the contact starred?
773         * <P>Type: INTEGER (boolean)</P>
774         */
775        public static final String STARRED = "starred";
776
777        /**
778         * The position at which the contact is pinned. If {@link PinnedPositions#UNPINNED},
779         * the contact is not pinned. Also see {@link PinnedPositions}.
780         * <P>Type: INTEGER </P>
781         */
782        public static final String PINNED = "pinned";
783
784        /**
785         * URI for a custom ringtone associated with the contact. If null or missing,
786         * the default ringtone is used.
787         * <P>Type: TEXT (URI to the ringtone)</P>
788         */
789        public static final String CUSTOM_RINGTONE = "custom_ringtone";
790
791        /**
792         * Whether the contact should always be sent to voicemail. If missing,
793         * defaults to false.
794         * <P>Type: INTEGER (0 for false, 1 for true)</P>
795         */
796        public static final String SEND_TO_VOICEMAIL = "send_to_voicemail";
797    }
798
799    /**
800     * Columns of {@link ContactsContract.Contacts} that refer to intrinsic
801     * properties of the contact, as opposed to the user-specified options
802     * found in {@link ContactOptionsColumns}.
803     *
804     * @see Contacts
805     * @see ContactsContract.Data
806     * @see PhoneLookup
807     * @see ContactsContract.Contacts.AggregationSuggestions
808     */
809    protected interface ContactsColumns {
810        /**
811         * The display name for the contact.
812         * <P>Type: TEXT</P>
813         */
814        public static final String DISPLAY_NAME = ContactNameColumns.DISPLAY_NAME_PRIMARY;
815
816        /**
817         * Reference to the row in the RawContacts table holding the contact name.
818         * <P>Type: INTEGER REFERENCES raw_contacts(_id)</P>
819         */
820        public static final String NAME_RAW_CONTACT_ID = "name_raw_contact_id";
821
822        /**
823         * Reference to the row in the data table holding the photo.  A photo can
824         * be referred to either by ID (this field) or by URI (see {@link #PHOTO_THUMBNAIL_URI}
825         * and {@link #PHOTO_URI}).
826         * If PHOTO_ID is null, consult {@link #PHOTO_URI} or {@link #PHOTO_THUMBNAIL_URI},
827         * which is a more generic mechanism for referencing the contact photo, especially for
828         * contacts returned by non-local directories (see {@link Directory}).
829         *
830         * <P>Type: INTEGER REFERENCES data(_id)</P>
831         */
832        public static final String PHOTO_ID = "photo_id";
833
834        /**
835         * Photo file ID of the full-size photo.  If present, this will be used to populate
836         * {@link #PHOTO_URI}.  The ID can also be used with
837         * {@link ContactsContract.DisplayPhoto#CONTENT_URI} to create a URI to the photo.
838         * If this is present, {@link #PHOTO_ID} is also guaranteed to be populated.
839         *
840         * <P>Type: INTEGER</P>
841         */
842        public static final String PHOTO_FILE_ID = "photo_file_id";
843
844        /**
845         * A URI that can be used to retrieve the contact's full-size photo.
846         * If PHOTO_FILE_ID is not null, this will be populated with a URI based off
847         * {@link ContactsContract.DisplayPhoto#CONTENT_URI}.  Otherwise, this will
848         * be populated with the same value as {@link #PHOTO_THUMBNAIL_URI}.
849         * A photo can be referred to either by a URI (this field) or by ID
850         * (see {@link #PHOTO_ID}). If either PHOTO_FILE_ID or PHOTO_ID is not null,
851         * PHOTO_URI and PHOTO_THUMBNAIL_URI shall not be null (but not necessarily
852         * vice versa).  Thus using PHOTO_URI is a more robust method of retrieving
853         * contact photos.
854         *
855         * <P>Type: TEXT</P>
856         */
857        public static final String PHOTO_URI = "photo_uri";
858
859        /**
860         * A URI that can be used to retrieve a thumbnail of the contact's photo.
861         * A photo can be referred to either by a URI (this field or {@link #PHOTO_URI})
862         * or by ID (see {@link #PHOTO_ID}). If PHOTO_ID is not null, PHOTO_URI and
863         * PHOTO_THUMBNAIL_URI shall not be null (but not necessarily vice versa).
864         * If the content provider does not differentiate between full-size photos
865         * and thumbnail photos, PHOTO_THUMBNAIL_URI and {@link #PHOTO_URI} can contain
866         * the same value, but either both shall be null or both not null.
867         *
868         * <P>Type: TEXT</P>
869         */
870        public static final String PHOTO_THUMBNAIL_URI = "photo_thumb_uri";
871
872        /**
873         * Flag that reflects whether the contact exists inside the default directory.
874         * Ie, whether the contact is designed to only be visible outside search.
875         */
876        public static final String IN_DEFAULT_DIRECTORY = "in_default_directory";
877
878        /**
879         * Flag that reflects the {@link Groups#GROUP_VISIBLE} state of any
880         * {@link CommonDataKinds.GroupMembership} for this contact.
881         */
882        public static final String IN_VISIBLE_GROUP = "in_visible_group";
883
884        /**
885         * Flag that reflects whether this contact represents the user's
886         * personal profile entry.
887         */
888        public static final String IS_USER_PROFILE = "is_user_profile";
889
890        /**
891         * An indicator of whether this contact has at least one phone number. "1" if there is
892         * at least one phone number, "0" otherwise.
893         * <P>Type: INTEGER</P>
894         */
895        public static final String HAS_PHONE_NUMBER = "has_phone_number";
896
897        /**
898         * An opaque value that contains hints on how to find the contact if
899         * its row id changed as a result of a sync or aggregation.
900         */
901        public static final String LOOKUP_KEY = "lookup";
902
903        /**
904         * Timestamp (milliseconds since epoch) of when this contact was last updated.  This
905         * includes updates to all data associated with this contact including raw contacts.  Any
906         * modification (including deletes and inserts) of underlying contact data are also
907         * reflected in this timestamp.
908         */
909        public static final String CONTACT_LAST_UPDATED_TIMESTAMP =
910                "contact_last_updated_timestamp";
911    }
912
913    /**
914     * @see Contacts
915     */
916    protected interface ContactStatusColumns {
917        /**
918         * Contact presence status. See {@link StatusUpdates} for individual status
919         * definitions.
920         * <p>Type: NUMBER</p>
921         */
922        public static final String CONTACT_PRESENCE = "contact_presence";
923
924        /**
925         * Contact Chat Capabilities. See {@link StatusUpdates} for individual
926         * definitions.
927         * <p>Type: NUMBER</p>
928         */
929        public static final String CONTACT_CHAT_CAPABILITY = "contact_chat_capability";
930
931        /**
932         * Contact's latest status update.
933         * <p>Type: TEXT</p>
934         */
935        public static final String CONTACT_STATUS = "contact_status";
936
937        /**
938         * The absolute time in milliseconds when the latest status was
939         * inserted/updated.
940         * <p>Type: NUMBER</p>
941         */
942        public static final String CONTACT_STATUS_TIMESTAMP = "contact_status_ts";
943
944        /**
945         * The package containing resources for this status: label and icon.
946         * <p>Type: TEXT</p>
947         */
948        public static final String CONTACT_STATUS_RES_PACKAGE = "contact_status_res_package";
949
950        /**
951         * The resource ID of the label describing the source of contact
952         * status, e.g. "Google Talk". This resource is scoped by the
953         * {@link #CONTACT_STATUS_RES_PACKAGE}.
954         * <p>Type: NUMBER</p>
955         */
956        public static final String CONTACT_STATUS_LABEL = "contact_status_label";
957
958        /**
959         * The resource ID of the icon for the source of contact status. This
960         * resource is scoped by the {@link #CONTACT_STATUS_RES_PACKAGE}.
961         * <p>Type: NUMBER</p>
962         */
963        public static final String CONTACT_STATUS_ICON = "contact_status_icon";
964    }
965
966    /**
967     * Constants for various styles of combining given name, family name etc into
968     * a full name.  For example, the western tradition follows the pattern
969     * 'given name' 'middle name' 'family name' with the alternative pattern being
970     * 'family name', 'given name' 'middle name'.  The CJK tradition is
971     * 'family name' 'middle name' 'given name', with Japanese favoring a space between
972     * the names and Chinese omitting the space.
973     */
974    public interface FullNameStyle {
975        public static final int UNDEFINED = 0;
976        public static final int WESTERN = 1;
977
978        /**
979         * Used if the name is written in Hanzi/Kanji/Hanja and we could not determine
980         * which specific language it belongs to: Chinese, Japanese or Korean.
981         */
982        public static final int CJK = 2;
983
984        public static final int CHINESE = 3;
985        public static final int JAPANESE = 4;
986        public static final int KOREAN = 5;
987    }
988
989    /**
990     * Constants for various styles of capturing the pronunciation of a person's name.
991     */
992    public interface PhoneticNameStyle {
993        public static final int UNDEFINED = 0;
994
995        /**
996         * Pinyin is a phonetic method of entering Chinese characters. Typically not explicitly
997         * shown in UIs, but used for searches and sorting.
998         */
999        public static final int PINYIN = 3;
1000
1001        /**
1002         * Hiragana and Katakana are two common styles of writing out the pronunciation
1003         * of a Japanese names.
1004         */
1005        public static final int JAPANESE = 4;
1006
1007        /**
1008         * Hangul is the Korean phonetic alphabet.
1009         */
1010        public static final int KOREAN = 5;
1011    }
1012
1013    /**
1014     * Types of data used to produce the display name for a contact. In the order
1015     * of increasing priority: {@link #EMAIL}, {@link #PHONE},
1016     * {@link #ORGANIZATION}, {@link #NICKNAME}, {@link #STRUCTURED_PHONETIC_NAME},
1017     * {@link #STRUCTURED_NAME}.
1018     */
1019    public interface DisplayNameSources {
1020        public static final int UNDEFINED = 0;
1021        public static final int EMAIL = 10;
1022        public static final int PHONE = 20;
1023        public static final int ORGANIZATION = 30;
1024        public static final int NICKNAME = 35;
1025        /** Display name comes from a structured name that only has phonetic components. */
1026        public static final int STRUCTURED_PHONETIC_NAME = 37;
1027        public static final int STRUCTURED_NAME = 40;
1028    }
1029
1030    /**
1031     * Contact name and contact name metadata columns in the RawContacts table.
1032     *
1033     * @see Contacts
1034     * @see RawContacts
1035     */
1036    protected interface ContactNameColumns {
1037
1038        /**
1039         * The kind of data that is used as the display name for the contact, such as
1040         * structured name or email address.  See {@link DisplayNameSources}.
1041         */
1042        public static final String DISPLAY_NAME_SOURCE = "display_name_source";
1043
1044        /**
1045         * <p>
1046         * The standard text shown as the contact's display name, based on the best
1047         * available information for the contact (for example, it might be the email address
1048         * if the name is not available).
1049         * The information actually used to compute the name is stored in
1050         * {@link #DISPLAY_NAME_SOURCE}.
1051         * </p>
1052         * <p>
1053         * A contacts provider is free to choose whatever representation makes most
1054         * sense for its target market.
1055         * For example in the default Android Open Source Project implementation,
1056         * if the display name is
1057         * based on the structured name and the structured name follows
1058         * the Western full-name style, then this field contains the "given name first"
1059         * version of the full name.
1060         * <p>
1061         *
1062         * @see ContactsContract.ContactNameColumns#DISPLAY_NAME_ALTERNATIVE
1063         */
1064        public static final String DISPLAY_NAME_PRIMARY = "display_name";
1065
1066        /**
1067         * <p>
1068         * An alternative representation of the display name, such as "family name first"
1069         * instead of "given name first" for Western names.  If an alternative is not
1070         * available, the values should be the same as {@link #DISPLAY_NAME_PRIMARY}.
1071         * </p>
1072         * <p>
1073         * A contacts provider is free to provide alternatives as necessary for
1074         * its target market.
1075         * For example the default Android Open Source Project contacts provider
1076         * currently provides an
1077         * alternative in a single case:  if the display name is
1078         * based on the structured name and the structured name follows
1079         * the Western full name style, then the field contains the "family name first"
1080         * version of the full name.
1081         * Other cases may be added later.
1082         * </p>
1083         */
1084        public static final String DISPLAY_NAME_ALTERNATIVE = "display_name_alt";
1085
1086        /**
1087         * The phonetic alphabet used to represent the {@link #PHONETIC_NAME}.  See
1088         * {@link PhoneticNameStyle}.
1089         */
1090        public static final String PHONETIC_NAME_STYLE = "phonetic_name_style";
1091
1092        /**
1093         * <p>
1094         * Pronunciation of the full name in the phonetic alphabet specified by
1095         * {@link #PHONETIC_NAME_STYLE}.
1096         * </p>
1097         * <p>
1098         * The value may be set manually by the user. This capability is of
1099         * interest only in countries with commonly used phonetic alphabets,
1100         * such as Japan and Korea. See {@link PhoneticNameStyle}.
1101         * </p>
1102         */
1103        public static final String PHONETIC_NAME = "phonetic_name";
1104
1105        /**
1106         * Sort key that takes into account locale-based traditions for sorting
1107         * names in address books.  The default
1108         * sort key is {@link #DISPLAY_NAME_PRIMARY}.  For Chinese names
1109         * the sort key is the name's Pinyin spelling, and for Japanese names
1110         * it is the Hiragana version of the phonetic name.
1111         */
1112        public static final String SORT_KEY_PRIMARY = "sort_key";
1113
1114        /**
1115         * Sort key based on the alternative representation of the full name,
1116         * {@link #DISPLAY_NAME_ALTERNATIVE}.  Thus for Western names,
1117         * it is the one using the "family name first" format.
1118         */
1119        public static final String SORT_KEY_ALTERNATIVE = "sort_key_alt";
1120    }
1121
1122    interface ContactCounts {
1123
1124        /**
1125         * Add this query parameter to a URI to get back row counts grouped by the address book
1126         * index as cursor extras. For most languages it is the first letter of the sort key. This
1127         * parameter does not affect the main content of the cursor.
1128         *
1129         * <p>
1130         * <pre>
1131         * Example:
1132         *
1133         * import android.provider.ContactsContract.Contacts;
1134         *
1135         * Uri uri = Contacts.CONTENT_URI.buildUpon()
1136         *          .appendQueryParameter(Contacts.EXTRA_ADDRESS_BOOK_INDEX, "true")
1137         *          .build();
1138         * Cursor cursor = getContentResolver().query(uri,
1139         *          new String[] {Contacts.DISPLAY_NAME},
1140         *          null, null, null);
1141         * Bundle bundle = cursor.getExtras();
1142         * if (bundle.containsKey(Contacts.EXTRA_ADDRESS_BOOK_INDEX_TITLES) &&
1143         *         bundle.containsKey(Contacts.EXTRA_ADDRESS_BOOK_INDEX_COUNTS)) {
1144         *     String sections[] =
1145         *             bundle.getStringArray(Contacts.EXTRA_ADDRESS_BOOK_INDEX_TITLES);
1146         *     int counts[] = bundle.getIntArray(Contacts.EXTRA_ADDRESS_BOOK_INDEX_COUNTS);
1147         * }
1148         * </pre>
1149         * </p>
1150         */
1151        public static final String EXTRA_ADDRESS_BOOK_INDEX =
1152                "android.provider.extra.ADDRESS_BOOK_INDEX";
1153
1154        /**
1155         * The array of address book index titles, which are returned in the
1156         * same order as the data in the cursor.
1157         * <p>TYPE: String[]</p>
1158         */
1159        public static final String EXTRA_ADDRESS_BOOK_INDEX_TITLES =
1160                "android.provider.extra.ADDRESS_BOOK_INDEX_TITLES";
1161
1162        /**
1163         * The array of group counts for the corresponding group.  Contains the same number
1164         * of elements as the EXTRA_ADDRESS_BOOK_INDEX_TITLES array.
1165         * <p>TYPE: int[]</p>
1166         */
1167        public static final String EXTRA_ADDRESS_BOOK_INDEX_COUNTS =
1168                "android.provider.extra.ADDRESS_BOOK_INDEX_COUNTS";
1169    }
1170
1171    /**
1172     * Constants for the contacts table, which contains a record per aggregate
1173     * of raw contacts representing the same person.
1174     * <h3>Operations</h3>
1175     * <dl>
1176     * <dt><b>Insert</b></dt>
1177     * <dd>A Contact cannot be created explicitly. When a raw contact is
1178     * inserted, the provider will first try to find a Contact representing the
1179     * same person. If one is found, the raw contact's
1180     * {@link RawContacts#CONTACT_ID} column gets the _ID of the aggregate
1181     * Contact. If no match is found, the provider automatically inserts a new
1182     * Contact and puts its _ID into the {@link RawContacts#CONTACT_ID} column
1183     * of the newly inserted raw contact.</dd>
1184     * <dt><b>Update</b></dt>
1185     * <dd>Only certain columns of Contact are modifiable:
1186     * {@link #TIMES_CONTACTED}, {@link #LAST_TIME_CONTACTED}, {@link #STARRED},
1187     * {@link #CUSTOM_RINGTONE}, {@link #SEND_TO_VOICEMAIL}. Changing any of
1188     * these columns on the Contact also changes them on all constituent raw
1189     * contacts.</dd>
1190     * <dt><b>Delete</b></dt>
1191     * <dd>Be careful with deleting Contacts! Deleting an aggregate contact
1192     * deletes all constituent raw contacts. The corresponding sync adapters
1193     * will notice the deletions of their respective raw contacts and remove
1194     * them from their back end storage.</dd>
1195     * <dt><b>Query</b></dt>
1196     * <dd>
1197     * <ul>
1198     * <li>If you need to read an individual contact, consider using
1199     * {@link #CONTENT_LOOKUP_URI} instead of {@link #CONTENT_URI}.</li>
1200     * <li>If you need to look up a contact by the phone number, use
1201     * {@link PhoneLookup#CONTENT_FILTER_URI PhoneLookup.CONTENT_FILTER_URI},
1202     * which is optimized for this purpose.</li>
1203     * <li>If you need to look up a contact by partial name, e.g. to produce
1204     * filter-as-you-type suggestions, use the {@link #CONTENT_FILTER_URI} URI.
1205     * <li>If you need to look up a contact by some data element like email
1206     * address, nickname, etc, use a query against the {@link ContactsContract.Data} table.
1207     * The result will contain contact ID, name etc.
1208     * </ul>
1209     * </dd>
1210     * </dl>
1211     * <h2>Columns</h2>
1212     * <table class="jd-sumtable">
1213     * <tr>
1214     * <th colspan='4'>Contacts</th>
1215     * </tr>
1216     * <tr>
1217     * <td>long</td>
1218     * <td>{@link #_ID}</td>
1219     * <td>read-only</td>
1220     * <td>Row ID. Consider using {@link #LOOKUP_KEY} instead.</td>
1221     * </tr>
1222     * <tr>
1223     * <td>String</td>
1224     * <td>{@link #LOOKUP_KEY}</td>
1225     * <td>read-only</td>
1226     * <td>An opaque value that contains hints on how to find the contact if its
1227     * row id changed as a result of a sync or aggregation.</td>
1228     * </tr>
1229     * <tr>
1230     * <td>long</td>
1231     * <td>NAME_RAW_CONTACT_ID</td>
1232     * <td>read-only</td>
1233     * <td>The ID of the raw contact that contributes the display name
1234     * to the aggregate contact. During aggregation one of the constituent
1235     * raw contacts is chosen using a heuristic: a longer name or a name
1236     * with more diacritic marks or more upper case characters is chosen.</td>
1237     * </tr>
1238     * <tr>
1239     * <td>String</td>
1240     * <td>DISPLAY_NAME_PRIMARY</td>
1241     * <td>read-only</td>
1242     * <td>The display name for the contact. It is the display name
1243     * contributed by the raw contact referred to by the NAME_RAW_CONTACT_ID
1244     * column.</td>
1245     * </tr>
1246     * <tr>
1247     * <td>long</td>
1248     * <td>{@link #PHOTO_ID}</td>
1249     * <td>read-only</td>
1250     * <td>Reference to the row in the {@link ContactsContract.Data} table holding the photo.
1251     * That row has the mime type
1252     * {@link CommonDataKinds.Photo#CONTENT_ITEM_TYPE}. The value of this field
1253     * is computed automatically based on the
1254     * {@link CommonDataKinds.Photo#IS_SUPER_PRIMARY} field of the data rows of
1255     * that mime type.</td>
1256     * </tr>
1257     * <tr>
1258     * <td>long</td>
1259     * <td>{@link #PHOTO_URI}</td>
1260     * <td>read-only</td>
1261     * <td>A URI that can be used to retrieve the contact's full-size photo. This
1262     * column is the preferred method of retrieving the contact photo.</td>
1263     * </tr>
1264     * <tr>
1265     * <td>long</td>
1266     * <td>{@link #PHOTO_THUMBNAIL_URI}</td>
1267     * <td>read-only</td>
1268     * <td>A URI that can be used to retrieve the thumbnail of contact's photo.  This
1269     * column is the preferred method of retrieving the contact photo.</td>
1270     * </tr>
1271     * <tr>
1272     * <td>int</td>
1273     * <td>{@link #IN_VISIBLE_GROUP}</td>
1274     * <td>read-only</td>
1275     * <td>An indicator of whether this contact is supposed to be visible in the
1276     * UI. "1" if the contact has at least one raw contact that belongs to a
1277     * visible group; "0" otherwise.</td>
1278     * </tr>
1279     * <tr>
1280     * <td>int</td>
1281     * <td>{@link #HAS_PHONE_NUMBER}</td>
1282     * <td>read-only</td>
1283     * <td>An indicator of whether this contact has at least one phone number.
1284     * "1" if there is at least one phone number, "0" otherwise.</td>
1285     * </tr>
1286     * <tr>
1287     * <td>int</td>
1288     * <td>{@link #TIMES_CONTACTED}</td>
1289     * <td>read/write</td>
1290     * <td>The number of times the contact has been contacted. See
1291     * {@link #markAsContacted}. When raw contacts are aggregated, this field is
1292     * computed automatically as the maximum number of times contacted among all
1293     * constituent raw contacts. Setting this field automatically changes the
1294     * corresponding field on all constituent raw contacts.</td>
1295     * </tr>
1296     * <tr>
1297     * <td>long</td>
1298     * <td>{@link #LAST_TIME_CONTACTED}</td>
1299     * <td>read/write</td>
1300     * <td>The timestamp of the last time the contact was contacted. See
1301     * {@link #markAsContacted}. Setting this field also automatically
1302     * increments {@link #TIMES_CONTACTED}. When raw contacts are aggregated,
1303     * this field is computed automatically as the latest time contacted of all
1304     * constituent raw contacts. Setting this field automatically changes the
1305     * corresponding field on all constituent raw contacts.</td>
1306     * </tr>
1307     * <tr>
1308     * <td>int</td>
1309     * <td>{@link #STARRED}</td>
1310     * <td>read/write</td>
1311     * <td>An indicator for favorite contacts: '1' if favorite, '0' otherwise.
1312     * When raw contacts are aggregated, this field is automatically computed:
1313     * if any constituent raw contacts are starred, then this field is set to
1314     * '1'. Setting this field automatically changes the corresponding field on
1315     * all constituent raw contacts.</td>
1316     * </tr>
1317     * <tr>
1318     * <td>String</td>
1319     * <td>{@link #CUSTOM_RINGTONE}</td>
1320     * <td>read/write</td>
1321     * <td>A custom ringtone associated with a contact. Typically this is the
1322     * URI returned by an activity launched with the
1323     * {@link android.media.RingtoneManager#ACTION_RINGTONE_PICKER} intent.</td>
1324     * </tr>
1325     * <tr>
1326     * <td>int</td>
1327     * <td>{@link #SEND_TO_VOICEMAIL}</td>
1328     * <td>read/write</td>
1329     * <td>An indicator of whether calls from this contact should be forwarded
1330     * directly to voice mail ('1') or not ('0'). When raw contacts are
1331     * aggregated, this field is automatically computed: if <i>all</i>
1332     * constituent raw contacts have SEND_TO_VOICEMAIL=1, then this field is set
1333     * to '1'. Setting this field automatically changes the corresponding field
1334     * on all constituent raw contacts.</td>
1335     * </tr>
1336     * <tr>
1337     * <td>int</td>
1338     * <td>{@link #CONTACT_PRESENCE}</td>
1339     * <td>read-only</td>
1340     * <td>Contact IM presence status. See {@link StatusUpdates} for individual
1341     * status definitions. Automatically computed as the highest presence of all
1342     * constituent raw contacts. The provider may choose not to store this value
1343     * in persistent storage. The expectation is that presence status will be
1344     * updated on a regular basis.</td>
1345     * </tr>
1346     * <tr>
1347     * <td>String</td>
1348     * <td>{@link #CONTACT_STATUS}</td>
1349     * <td>read-only</td>
1350     * <td>Contact's latest status update. Automatically computed as the latest
1351     * of all constituent raw contacts' status updates.</td>
1352     * </tr>
1353     * <tr>
1354     * <td>long</td>
1355     * <td>{@link #CONTACT_STATUS_TIMESTAMP}</td>
1356     * <td>read-only</td>
1357     * <td>The absolute time in milliseconds when the latest status was
1358     * inserted/updated.</td>
1359     * </tr>
1360     * <tr>
1361     * <td>String</td>
1362     * <td>{@link #CONTACT_STATUS_RES_PACKAGE}</td>
1363     * <td>read-only</td>
1364     * <td> The package containing resources for this status: label and icon.</td>
1365     * </tr>
1366     * <tr>
1367     * <td>long</td>
1368     * <td>{@link #CONTACT_STATUS_LABEL}</td>
1369     * <td>read-only</td>
1370     * <td>The resource ID of the label describing the source of contact status,
1371     * e.g. "Google Talk". This resource is scoped by the
1372     * {@link #CONTACT_STATUS_RES_PACKAGE}.</td>
1373     * </tr>
1374     * <tr>
1375     * <td>long</td>
1376     * <td>{@link #CONTACT_STATUS_ICON}</td>
1377     * <td>read-only</td>
1378     * <td>The resource ID of the icon for the source of contact status. This
1379     * resource is scoped by the {@link #CONTACT_STATUS_RES_PACKAGE}.</td>
1380     * </tr>
1381     * </table>
1382     */
1383    public static class Contacts implements BaseColumns, ContactsColumns,
1384            ContactOptionsColumns, ContactNameColumns, ContactStatusColumns, ContactCounts {
1385        /**
1386         * This utility class cannot be instantiated
1387         */
1388        private Contacts()  {}
1389
1390        /**
1391         * The content:// style URI for this table
1392         */
1393        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "contacts");
1394
1395        /**
1396         * Special contacts URI to refer to contacts on the corp profile from the personal
1397         * profile.
1398         *
1399         * It's supported only by a few specific places for referring to contact pictures that
1400         * are in the corp provider for enterprise caller-ID.  Contact picture URIs returned from
1401         * {@link PhoneLookup#ENTERPRISE_CONTENT_FILTER_URI} may contain this kind of URI.
1402         *
1403         * @hide
1404         */
1405        public static final Uri CORP_CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI,
1406                "contacts_corp");
1407
1408        /**
1409         * A content:// style URI for this table that should be used to create
1410         * shortcuts or otherwise create long-term links to contacts. This URI
1411         * should always be followed by a "/" and the contact's {@link #LOOKUP_KEY}.
1412         * It can optionally also have a "/" and last known contact ID appended after
1413         * that. This "complete" format is an important optimization and is highly recommended.
1414         * <p>
1415         * As long as the contact's row ID remains the same, this URI is
1416         * equivalent to {@link #CONTENT_URI}. If the contact's row ID changes
1417         * as a result of a sync or aggregation, this URI will look up the
1418         * contact using indirect information (sync IDs or constituent raw
1419         * contacts).
1420         * <p>
1421         * Lookup key should be appended unencoded - it is stored in the encoded
1422         * form, ready for use in a URI.
1423         */
1424        public static final Uri CONTENT_LOOKUP_URI = Uri.withAppendedPath(CONTENT_URI,
1425                "lookup");
1426
1427        /**
1428         * Base {@link Uri} for referencing a single {@link Contacts} entry,
1429         * created by appending {@link #LOOKUP_KEY} using
1430         * {@link Uri#withAppendedPath(Uri, String)}. Provides
1431         * {@link OpenableColumns} columns when queried, or returns the
1432         * referenced contact formatted as a vCard when opened through
1433         * {@link ContentResolver#openAssetFileDescriptor(Uri, String)}.
1434         */
1435        public static final Uri CONTENT_VCARD_URI = Uri.withAppendedPath(CONTENT_URI,
1436                "as_vcard");
1437
1438       /**
1439        * Boolean parameter that may be used with {@link #CONTENT_VCARD_URI}
1440        * and {@link #CONTENT_MULTI_VCARD_URI} to indicate that the returned
1441        * vcard should not contain a photo.
1442        *
1443        * This is useful for obtaining a space efficient vcard.
1444        */
1445        public static final String QUERY_PARAMETER_VCARD_NO_PHOTO = "no_photo";
1446
1447        /**
1448         * Base {@link Uri} for referencing multiple {@link Contacts} entry,
1449         * created by appending {@link #LOOKUP_KEY} using
1450         * {@link Uri#withAppendedPath(Uri, String)}. The lookup keys have to be
1451         * joined with the colon (":") separator, and the resulting string encoded.
1452         *
1453         * Provides {@link OpenableColumns} columns when queried, or returns the
1454         * referenced contact formatted as a vCard when opened through
1455         * {@link ContentResolver#openAssetFileDescriptor(Uri, String)}.
1456         *
1457         * <p>
1458         * Usage example:
1459         * <dl>
1460         * <dt>The following code snippet creates a multi-vcard URI that references all the
1461         * contacts in a user's database.</dt>
1462         * <dd>
1463         *
1464         * <pre>
1465         * public Uri getAllContactsVcardUri() {
1466         *     Cursor cursor = getActivity().getContentResolver().query(Contacts.CONTENT_URI,
1467         *         new String[] {Contacts.LOOKUP_KEY}, null, null, null);
1468         *     if (cursor == null) {
1469         *         return null;
1470         *     }
1471         *     try {
1472         *         StringBuilder uriListBuilder = new StringBuilder();
1473         *         int index = 0;
1474         *         while (cursor.moveToNext()) {
1475         *             if (index != 0) uriListBuilder.append(':');
1476         *             uriListBuilder.append(cursor.getString(0));
1477         *             index++;
1478         *         }
1479         *         return Uri.withAppendedPath(Contacts.CONTENT_MULTI_VCARD_URI,
1480         *                 Uri.encode(uriListBuilder.toString()));
1481         *     } finally {
1482         *         cursor.close();
1483         *     }
1484         * }
1485         * </pre>
1486         *
1487         * </p>
1488         */
1489        public static final Uri CONTENT_MULTI_VCARD_URI = Uri.withAppendedPath(CONTENT_URI,
1490                "as_multi_vcard");
1491
1492        /**
1493         * Builds a {@link #CONTENT_LOOKUP_URI} style {@link Uri} describing the
1494         * requested {@link Contacts} entry.
1495         *
1496         * @param contactUri A {@link #CONTENT_URI} row, or an existing
1497         *            {@link #CONTENT_LOOKUP_URI} to attempt refreshing.
1498         */
1499        public static Uri getLookupUri(ContentResolver resolver, Uri contactUri) {
1500            final Cursor c = resolver.query(contactUri, new String[] {
1501                    Contacts.LOOKUP_KEY, Contacts._ID
1502            }, null, null, null);
1503            if (c == null) {
1504                return null;
1505            }
1506
1507            try {
1508                if (c.moveToFirst()) {
1509                    final String lookupKey = c.getString(0);
1510                    final long contactId = c.getLong(1);
1511                    return getLookupUri(contactId, lookupKey);
1512                }
1513            } finally {
1514                c.close();
1515            }
1516            return null;
1517        }
1518
1519        /**
1520         * Build a {@link #CONTENT_LOOKUP_URI} lookup {@link Uri} using the
1521         * given {@link ContactsContract.Contacts#_ID} and {@link #LOOKUP_KEY}.
1522         * <p>
1523         * Returns null if unable to construct a valid lookup URI from the
1524         * provided parameters.
1525         */
1526        public static Uri getLookupUri(long contactId, String lookupKey) {
1527            if (TextUtils.isEmpty(lookupKey)) {
1528                return null;
1529            }
1530            return ContentUris.withAppendedId(Uri.withAppendedPath(Contacts.CONTENT_LOOKUP_URI,
1531                    lookupKey), contactId);
1532        }
1533
1534        /**
1535         * Computes a content URI (see {@link #CONTENT_URI}) given a lookup URI.
1536         * <p>
1537         * Returns null if the contact cannot be found.
1538         */
1539        public static Uri lookupContact(ContentResolver resolver, Uri lookupUri) {
1540            if (lookupUri == null) {
1541                return null;
1542            }
1543
1544            Cursor c = resolver.query(lookupUri, new String[]{Contacts._ID}, null, null, null);
1545            if (c == null) {
1546                return null;
1547            }
1548
1549            try {
1550                if (c.moveToFirst()) {
1551                    long contactId = c.getLong(0);
1552                    return ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId);
1553                }
1554            } finally {
1555                c.close();
1556            }
1557            return null;
1558        }
1559
1560        /**
1561         * Mark a contact as having been contacted. Updates two fields:
1562         * {@link #TIMES_CONTACTED} and {@link #LAST_TIME_CONTACTED}. The
1563         * TIMES_CONTACTED field is incremented by 1 and the LAST_TIME_CONTACTED
1564         * field is populated with the current system time.
1565         *
1566         * @param resolver the ContentResolver to use
1567         * @param contactId the person who was contacted
1568         *
1569         * @deprecated The class DataUsageStatUpdater of the Android support library should
1570         *     be used instead.
1571         */
1572        @Deprecated
1573        public static void markAsContacted(ContentResolver resolver, long contactId) {
1574            Uri uri = ContentUris.withAppendedId(CONTENT_URI, contactId);
1575            ContentValues values = new ContentValues();
1576            // TIMES_CONTACTED will be incremented when LAST_TIME_CONTACTED is modified.
1577            values.put(LAST_TIME_CONTACTED, System.currentTimeMillis());
1578            resolver.update(uri, values, null, null);
1579        }
1580
1581        /**
1582         * The content:// style URI used for "type-to-filter" functionality on the
1583         * {@link #CONTENT_URI} URI. The filter string will be used to match
1584         * various parts of the contact name. The filter argument should be passed
1585         * as an additional path segment after this URI.
1586         */
1587        public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(
1588                CONTENT_URI, "filter");
1589
1590        /**
1591         * The content:// style URI for this table joined with useful data from
1592         * {@link ContactsContract.Data}, filtered to include only starred contacts
1593         * and the most frequently contacted contacts.
1594         */
1595        public static final Uri CONTENT_STREQUENT_URI = Uri.withAppendedPath(
1596                CONTENT_URI, "strequent");
1597
1598        /**
1599         * The content:// style URI for showing a list of frequently contacted people.
1600         */
1601        public static final Uri CONTENT_FREQUENT_URI = Uri.withAppendedPath(
1602                CONTENT_URI, "frequent");
1603
1604        /**
1605         * The content:// style URI used for "type-to-filter" functionality on the
1606         * {@link #CONTENT_STREQUENT_URI} URI. The filter string will be used to match
1607         * various parts of the contact name. The filter argument should be passed
1608         * as an additional path segment after this URI.
1609         */
1610        public static final Uri CONTENT_STREQUENT_FILTER_URI = Uri.withAppendedPath(
1611                CONTENT_STREQUENT_URI, "filter");
1612
1613        public static final Uri CONTENT_GROUP_URI = Uri.withAppendedPath(
1614                CONTENT_URI, "group");
1615
1616        /**
1617         * The MIME type of {@link #CONTENT_URI} providing a directory of
1618         * people.
1619         */
1620        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/contact";
1621
1622        /**
1623         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
1624         * person.
1625         */
1626        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contact";
1627
1628        /**
1629         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
1630         * person.
1631         */
1632        public static final String CONTENT_VCARD_TYPE = "text/x-vcard";
1633
1634        /**
1635         * Mimimal ID for corp contacts returned from
1636         * {@link PhoneLookup#ENTERPRISE_CONTENT_FILTER_URI}.
1637         *
1638         * @hide
1639         */
1640        public static long ENTERPRISE_CONTACT_ID_BASE = 1000000000; // slightly smaller than 2 ** 30
1641
1642        /**
1643         * Prefix for corp contacts returned from
1644         * {@link PhoneLookup#ENTERPRISE_CONTENT_FILTER_URI}.
1645         *
1646         * @hide
1647         */
1648        public static String ENTERPRISE_CONTACT_LOOKUP_PREFIX = "c-";
1649
1650        /**
1651         * Return TRUE if a contact ID is from the contacts provider on the enterprise profile.
1652         *
1653         * {@link PhoneLookup#ENTERPRISE_CONTENT_FILTER_URI} may return such a contact.
1654         */
1655        public static boolean isEnterpriseContactId(long contactId) {
1656            return (contactId >= ENTERPRISE_CONTACT_ID_BASE) && (contactId < Profile.MIN_ID);
1657        }
1658
1659        /**
1660         * A sub-directory of a single contact that contains all of the constituent raw contact
1661         * {@link ContactsContract.Data} rows.  This directory can be used either
1662         * with a {@link #CONTENT_URI} or {@link #CONTENT_LOOKUP_URI}.
1663         */
1664        public static final class Data implements BaseColumns, DataColumns {
1665            /**
1666             * no public constructor since this is a utility class
1667             */
1668            private Data() {}
1669
1670            /**
1671             * The directory twig for this sub-table
1672             */
1673            public static final String CONTENT_DIRECTORY = "data";
1674        }
1675
1676        /**
1677         * <p>
1678         * A sub-directory of a contact that contains all of its
1679         * {@link ContactsContract.RawContacts} as well as
1680         * {@link ContactsContract.Data} rows. To access this directory append
1681         * {@link #CONTENT_DIRECTORY} to the contact URI.
1682         * </p>
1683         * <p>
1684         * Entity has three ID fields: {@link #CONTACT_ID} for the contact,
1685         * {@link #RAW_CONTACT_ID} for the raw contact and {@link #DATA_ID} for
1686         * the data rows. Entity always contains at least one row per
1687         * constituent raw contact, even if there are no actual data rows. In
1688         * this case the {@link #DATA_ID} field will be null.
1689         * </p>
1690         * <p>
1691         * Entity reads all data for the entire contact in one transaction, to
1692         * guarantee consistency.  There is significant data duplication
1693         * in the Entity (each row repeats all Contact columns and all RawContact
1694         * columns), so the benefits of transactional consistency should be weighed
1695         * against the cost of transferring large amounts of denormalized data
1696         * from the Provider.
1697         * </p>
1698         * <p>
1699         * To reduce the amount of data duplication the contacts provider and directory
1700         * providers implementing this protocol are allowed to provide common Contacts
1701         * and RawContacts fields in the first row returned for each raw contact only and
1702         * leave them as null in subsequent rows.
1703         * </p>
1704         */
1705        public static final class Entity implements BaseColumns, ContactsColumns,
1706                ContactNameColumns, RawContactsColumns, BaseSyncColumns, SyncColumns, DataColumns,
1707                StatusColumns, ContactOptionsColumns, ContactStatusColumns, DataUsageStatColumns {
1708            /**
1709             * no public constructor since this is a utility class
1710             */
1711            private Entity() {
1712            }
1713
1714            /**
1715             * The directory twig for this sub-table
1716             */
1717            public static final String CONTENT_DIRECTORY = "entities";
1718
1719            /**
1720             * The ID of the raw contact row.
1721             * <P>Type: INTEGER</P>
1722             */
1723            public static final String RAW_CONTACT_ID = "raw_contact_id";
1724
1725            /**
1726             * The ID of the data row. The value will be null if this raw contact has no
1727             * data rows.
1728             * <P>Type: INTEGER</P>
1729             */
1730            public static final String DATA_ID = "data_id";
1731        }
1732
1733        /**
1734         * <p>
1735         * A sub-directory of a single contact that contains all of the constituent raw contact
1736         * {@link ContactsContract.StreamItems} rows.  This directory can be used either
1737         * with a {@link #CONTENT_URI} or {@link #CONTENT_LOOKUP_URI}.
1738         * </p>
1739         * <p>
1740         * Querying for social stream data requires android.permission.READ_SOCIAL_STREAM
1741         * permission.
1742         * </p>
1743         *
1744         * @deprecated - Do not use. This will not be supported in the future. In the future,
1745         * cursors returned from related queries will be empty.
1746         */
1747        @Deprecated
1748        public static final class StreamItems implements StreamItemsColumns {
1749            /**
1750             * no public constructor since this is a utility class
1751             *
1752             * @deprecated - Do not use. This will not be supported in the future. In the future,
1753             * cursors returned from related queries will be empty.
1754             */
1755            @Deprecated
1756            private StreamItems() {}
1757
1758            /**
1759             * The directory twig for this sub-table
1760             *
1761             * @deprecated - Do not use. This will not be supported in the future. In the future,
1762             * cursors returned from related queries will be empty.
1763             */
1764            @Deprecated
1765            public static final String CONTENT_DIRECTORY = "stream_items";
1766        }
1767
1768        /**
1769         * <p>
1770         * A <i>read-only</i> sub-directory of a single contact aggregate that
1771         * contains all aggregation suggestions (other contacts). The
1772         * aggregation suggestions are computed based on approximate data
1773         * matches with this contact.
1774         * </p>
1775         * <p>
1776         * <i>Note: this query may be expensive! If you need to use it in bulk,
1777         * make sure the user experience is acceptable when the query runs for a
1778         * long time.</i>
1779         * <p>
1780         * Usage example:
1781         *
1782         * <pre>
1783         * Uri uri = Contacts.CONTENT_URI.buildUpon()
1784         *          .appendEncodedPath(String.valueOf(contactId))
1785         *          .appendPath(Contacts.AggregationSuggestions.CONTENT_DIRECTORY)
1786         *          .appendQueryParameter(&quot;limit&quot;, &quot;3&quot;)
1787         *          .build()
1788         * Cursor cursor = getContentResolver().query(suggestionsUri,
1789         *          new String[] {Contacts.DISPLAY_NAME, Contacts._ID, Contacts.LOOKUP_KEY},
1790         *          null, null, null);
1791         * </pre>
1792         *
1793         * </p>
1794         * <p>
1795         * This directory can be used either with a {@link #CONTENT_URI} or
1796         * {@link #CONTENT_LOOKUP_URI}.
1797         * </p>
1798         */
1799        public static final class AggregationSuggestions implements BaseColumns, ContactsColumns,
1800                ContactOptionsColumns, ContactStatusColumns {
1801            /**
1802             * No public constructor since this is a utility class
1803             */
1804            private AggregationSuggestions() {}
1805
1806            /**
1807             * The directory twig for this sub-table. The URI can be followed by an optional
1808             * type-to-filter, similar to
1809             * {@link android.provider.ContactsContract.Contacts#CONTENT_FILTER_URI}.
1810             */
1811            public static final String CONTENT_DIRECTORY = "suggestions";
1812
1813            /**
1814             * Used to specify what kind of data is supplied for the suggestion query.
1815             *
1816             * @hide
1817             */
1818            public static final String PARAMETER_MATCH_NAME = "name";
1819
1820            /**
1821             * A convenience builder for aggregation suggestion content URIs.
1822             */
1823            public static final class Builder {
1824                private long mContactId;
1825                private final ArrayList<String> mValues = new ArrayList<String>();
1826                private int mLimit;
1827
1828                /**
1829                 * Optional existing contact ID.  If it is not provided, the search
1830                 * will be based exclusively on the values supplied with {@link #addNameParameter}.
1831                 *
1832                 * @param contactId contact to find aggregation suggestions for
1833                 * @return This Builder object to allow for chaining of calls to builder methods
1834                 */
1835                public Builder setContactId(long contactId) {
1836                    this.mContactId = contactId;
1837                    return this;
1838                }
1839
1840                /**
1841                 * Add a name to be used when searching for aggregation suggestions.
1842                 *
1843                 * @param name name to find aggregation suggestions for
1844                 * @return This Builder object to allow for chaining of calls to builder methods
1845                 */
1846                public Builder addNameParameter(String name) {
1847                    mValues.add(name);
1848                    return this;
1849                }
1850
1851                /**
1852                 * Sets the Maximum number of suggested aggregations that should be returned.
1853                 * @param limit The maximum number of suggested aggregations
1854                 *
1855                 * @return This Builder object to allow for chaining of calls to builder methods
1856                 */
1857                public Builder setLimit(int limit) {
1858                    mLimit = limit;
1859                    return this;
1860                }
1861
1862                /**
1863                 * Combine all of the options that have been set and return a new {@link Uri}
1864                 * object for fetching aggregation suggestions.
1865                 */
1866                public Uri build() {
1867                    android.net.Uri.Builder builder = Contacts.CONTENT_URI.buildUpon();
1868                    builder.appendEncodedPath(String.valueOf(mContactId));
1869                    builder.appendPath(Contacts.AggregationSuggestions.CONTENT_DIRECTORY);
1870                    if (mLimit != 0) {
1871                        builder.appendQueryParameter("limit", String.valueOf(mLimit));
1872                    }
1873
1874                    int count = mValues.size();
1875                    for (int i = 0; i < count; i++) {
1876                        builder.appendQueryParameter("query", PARAMETER_MATCH_NAME
1877                                + ":" + mValues.get(i));
1878                    }
1879
1880                    return builder.build();
1881                }
1882            }
1883
1884            /**
1885             * @hide
1886             */
1887            public static final Builder builder() {
1888                return new Builder();
1889            }
1890        }
1891
1892        /**
1893         * A <i>read-only</i> sub-directory of a single contact that contains
1894         * the contact's primary photo.  The photo may be stored in up to two ways -
1895         * the default "photo" is a thumbnail-sized image stored directly in the data
1896         * row, while the "display photo", if present, is a larger version stored as
1897         * a file.
1898         * <p>
1899         * Usage example:
1900         * <dl>
1901         * <dt>Retrieving the thumbnail-sized photo</dt>
1902         * <dd>
1903         * <pre>
1904         * public InputStream openPhoto(long contactId) {
1905         *     Uri contactUri = ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId);
1906         *     Uri photoUri = Uri.withAppendedPath(contactUri, Contacts.Photo.CONTENT_DIRECTORY);
1907         *     Cursor cursor = getContentResolver().query(photoUri,
1908         *          new String[] {Contacts.Photo.PHOTO}, null, null, null);
1909         *     if (cursor == null) {
1910         *         return null;
1911         *     }
1912         *     try {
1913         *         if (cursor.moveToFirst()) {
1914         *             byte[] data = cursor.getBlob(0);
1915         *             if (data != null) {
1916         *                 return new ByteArrayInputStream(data);
1917         *             }
1918         *         }
1919         *     } finally {
1920         *         cursor.close();
1921         *     }
1922         *     return null;
1923         * }
1924         * </pre>
1925         * </dd>
1926         * <dt>Retrieving the larger photo version</dt>
1927         * <dd>
1928         * <pre>
1929         * public InputStream openDisplayPhoto(long contactId) {
1930         *     Uri contactUri = ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId);
1931         *     Uri displayPhotoUri = Uri.withAppendedPath(contactUri, Contacts.Photo.DISPLAY_PHOTO);
1932         *     try {
1933         *         AssetFileDescriptor fd =
1934         *             getContentResolver().openAssetFileDescriptor(displayPhotoUri, "r");
1935         *         return fd.createInputStream();
1936         *     } catch (IOException e) {
1937         *         return null;
1938         *     }
1939         * }
1940         * </pre>
1941         * </dd>
1942         * </dl>
1943         *
1944         * </p>
1945         * <p>You may also consider using the convenience method
1946         * {@link ContactsContract.Contacts#openContactPhotoInputStream(ContentResolver, Uri, boolean)}
1947         * to retrieve the raw photo contents of either the thumbnail-sized or the full-sized photo.
1948         * </p>
1949         * <p>
1950         * This directory can be used either with a {@link #CONTENT_URI} or
1951         * {@link #CONTENT_LOOKUP_URI}.
1952         * </p>
1953         */
1954        public static final class Photo implements BaseColumns, DataColumnsWithJoins {
1955            /**
1956             * no public constructor since this is a utility class
1957             */
1958            private Photo() {}
1959
1960            /**
1961             * The directory twig for this sub-table
1962             */
1963            public static final String CONTENT_DIRECTORY = "photo";
1964
1965            /**
1966             * The directory twig for retrieving the full-size display photo.
1967             */
1968            public static final String DISPLAY_PHOTO = "display_photo";
1969
1970            /**
1971             * Full-size photo file ID of the raw contact.
1972             * See {@link ContactsContract.DisplayPhoto}.
1973             * <p>
1974             * Type: NUMBER
1975             */
1976            public static final String PHOTO_FILE_ID = DATA14;
1977
1978            /**
1979             * Thumbnail photo of the raw contact. This is the raw bytes of an image
1980             * that could be inflated using {@link android.graphics.BitmapFactory}.
1981             * <p>
1982             * Type: BLOB
1983             */
1984            public static final String PHOTO = DATA15;
1985        }
1986
1987        /**
1988         * Opens an InputStream for the contacts's photo and returns the
1989         * photo as a byte stream.
1990         * @param cr The content resolver to use for querying
1991         * @param contactUri the contact whose photo should be used. This can be used with
1992         * either a {@link #CONTENT_URI} or a {@link #CONTENT_LOOKUP_URI} URI.
1993         * @param preferHighres If this is true and the contact has a higher resolution photo
1994         * available, it is returned. If false, this function always tries to get the thumbnail
1995         * @return an InputStream of the photo, or null if no photo is present
1996         */
1997        public static InputStream openContactPhotoInputStream(ContentResolver cr, Uri contactUri,
1998                boolean preferHighres) {
1999            if (preferHighres) {
2000                final Uri displayPhotoUri = Uri.withAppendedPath(contactUri,
2001                        Contacts.Photo.DISPLAY_PHOTO);
2002                InputStream inputStream;
2003                try {
2004                    AssetFileDescriptor fd = cr.openAssetFileDescriptor(displayPhotoUri, "r");
2005                    return fd.createInputStream();
2006                } catch (IOException e) {
2007                    // fallback to the thumbnail code
2008                }
2009           }
2010
2011            Uri photoUri = Uri.withAppendedPath(contactUri, Photo.CONTENT_DIRECTORY);
2012            if (photoUri == null) {
2013                return null;
2014            }
2015            Cursor cursor = cr.query(photoUri,
2016                    new String[] {
2017                        ContactsContract.CommonDataKinds.Photo.PHOTO
2018                    }, null, null, null);
2019            try {
2020                if (cursor == null || !cursor.moveToNext()) {
2021                    return null;
2022                }
2023                byte[] data = cursor.getBlob(0);
2024                if (data == null) {
2025                    return null;
2026                }
2027                return new ByteArrayInputStream(data);
2028            } finally {
2029                if (cursor != null) {
2030                    cursor.close();
2031                }
2032            }
2033        }
2034
2035        /**
2036         * Opens an InputStream for the contacts's thumbnail photo and returns the
2037         * photo as a byte stream.
2038         * @param cr The content resolver to use for querying
2039         * @param contactUri the contact whose photo should be used. This can be used with
2040         * either a {@link #CONTENT_URI} or a {@link #CONTENT_LOOKUP_URI} URI.
2041         * @return an InputStream of the photo, or null if no photo is present
2042         * @see #openContactPhotoInputStream(ContentResolver, Uri, boolean), if instead
2043         * of the thumbnail the high-res picture is preferred
2044         */
2045        public static InputStream openContactPhotoInputStream(ContentResolver cr, Uri contactUri) {
2046            return openContactPhotoInputStream(cr, contactUri, false);
2047        }
2048    }
2049
2050    /**
2051     * <p>
2052     * Constants for the user's profile data, which is represented as a single contact on
2053     * the device that represents the user.  The profile contact is not aggregated
2054     * together automatically in the same way that normal contacts are; instead, each
2055     * account (including data set, if applicable) on the device may contribute a single
2056     * raw contact representing the user's personal profile data from that source.
2057     * </p>
2058     * <p>
2059     * Access to the profile entry through these URIs (or incidental access to parts of
2060     * the profile if retrieved directly via ID) requires additional permissions beyond
2061     * the read/write contact permissions required by the provider.  Querying for profile
2062     * data requires android.permission.READ_PROFILE permission, and inserting or
2063     * updating profile data requires android.permission.WRITE_PROFILE permission.
2064     * </p>
2065     * <h3>Operations</h3>
2066     * <dl>
2067     * <dt><b>Insert</b></dt>
2068     * <dd>The user's profile entry cannot be created explicitly (attempting to do so
2069     * will throw an exception). When a raw contact is inserted into the profile, the
2070     * provider will check for the existence of a profile on the device.  If one is
2071     * found, the raw contact's {@link RawContacts#CONTACT_ID} column gets the _ID of
2072     * the profile Contact. If no match is found, the profile Contact is created and
2073     * its _ID is put into the {@link RawContacts#CONTACT_ID} column of the newly
2074     * inserted raw contact.</dd>
2075     * <dt><b>Update</b></dt>
2076     * <dd>The profile Contact has the same update restrictions as Contacts in general,
2077     * but requires the android.permission.WRITE_PROFILE permission.</dd>
2078     * <dt><b>Delete</b></dt>
2079     * <dd>The profile Contact cannot be explicitly deleted.  It will be removed
2080     * automatically if all of its constituent raw contact entries are deleted.</dd>
2081     * <dt><b>Query</b></dt>
2082     * <dd>
2083     * <ul>
2084     * <li>The {@link #CONTENT_URI} for profiles behaves in much the same way as
2085     * retrieving a contact by ID, except that it will only ever return the user's
2086     * profile contact.
2087     * </li>
2088     * <li>
2089     * The profile contact supports all of the same sub-paths as an individual contact
2090     * does - the content of the profile contact can be retrieved as entities or
2091     * data rows.  Similarly, specific raw contact entries can be retrieved by appending
2092     * the desired raw contact ID within the profile.
2093     * </li>
2094     * </ul>
2095     * </dd>
2096     * </dl>
2097     */
2098    public static final class Profile implements BaseColumns, ContactsColumns,
2099            ContactOptionsColumns, ContactNameColumns, ContactStatusColumns {
2100        /**
2101         * This utility class cannot be instantiated
2102         */
2103        private Profile() {
2104        }
2105
2106        /**
2107         * The content:// style URI for this table, which requests the contact entry
2108         * representing the user's personal profile data.
2109         */
2110        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "profile");
2111
2112        /**
2113         * {@link Uri} for referencing the user's profile {@link Contacts} entry,
2114         * Provides {@link OpenableColumns} columns when queried, or returns the
2115         * user's profile contact formatted as a vCard when opened through
2116         * {@link ContentResolver#openAssetFileDescriptor(Uri, String)}.
2117         */
2118        public static final Uri CONTENT_VCARD_URI = Uri.withAppendedPath(CONTENT_URI,
2119                "as_vcard");
2120
2121        /**
2122         * {@link Uri} for referencing the raw contacts that make up the user's profile
2123         * {@link Contacts} entry.  An individual raw contact entry within the profile
2124         * can be addressed by appending the raw contact ID.  The entities or data within
2125         * that specific raw contact can be requested by appending the entity or data
2126         * path as well.
2127         */
2128        public static final Uri CONTENT_RAW_CONTACTS_URI = Uri.withAppendedPath(CONTENT_URI,
2129                "raw_contacts");
2130
2131        /**
2132         * The minimum ID for any entity that belongs to the profile.  This essentially
2133         * defines an ID-space in which profile data is stored, and is used by the provider
2134         * to determine whether a request via a non-profile-specific URI should be directed
2135         * to the profile data rather than general contacts data, along with all the special
2136         * permission checks that entails.
2137         *
2138         * Callers may use {@link #isProfileId} to check whether a specific ID falls into
2139         * the set of data intended for the profile.
2140         */
2141        public static final long MIN_ID = Long.MAX_VALUE - (long) Integer.MAX_VALUE;
2142    }
2143
2144    /**
2145     * This method can be used to identify whether the given ID is associated with profile
2146     * data.  It does not necessarily indicate that the ID is tied to valid data, merely
2147     * that accessing data using this ID will result in profile access checks and will only
2148     * return data from the profile.
2149     *
2150     * @param id The ID to check.
2151     * @return Whether the ID is associated with profile data.
2152     */
2153    public static boolean isProfileId(long id) {
2154        return id >= Profile.MIN_ID;
2155    }
2156
2157    protected interface DeletedContactsColumns {
2158
2159        /**
2160         * A reference to the {@link ContactsContract.Contacts#_ID} that was deleted.
2161         * <P>Type: INTEGER</P>
2162         */
2163        public static final String CONTACT_ID = "contact_id";
2164
2165        /**
2166         * Time (milliseconds since epoch) that the contact was deleted.
2167         */
2168        public static final String CONTACT_DELETED_TIMESTAMP = "contact_deleted_timestamp";
2169    }
2170
2171    /**
2172     * Constants for the deleted contact table.  This table holds a log of deleted contacts.
2173     * <p>
2174     * Log older than {@link #DAYS_KEPT_MILLISECONDS} may be deleted.
2175     */
2176    public static final class DeletedContacts implements DeletedContactsColumns {
2177
2178        /**
2179         * This utility class cannot be instantiated
2180         */
2181        private DeletedContacts() {
2182        }
2183
2184        /**
2185         * The content:// style URI for this table, which requests a directory of raw contact rows
2186         * matching the selection criteria.
2187         */
2188        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI,
2189                "deleted_contacts");
2190
2191        /**
2192         * Number of days that the delete log will be kept.  After this time, delete records may be
2193         * deleted.
2194         *
2195         * @hide
2196         */
2197        private static final int DAYS_KEPT = 30;
2198
2199        /**
2200         * Milliseconds that the delete log will be kept.  After this time, delete records may be
2201         * deleted.
2202         */
2203        public static final long DAYS_KEPT_MILLISECONDS = 1000L * 60L * 60L * 24L * (long)DAYS_KEPT;
2204    }
2205
2206    protected interface RawContactsColumns {
2207        /**
2208         * A reference to the {@link ContactsContract.Contacts#_ID} that this
2209         * data belongs to.
2210         * <P>Type: INTEGER</P>
2211         */
2212        public static final String CONTACT_ID = "contact_id";
2213
2214        /**
2215         * Persistent unique id for each raw_contact within its account.
2216         * This id is provided by its own data source, and can be used to backup metadata
2217         * to the server.
2218         * This should be unique within each set of account_name/account_type/data_set
2219         *
2220         * @hide
2221         */
2222        public static final String BACKUP_ID = "backup_id";
2223
2224        /**
2225         * The data set within the account that this row belongs to.  This allows
2226         * multiple sync adapters for the same account type to distinguish between
2227         * each others' data.
2228         *
2229         * This is empty by default, and is completely optional.  It only needs to
2230         * be populated if multiple sync adapters are entering distinct data for
2231         * the same account type and account name.
2232         * <P>Type: TEXT</P>
2233         */
2234        public static final String DATA_SET = "data_set";
2235
2236        /**
2237         * A concatenation of the account type and data set (delimited by a forward
2238         * slash) - if the data set is empty, this will be the same as the account
2239         * type.  For applications that need to be aware of the data set, this can
2240         * be used instead of account type to distinguish sets of data.  This is
2241         * never intended to be used for specifying accounts.
2242         * <p>
2243         * This column does *not* escape forward slashes in the account type or the data set.
2244         * If this is an issue, consider using
2245         * {@link ContactsContract.RawContacts#ACCOUNT_TYPE} and
2246         * {@link ContactsContract.RawContacts#DATA_SET} directly.
2247         */
2248        public static final String ACCOUNT_TYPE_AND_DATA_SET = "account_type_and_data_set";
2249
2250        /**
2251         * The aggregation mode for this contact.
2252         * <P>Type: INTEGER</P>
2253         */
2254        public static final String AGGREGATION_MODE = "aggregation_mode";
2255
2256        /**
2257         * The "deleted" flag: "0" by default, "1" if the row has been marked
2258         * for deletion. When {@link android.content.ContentResolver#delete} is
2259         * called on a raw contact, it is marked for deletion and removed from its
2260         * aggregate contact. The sync adaptor deletes the raw contact on the server and
2261         * then calls ContactResolver.delete once more, this time passing the
2262         * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to finalize
2263         * the data removal.
2264         * <P>Type: INTEGER</P>
2265         */
2266        public static final String DELETED = "deleted";
2267
2268        /**
2269         * The "read-only" flag: "0" by default, "1" if the row cannot be modified or
2270         * deleted except by a sync adapter.  See {@link ContactsContract#CALLER_IS_SYNCADAPTER}.
2271         * <P>Type: INTEGER</P>
2272         */
2273        public static final String RAW_CONTACT_IS_READ_ONLY = "raw_contact_is_read_only";
2274
2275        /**
2276         * Flag that reflects whether this raw contact belongs to the user's
2277         * personal profile entry.
2278         */
2279        public static final String RAW_CONTACT_IS_USER_PROFILE = "raw_contact_is_user_profile";
2280
2281        /**
2282         * Flag indicating that a raw contact's metadata has changed, and its metadata
2283         * needs to be synchronized by the server.
2284         * <P>Type: INTEGER (boolean)</P>
2285         */
2286        public static final String METADATA_DIRTY = "metadata_dirty";
2287    }
2288
2289    /**
2290     * Constants for the raw contacts table, which contains one row of contact
2291     * information for each person in each synced account. Sync adapters and
2292     * contact management apps
2293     * are the primary consumers of this API.
2294     *
2295     * <h3>Aggregation</h3>
2296     * <p>
2297     * As soon as a raw contact is inserted or whenever its constituent data
2298     * changes, the provider will check if the raw contact matches other
2299     * existing raw contacts and if so will aggregate it with those. The
2300     * aggregation is reflected in the {@link RawContacts} table by the change of the
2301     * {@link #CONTACT_ID} field, which is the reference to the aggregate contact.
2302     * </p>
2303     * <p>
2304     * Changes to the structured name, organization, phone number, email address,
2305     * or nickname trigger a re-aggregation.
2306     * </p>
2307     * <p>
2308     * See also {@link AggregationExceptions} for a mechanism to control
2309     * aggregation programmatically.
2310     * </p>
2311     *
2312     * <h3>Operations</h3>
2313     * <dl>
2314     * <dt><b>Insert</b></dt>
2315     * <dd>
2316     * <p>
2317     * Raw contacts can be inserted incrementally or in a batch.
2318     * The incremental method is more traditional but less efficient.
2319     * It should be used
2320     * only if no {@link Data} values are available at the time the raw contact is created:
2321     * <pre>
2322     * ContentValues values = new ContentValues();
2323     * values.put(RawContacts.ACCOUNT_TYPE, accountType);
2324     * values.put(RawContacts.ACCOUNT_NAME, accountName);
2325     * Uri rawContactUri = getContentResolver().insert(RawContacts.CONTENT_URI, values);
2326     * long rawContactId = ContentUris.parseId(rawContactUri);
2327     * </pre>
2328     * </p>
2329     * <p>
2330     * Once {@link Data} values become available, insert those.
2331     * For example, here's how you would insert a name:
2332     *
2333     * <pre>
2334     * values.clear();
2335     * values.put(Data.RAW_CONTACT_ID, rawContactId);
2336     * values.put(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE);
2337     * values.put(StructuredName.DISPLAY_NAME, &quot;Mike Sullivan&quot;);
2338     * getContentResolver().insert(Data.CONTENT_URI, values);
2339     * </pre>
2340     * </p>
2341     * <p>
2342     * The batch method is by far preferred.  It inserts the raw contact and its
2343     * constituent data rows in a single database transaction
2344     * and causes at most one aggregation pass.
2345     * <pre>
2346     * ArrayList&lt;ContentProviderOperation&gt; ops =
2347     *          new ArrayList&lt;ContentProviderOperation&gt;();
2348     * ...
2349     * int rawContactInsertIndex = ops.size();
2350     * ops.add(ContentProviderOperation.newInsert(RawContacts.CONTENT_URI)
2351     *          .withValue(RawContacts.ACCOUNT_TYPE, accountType)
2352     *          .withValue(RawContacts.ACCOUNT_NAME, accountName)
2353     *          .build());
2354     *
2355     * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
2356     *          .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex)
2357     *          .withValue(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE)
2358     *          .withValue(StructuredName.DISPLAY_NAME, &quot;Mike Sullivan&quot;)
2359     *          .build());
2360     *
2361     * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
2362     * </pre>
2363     * </p>
2364     * <p>
2365     * Note the use of {@link ContentProviderOperation.Builder#withValueBackReference(String, int)}
2366     * to refer to the as-yet-unknown index value of the raw contact inserted in the
2367     * first operation.
2368     * </p>
2369     *
2370     * <dt><b>Update</b></dt>
2371     * <dd><p>
2372     * Raw contacts can be updated incrementally or in a batch.
2373     * Batch mode should be used whenever possible.
2374     * The procedures and considerations are analogous to those documented above for inserts.
2375     * </p></dd>
2376     * <dt><b>Delete</b></dt>
2377     * <dd><p>When a raw contact is deleted, all of its Data rows as well as StatusUpdates,
2378     * AggregationExceptions, PhoneLookup rows are deleted automatically. When all raw
2379     * contacts associated with a {@link Contacts} row are deleted, the {@link Contacts} row
2380     * itself is also deleted automatically.
2381     * </p>
2382     * <p>
2383     * The invocation of {@code resolver.delete(...)}, does not immediately delete
2384     * a raw contacts row.
2385     * Instead, it sets the {@link #DELETED} flag on the raw contact and
2386     * removes the raw contact from its aggregate contact.
2387     * The sync adapter then deletes the raw contact from the server and
2388     * finalizes phone-side deletion by calling {@code resolver.delete(...)}
2389     * again and passing the {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter.<p>
2390     * <p>Some sync adapters are read-only, meaning that they only sync server-side
2391     * changes to the phone, but not the reverse.  If one of those raw contacts
2392     * is marked for deletion, it will remain on the phone.  However it will be
2393     * effectively invisible, because it will not be part of any aggregate contact.
2394     * </dd>
2395     *
2396     * <dt><b>Query</b></dt>
2397     * <dd>
2398     * <p>
2399     * It is easy to find all raw contacts in a Contact:
2400     * <pre>
2401     * Cursor c = getContentResolver().query(RawContacts.CONTENT_URI,
2402     *          new String[]{RawContacts._ID},
2403     *          RawContacts.CONTACT_ID + "=?",
2404     *          new String[]{String.valueOf(contactId)}, null);
2405     * </pre>
2406     * </p>
2407     * <p>
2408     * To find raw contacts within a specific account,
2409     * you can either put the account name and type in the selection or pass them as query
2410     * parameters.  The latter approach is preferable, especially when you can reuse the
2411     * URI:
2412     * <pre>
2413     * Uri rawContactUri = RawContacts.CONTENT_URI.buildUpon()
2414     *          .appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName)
2415     *          .appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType)
2416     *          .build();
2417     * Cursor c1 = getContentResolver().query(rawContactUri,
2418     *          RawContacts.STARRED + "&lt;&gt;0", null, null, null);
2419     * ...
2420     * Cursor c2 = getContentResolver().query(rawContactUri,
2421     *          RawContacts.DELETED + "&lt;&gt;0", null, null, null);
2422     * </pre>
2423     * </p>
2424     * <p>The best way to read a raw contact along with all the data associated with it is
2425     * by using the {@link Entity} directory. If the raw contact has data rows,
2426     * the Entity cursor will contain a row for each data row.  If the raw contact has no
2427     * data rows, the cursor will still contain one row with the raw contact-level information.
2428     * <pre>
2429     * Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactId);
2430     * Uri entityUri = Uri.withAppendedPath(rawContactUri, Entity.CONTENT_DIRECTORY);
2431     * Cursor c = getContentResolver().query(entityUri,
2432     *          new String[]{RawContacts.SOURCE_ID, Entity.DATA_ID, Entity.MIMETYPE, Entity.DATA1},
2433     *          null, null, null);
2434     * try {
2435     *     while (c.moveToNext()) {
2436     *         String sourceId = c.getString(0);
2437     *         if (!c.isNull(1)) {
2438     *             String mimeType = c.getString(2);
2439     *             String data = c.getString(3);
2440     *             ...
2441     *         }
2442     *     }
2443     * } finally {
2444     *     c.close();
2445     * }
2446     * </pre>
2447     * </p>
2448     * </dd>
2449     * </dl>
2450     * <h2>Columns</h2>
2451     *
2452     * <table class="jd-sumtable">
2453     * <tr>
2454     * <th colspan='4'>RawContacts</th>
2455     * </tr>
2456     * <tr>
2457     * <td>long</td>
2458     * <td>{@link #_ID}</td>
2459     * <td>read-only</td>
2460     * <td>Row ID. Sync adapters should try to preserve row IDs during updates. In other words,
2461     * it is much better for a sync adapter to update a raw contact rather than to delete and
2462     * re-insert it.</td>
2463     * </tr>
2464     * <tr>
2465     * <td>long</td>
2466     * <td>{@link #CONTACT_ID}</td>
2467     * <td>read-only</td>
2468     * <td>The ID of the row in the {@link ContactsContract.Contacts} table
2469     * that this raw contact belongs
2470     * to. Raw contacts are linked to contacts by the aggregation process, which can be controlled
2471     * by the {@link #AGGREGATION_MODE} field and {@link AggregationExceptions}.</td>
2472     * </tr>
2473     * <tr>
2474     * <td>int</td>
2475     * <td>{@link #AGGREGATION_MODE}</td>
2476     * <td>read/write</td>
2477     * <td>A mechanism that allows programmatic control of the aggregation process. The allowed
2478     * values are {@link #AGGREGATION_MODE_DEFAULT}, {@link #AGGREGATION_MODE_DISABLED}
2479     * and {@link #AGGREGATION_MODE_SUSPENDED}. See also {@link AggregationExceptions}.</td>
2480     * </tr>
2481     * <tr>
2482     * <td>int</td>
2483     * <td>{@link #DELETED}</td>
2484     * <td>read/write</td>
2485     * <td>The "deleted" flag: "0" by default, "1" if the row has been marked
2486     * for deletion. When {@link android.content.ContentResolver#delete} is
2487     * called on a raw contact, it is marked for deletion and removed from its
2488     * aggregate contact. The sync adaptor deletes the raw contact on the server and
2489     * then calls ContactResolver.delete once more, this time passing the
2490     * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to finalize
2491     * the data removal.</td>
2492     * </tr>
2493     * <tr>
2494     * <td>int</td>
2495     * <td>{@link #TIMES_CONTACTED}</td>
2496     * <td>read/write</td>
2497     * <td>The number of times the contact has been contacted. To have an effect
2498     * on the corresponding value of the aggregate contact, this field
2499     * should be set at the time the raw contact is inserted.
2500     * After that, this value is typically updated via
2501     * {@link ContactsContract.Contacts#markAsContacted}.</td>
2502     * </tr>
2503     * <tr>
2504     * <td>long</td>
2505     * <td>{@link #LAST_TIME_CONTACTED}</td>
2506     * <td>read/write</td>
2507     * <td>The timestamp of the last time the contact was contacted. To have an effect
2508     * on the corresponding value of the aggregate contact, this field
2509     * should be set at the time the raw contact is inserted.
2510     * After that, this value is typically updated via
2511     * {@link ContactsContract.Contacts#markAsContacted}.
2512     * </td>
2513     * </tr>
2514     * <tr>
2515     * <td>int</td>
2516     * <td>{@link #STARRED}</td>
2517     * <td>read/write</td>
2518     * <td>An indicator for favorite contacts: '1' if favorite, '0' otherwise.
2519     * Changing this field immediately affects the corresponding aggregate contact:
2520     * if any raw contacts in that aggregate contact are starred, then the contact
2521     * itself is marked as starred.</td>
2522     * </tr>
2523     * <tr>
2524     * <td>String</td>
2525     * <td>{@link #CUSTOM_RINGTONE}</td>
2526     * <td>read/write</td>
2527     * <td>A custom ringtone associated with a raw contact. Typically this is the
2528     * URI returned by an activity launched with the
2529     * {@link android.media.RingtoneManager#ACTION_RINGTONE_PICKER} intent.
2530     * To have an effect on the corresponding value of the aggregate contact, this field
2531     * should be set at the time the raw contact is inserted. To set a custom
2532     * ringtone on a contact, use the field {@link ContactsContract.Contacts#CUSTOM_RINGTONE
2533     * Contacts.CUSTOM_RINGTONE}
2534     * instead.</td>
2535     * </tr>
2536     * <tr>
2537     * <td>int</td>
2538     * <td>{@link #SEND_TO_VOICEMAIL}</td>
2539     * <td>read/write</td>
2540     * <td>An indicator of whether calls from this raw contact should be forwarded
2541     * directly to voice mail ('1') or not ('0'). To have an effect
2542     * on the corresponding value of the aggregate contact, this field
2543     * should be set at the time the raw contact is inserted.</td>
2544     * </tr>
2545     * <tr>
2546     * <td>String</td>
2547     * <td>{@link #ACCOUNT_NAME}</td>
2548     * <td>read/write-once</td>
2549     * <td>The name of the account instance to which this row belongs, which when paired with
2550     * {@link #ACCOUNT_TYPE} identifies a specific account.
2551     * For example, this will be the Gmail address if it is a Google account.
2552     * It should be set at the time the raw contact is inserted and never
2553     * changed afterwards.</td>
2554     * </tr>
2555     * <tr>
2556     * <td>String</td>
2557     * <td>{@link #ACCOUNT_TYPE}</td>
2558     * <td>read/write-once</td>
2559     * <td>
2560     * <p>
2561     * The type of account to which this row belongs, which when paired with
2562     * {@link #ACCOUNT_NAME} identifies a specific account.
2563     * It should be set at the time the raw contact is inserted and never
2564     * changed afterwards.
2565     * </p>
2566     * <p>
2567     * To ensure uniqueness, new account types should be chosen according to the
2568     * Java package naming convention.  Thus a Google account is of type "com.google".
2569     * </p>
2570     * </td>
2571     * </tr>
2572     * <tr>
2573     * <td>String</td>
2574     * <td>{@link #DATA_SET}</td>
2575     * <td>read/write-once</td>
2576     * <td>
2577     * <p>
2578     * The data set within the account that this row belongs to.  This allows
2579     * multiple sync adapters for the same account type to distinguish between
2580     * each others' data.  The combination of {@link #ACCOUNT_TYPE},
2581     * {@link #ACCOUNT_NAME}, and {@link #DATA_SET} identifies a set of data
2582     * that is associated with a single sync adapter.
2583     * </p>
2584     * <p>
2585     * This is empty by default, and is completely optional.  It only needs to
2586     * be populated if multiple sync adapters are entering distinct data for
2587     * the same account type and account name.
2588     * </p>
2589     * <p>
2590     * It should be set at the time the raw contact is inserted and never
2591     * changed afterwards.
2592     * </p>
2593     * </td>
2594     * </tr>
2595     * <tr>
2596     * <td>String</td>
2597     * <td>{@link #SOURCE_ID}</td>
2598     * <td>read/write</td>
2599     * <td>String that uniquely identifies this row to its source account.
2600     * Typically it is set at the time the raw contact is inserted and never
2601     * changed afterwards. The one notable exception is a new raw contact: it
2602     * will have an account name and type (and possibly a data set), but no
2603     * source id. This indicates to the sync adapter that a new contact needs
2604     * to be created server-side and its ID stored in the corresponding
2605     * SOURCE_ID field on the phone.
2606     * </td>
2607     * </tr>
2608     * <tr>
2609     * <td>int</td>
2610     * <td>{@link #VERSION}</td>
2611     * <td>read-only</td>
2612     * <td>Version number that is updated whenever this row or its related data
2613     * changes. This field can be used for optimistic locking of a raw contact.
2614     * </td>
2615     * </tr>
2616     * <tr>
2617     * <td>int</td>
2618     * <td>{@link #DIRTY}</td>
2619     * <td>read/write</td>
2620     * <td>Flag indicating that {@link #VERSION} has changed, and this row needs
2621     * to be synchronized by its owning account.  The value is set to "1" automatically
2622     * whenever the raw contact changes, unless the URI has the
2623     * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter specified.
2624     * The sync adapter should always supply this query parameter to prevent
2625     * unnecessary synchronization: user changes some data on the server,
2626     * the sync adapter updates the contact on the phone (without the
2627     * CALLER_IS_SYNCADAPTER flag) flag, which sets the DIRTY flag,
2628     * which triggers a sync to bring the changes to the server.
2629     * </td>
2630     * </tr>
2631     * <tr>
2632     * <td>String</td>
2633     * <td>{@link #SYNC1}</td>
2634     * <td>read/write</td>
2635     * <td>Generic column provided for arbitrary use by sync adapters.
2636     * The content provider
2637     * stores this information on behalf of the sync adapter but does not
2638     * interpret it in any way.
2639     * </td>
2640     * </tr>
2641     * <tr>
2642     * <td>String</td>
2643     * <td>{@link #SYNC2}</td>
2644     * <td>read/write</td>
2645     * <td>Generic column for use by sync adapters.
2646     * </td>
2647     * </tr>
2648     * <tr>
2649     * <td>String</td>
2650     * <td>{@link #SYNC3}</td>
2651     * <td>read/write</td>
2652     * <td>Generic column for use by sync adapters.
2653     * </td>
2654     * </tr>
2655     * <tr>
2656     * <td>String</td>
2657     * <td>{@link #SYNC4}</td>
2658     * <td>read/write</td>
2659     * <td>Generic column for use by sync adapters.
2660     * </td>
2661     * </tr>
2662     * </table>
2663     */
2664    public static final class RawContacts implements BaseColumns, RawContactsColumns,
2665            ContactOptionsColumns, ContactNameColumns, SyncColumns  {
2666        /**
2667         * This utility class cannot be instantiated
2668         */
2669        private RawContacts() {
2670        }
2671
2672        /**
2673         * The content:// style URI for this table, which requests a directory of
2674         * raw contact rows matching the selection criteria.
2675         */
2676        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "raw_contacts");
2677
2678        /**
2679         * The MIME type of the results from {@link #CONTENT_URI} when a specific
2680         * ID value is not provided, and multiple raw contacts may be returned.
2681         */
2682        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/raw_contact";
2683
2684        /**
2685         * The MIME type of the results when a raw contact ID is appended to {@link #CONTENT_URI},
2686         * yielding a subdirectory of a single person.
2687         */
2688        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/raw_contact";
2689
2690        /**
2691         * Aggregation mode: aggregate immediately after insert or update operation(s) are complete.
2692         */
2693        public static final int AGGREGATION_MODE_DEFAULT = 0;
2694
2695        /**
2696         * Aggregation mode: aggregate at the time the raw contact is inserted/updated.
2697         * @deprecated Aggregation is synchronous, this historic value is a no-op
2698         */
2699        @Deprecated
2700        public static final int AGGREGATION_MODE_IMMEDIATE = 1;
2701
2702        /**
2703         * <p>
2704         * Aggregation mode: aggregation suspended temporarily, and is likely to be resumed later.
2705         * Changes to the raw contact will update the associated aggregate contact but will not
2706         * result in any change in how the contact is aggregated. Similar to
2707         * {@link #AGGREGATION_MODE_DISABLED}, but maintains a link to the corresponding
2708         * {@link Contacts} aggregate.
2709         * </p>
2710         * <p>
2711         * This can be used to postpone aggregation until after a series of updates, for better
2712         * performance and/or user experience.
2713         * </p>
2714         * <p>
2715         * Note that changing
2716         * {@link #AGGREGATION_MODE} from {@link #AGGREGATION_MODE_SUSPENDED} to
2717         * {@link #AGGREGATION_MODE_DEFAULT} does not trigger an aggregation pass, but any
2718         * subsequent
2719         * change to the raw contact's data will.
2720         * </p>
2721         */
2722        public static final int AGGREGATION_MODE_SUSPENDED = 2;
2723
2724        /**
2725         * <p>
2726         * Aggregation mode: never aggregate this raw contact.  The raw contact will not
2727         * have a corresponding {@link Contacts} aggregate and therefore will not be included in
2728         * {@link Contacts} query results.
2729         * </p>
2730         * <p>
2731         * For example, this mode can be used for a raw contact that is marked for deletion while
2732         * waiting for the deletion to occur on the server side.
2733         * </p>
2734         *
2735         * @see #AGGREGATION_MODE_SUSPENDED
2736         */
2737        public static final int AGGREGATION_MODE_DISABLED = 3;
2738
2739        /**
2740         * Build a {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}
2741         * style {@link Uri} for the parent {@link android.provider.ContactsContract.Contacts}
2742         * entry of the given {@link RawContacts} entry.
2743         */
2744        public static Uri getContactLookupUri(ContentResolver resolver, Uri rawContactUri) {
2745            // TODO: use a lighter query by joining rawcontacts with contacts in provider
2746            final Uri dataUri = Uri.withAppendedPath(rawContactUri, Data.CONTENT_DIRECTORY);
2747            final Cursor cursor = resolver.query(dataUri, new String[] {
2748                    RawContacts.CONTACT_ID, Contacts.LOOKUP_KEY
2749            }, null, null, null);
2750
2751            Uri lookupUri = null;
2752            try {
2753                if (cursor != null && cursor.moveToFirst()) {
2754                    final long contactId = cursor.getLong(0);
2755                    final String lookupKey = cursor.getString(1);
2756                    return Contacts.getLookupUri(contactId, lookupKey);
2757                }
2758            } finally {
2759                if (cursor != null) cursor.close();
2760            }
2761            return lookupUri;
2762        }
2763
2764        /**
2765         * A sub-directory of a single raw contact that contains all of its
2766         * {@link ContactsContract.Data} rows. To access this directory
2767         * append {@link Data#CONTENT_DIRECTORY} to the raw contact URI.
2768         */
2769        public static final class Data implements BaseColumns, DataColumns {
2770            /**
2771             * no public constructor since this is a utility class
2772             */
2773            private Data() {
2774            }
2775
2776            /**
2777             * The directory twig for this sub-table
2778             */
2779            public static final String CONTENT_DIRECTORY = "data";
2780        }
2781
2782        /**
2783         * <p>
2784         * A sub-directory of a single raw contact that contains all of its
2785         * {@link ContactsContract.Data} rows. To access this directory append
2786         * {@link RawContacts.Entity#CONTENT_DIRECTORY} to the raw contact URI. See
2787         * {@link RawContactsEntity} for a stand-alone table containing the same
2788         * data.
2789         * </p>
2790         * <p>
2791         * Entity has two ID fields: {@link #_ID} for the raw contact
2792         * and {@link #DATA_ID} for the data rows.
2793         * Entity always contains at least one row, even if there are no
2794         * actual data rows. In this case the {@link #DATA_ID} field will be
2795         * null.
2796         * </p>
2797         * <p>
2798         * Using Entity should be preferred to using two separate queries:
2799         * RawContacts followed by Data. The reason is that Entity reads all
2800         * data for a raw contact in one transaction, so there is no possibility
2801         * of the data changing between the two queries.
2802         */
2803        public static final class Entity implements BaseColumns, DataColumns {
2804            /**
2805             * no public constructor since this is a utility class
2806             */
2807            private Entity() {
2808            }
2809
2810            /**
2811             * The directory twig for this sub-table
2812             */
2813            public static final String CONTENT_DIRECTORY = "entity";
2814
2815            /**
2816             * The ID of the data row. The value will be null if this raw contact has no
2817             * data rows.
2818             * <P>Type: INTEGER</P>
2819             */
2820            public static final String DATA_ID = "data_id";
2821        }
2822
2823        /**
2824         * <p>
2825         * A sub-directory of a single raw contact that contains all of its
2826         * {@link ContactsContract.StreamItems} rows. To access this directory append
2827         * {@link RawContacts.StreamItems#CONTENT_DIRECTORY} to the raw contact URI. See
2828         * {@link ContactsContract.StreamItems} for a stand-alone table containing the
2829         * same data.
2830         * </p>
2831         * <p>
2832         * Access to the social stream through this sub-directory requires additional permissions
2833         * beyond the read/write contact permissions required by the provider.  Querying for
2834         * social stream data requires android.permission.READ_SOCIAL_STREAM permission, and
2835         * inserting or updating social stream items requires android.permission.WRITE_SOCIAL_STREAM
2836         * permission.
2837         * </p>
2838         *
2839         * @deprecated - Do not use. This will not be supported in the future. In the future,
2840         * cursors returned from related queries will be empty.
2841         */
2842        @Deprecated
2843        public static final class StreamItems implements BaseColumns, StreamItemsColumns {
2844            /**
2845             * No public constructor since this is a utility class
2846             *
2847             * @deprecated - Do not use. This will not be supported in the future. In the future,
2848             * cursors returned from related queries will be empty.
2849             */
2850            @Deprecated
2851            private StreamItems() {
2852            }
2853
2854            /**
2855             * The directory twig for this sub-table
2856             *
2857             * @deprecated - Do not use. This will not be supported in the future. In the future,
2858             * cursors returned from related queries will be empty.
2859             */
2860            @Deprecated
2861            public static final String CONTENT_DIRECTORY = "stream_items";
2862        }
2863
2864        /**
2865         * <p>
2866         * A sub-directory of a single raw contact that represents its primary
2867         * display photo.  To access this directory append
2868         * {@link RawContacts.DisplayPhoto#CONTENT_DIRECTORY} to the raw contact URI.
2869         * The resulting URI represents an image file, and should be interacted with
2870         * using ContentResolver.openAssetFileDescriptor.
2871         * <p>
2872         * <p>
2873         * Note that this sub-directory also supports opening the photo as an asset file
2874         * in write mode.  Callers can create or replace the primary photo associated
2875         * with this raw contact by opening the asset file and writing the full-size
2876         * photo contents into it.  When the file is closed, the image will be parsed,
2877         * sized down if necessary for the full-size display photo and thumbnail
2878         * dimensions, and stored.
2879         * </p>
2880         * <p>
2881         * Usage example:
2882         * <pre>
2883         * public void writeDisplayPhoto(long rawContactId, byte[] photo) {
2884         *     Uri rawContactPhotoUri = Uri.withAppendedPath(
2885         *             ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactId),
2886         *             RawContacts.DisplayPhoto.CONTENT_DIRECTORY);
2887         *     try {
2888         *         AssetFileDescriptor fd =
2889         *             getContentResolver().openAssetFileDescriptor(rawContactPhotoUri, "rw");
2890         *         OutputStream os = fd.createOutputStream();
2891         *         os.write(photo);
2892         *         os.close();
2893         *         fd.close();
2894         *     } catch (IOException e) {
2895         *         // Handle error cases.
2896         *     }
2897         * }
2898         * </pre>
2899         * </p>
2900         */
2901        public static final class DisplayPhoto {
2902            /**
2903             * No public constructor since this is a utility class
2904             */
2905            private DisplayPhoto() {
2906            }
2907
2908            /**
2909             * The directory twig for this sub-table
2910             */
2911            public static final String CONTENT_DIRECTORY = "display_photo";
2912        }
2913
2914        /**
2915         * TODO: javadoc
2916         * @param cursor
2917         * @return
2918         */
2919        public static EntityIterator newEntityIterator(Cursor cursor) {
2920            return new EntityIteratorImpl(cursor);
2921        }
2922
2923        private static class EntityIteratorImpl extends CursorEntityIterator {
2924            private static final String[] DATA_KEYS = new String[]{
2925                    Data.DATA1,
2926                    Data.DATA2,
2927                    Data.DATA3,
2928                    Data.DATA4,
2929                    Data.DATA5,
2930                    Data.DATA6,
2931                    Data.DATA7,
2932                    Data.DATA8,
2933                    Data.DATA9,
2934                    Data.DATA10,
2935                    Data.DATA11,
2936                    Data.DATA12,
2937                    Data.DATA13,
2938                    Data.DATA14,
2939                    Data.DATA15,
2940                    Data.SYNC1,
2941                    Data.SYNC2,
2942                    Data.SYNC3,
2943                    Data.SYNC4};
2944
2945            public EntityIteratorImpl(Cursor cursor) {
2946                super(cursor);
2947            }
2948
2949            @Override
2950            public android.content.Entity getEntityAndIncrementCursor(Cursor cursor)
2951                    throws RemoteException {
2952                final int columnRawContactId = cursor.getColumnIndexOrThrow(RawContacts._ID);
2953                final long rawContactId = cursor.getLong(columnRawContactId);
2954
2955                // we expect the cursor is already at the row we need to read from
2956                ContentValues cv = new ContentValues();
2957                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, ACCOUNT_NAME);
2958                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, ACCOUNT_TYPE);
2959                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, DATA_SET);
2960                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, _ID);
2961                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, DIRTY);
2962                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, VERSION);
2963                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SOURCE_ID);
2964                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC1);
2965                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC2);
2966                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC3);
2967                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC4);
2968                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, DELETED);
2969                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, CONTACT_ID);
2970                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, STARRED);
2971                android.content.Entity contact = new android.content.Entity(cv);
2972
2973                // read data rows until the contact id changes
2974                do {
2975                    if (rawContactId != cursor.getLong(columnRawContactId)) {
2976                        break;
2977                    }
2978                    // add the data to to the contact
2979                    cv = new ContentValues();
2980                    cv.put(Data._ID, cursor.getLong(cursor.getColumnIndexOrThrow(Entity.DATA_ID)));
2981                    DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv,
2982                            Data.RES_PACKAGE);
2983                    DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, Data.MIMETYPE);
2984                    DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, Data.IS_PRIMARY);
2985                    DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv,
2986                            Data.IS_SUPER_PRIMARY);
2987                    DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, Data.DATA_VERSION);
2988                    DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv,
2989                            CommonDataKinds.GroupMembership.GROUP_SOURCE_ID);
2990                    DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv,
2991                            Data.DATA_VERSION);
2992                    for (String key : DATA_KEYS) {
2993                        final int columnIndex = cursor.getColumnIndexOrThrow(key);
2994                        switch (cursor.getType(columnIndex)) {
2995                            case Cursor.FIELD_TYPE_NULL:
2996                                // don't put anything
2997                                break;
2998                            case Cursor.FIELD_TYPE_INTEGER:
2999                            case Cursor.FIELD_TYPE_FLOAT:
3000                            case Cursor.FIELD_TYPE_STRING:
3001                                cv.put(key, cursor.getString(columnIndex));
3002                                break;
3003                            case Cursor.FIELD_TYPE_BLOB:
3004                                cv.put(key, cursor.getBlob(columnIndex));
3005                                break;
3006                            default:
3007                                throw new IllegalStateException("Invalid or unhandled data type");
3008                        }
3009                    }
3010                    contact.addSubValue(ContactsContract.Data.CONTENT_URI, cv);
3011                } while (cursor.moveToNext());
3012
3013                return contact;
3014            }
3015
3016        }
3017    }
3018
3019    /**
3020     * Social status update columns.
3021     *
3022     * @see StatusUpdates
3023     * @see ContactsContract.Data
3024     */
3025    protected interface StatusColumns {
3026        /**
3027         * Contact's latest presence level.
3028         * <P>Type: INTEGER (one of the values below)</P>
3029         */
3030        public static final String PRESENCE = "mode";
3031
3032        /**
3033         * @deprecated use {@link #PRESENCE}
3034         */
3035        @Deprecated
3036        public static final String PRESENCE_STATUS = PRESENCE;
3037
3038        /**
3039         * An allowed value of {@link #PRESENCE}.
3040         */
3041        int OFFLINE = 0;
3042
3043        /**
3044         * An allowed value of {@link #PRESENCE}.
3045         */
3046        int INVISIBLE = 1;
3047
3048        /**
3049         * An allowed value of {@link #PRESENCE}.
3050         */
3051        int AWAY = 2;
3052
3053        /**
3054         * An allowed value of {@link #PRESENCE}.
3055         */
3056        int IDLE = 3;
3057
3058        /**
3059         * An allowed value of {@link #PRESENCE}.
3060         */
3061        int DO_NOT_DISTURB = 4;
3062
3063        /**
3064         * An allowed value of {@link #PRESENCE}.
3065         */
3066        int AVAILABLE = 5;
3067
3068        /**
3069         * Contact latest status update.
3070         * <p>Type: TEXT</p>
3071         */
3072        public static final String STATUS = "status";
3073
3074        /**
3075         * @deprecated use {@link #STATUS}
3076         */
3077        @Deprecated
3078        public static final String PRESENCE_CUSTOM_STATUS = STATUS;
3079
3080        /**
3081         * The absolute time in milliseconds when the latest status was inserted/updated.
3082         * <p>Type: NUMBER</p>
3083         */
3084        public static final String STATUS_TIMESTAMP = "status_ts";
3085
3086        /**
3087         * The package containing resources for this status: label and icon.
3088         * <p>Type: TEXT</p>
3089         */
3090        public static final String STATUS_RES_PACKAGE = "status_res_package";
3091
3092        /**
3093         * The resource ID of the label describing the source of the status update, e.g. "Google
3094         * Talk".  This resource should be scoped by the {@link #STATUS_RES_PACKAGE}.
3095         * <p>Type: NUMBER</p>
3096         */
3097        public static final String STATUS_LABEL = "status_label";
3098
3099        /**
3100         * The resource ID of the icon for the source of the status update.
3101         * This resource should be scoped by the {@link #STATUS_RES_PACKAGE}.
3102         * <p>Type: NUMBER</p>
3103         */
3104        public static final String STATUS_ICON = "status_icon";
3105
3106        /**
3107         * Contact's audio/video chat capability level.
3108         * <P>Type: INTEGER (one of the values below)</P>
3109         */
3110        public static final String CHAT_CAPABILITY = "chat_capability";
3111
3112        /**
3113         * An allowed flag of {@link #CHAT_CAPABILITY}. Indicates audio-chat capability (microphone
3114         * and speaker)
3115         */
3116        public static final int CAPABILITY_HAS_VOICE = 1;
3117
3118        /**
3119         * An allowed flag of {@link #CHAT_CAPABILITY}. Indicates that the contact's device can
3120         * display a video feed.
3121         */
3122        public static final int CAPABILITY_HAS_VIDEO = 2;
3123
3124        /**
3125         * An allowed flag of {@link #CHAT_CAPABILITY}. Indicates that the contact's device has a
3126         * camera that can be used for video chat (e.g. a front-facing camera on a phone).
3127         */
3128        public static final int CAPABILITY_HAS_CAMERA = 4;
3129    }
3130
3131    /**
3132     * <p>
3133     * Constants for the stream_items table, which contains social stream updates from
3134     * the user's contact list.
3135     * </p>
3136     * <p>
3137     * Only a certain number of stream items will ever be stored under a given raw contact.
3138     * Users of this API can query {@link ContactsContract.StreamItems#CONTENT_LIMIT_URI} to
3139     * determine this limit, and should restrict the number of items inserted in any given
3140     * transaction correspondingly.  Insertion of more items beyond the limit will
3141     * automatically lead to deletion of the oldest items, by {@link StreamItems#TIMESTAMP}.
3142     * </p>
3143     * <p>
3144     * Access to the social stream through these URIs requires additional permissions beyond the
3145     * read/write contact permissions required by the provider.  Querying for social stream data
3146     * requires android.permission.READ_SOCIAL_STREAM permission, and inserting or updating social
3147     * stream items requires android.permission.WRITE_SOCIAL_STREAM permission.
3148     * </p>
3149     * <h3>Account check</h3>
3150     * <p>
3151     * The content URIs to the insert, update and delete operations are required to have the account
3152     * information matching that of the owning raw contact as query parameters, namely
3153     * {@link RawContacts#ACCOUNT_TYPE} and {@link RawContacts#ACCOUNT_NAME}.
3154     * {@link RawContacts#DATA_SET} isn't required.
3155     * </p>
3156     * <h3>Operations</h3>
3157     * <dl>
3158     * <dt><b>Insert</b></dt>
3159     * <dd>
3160     * <p>Social stream updates are always associated with a raw contact.  There are a couple
3161     * of ways to insert these entries.
3162     * <dl>
3163     * <dt>Via the {@link RawContacts.StreamItems#CONTENT_DIRECTORY} sub-path of a raw contact:</dt>
3164     * <dd>
3165     * <pre>
3166     * ContentValues values = new ContentValues();
3167     * values.put(StreamItems.TEXT, "Breakfasted at Tiffanys");
3168     * values.put(StreamItems.TIMESTAMP, timestamp);
3169     * values.put(StreamItems.COMMENTS, "3 people reshared this");
3170     * Uri.Builder builder = RawContacts.CONTENT_URI.buildUpon();
3171     * ContentUris.appendId(builder, rawContactId);
3172     * builder.appendEncodedPath(RawContacts.StreamItems.CONTENT_DIRECTORY);
3173     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3174     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3175     * Uri streamItemUri = getContentResolver().insert(builder.build(), values);
3176     * long streamItemId = ContentUris.parseId(streamItemUri);
3177     * </pre>
3178     * </dd>
3179     * <dt>Via {@link StreamItems#CONTENT_URI}:</dt>
3180     * <dd>
3181     *<pre>
3182     * ContentValues values = new ContentValues();
3183     * values.put(StreamItems.RAW_CONTACT_ID, rawContactId);
3184     * values.put(StreamItems.TEXT, "Breakfasted at Tiffanys");
3185     * values.put(StreamItems.TIMESTAMP, timestamp);
3186     * values.put(StreamItems.COMMENTS, "3 people reshared this");
3187     * Uri.Builder builder = StreamItems.CONTENT_URI.buildUpon();
3188     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3189     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3190     * Uri streamItemUri = getContentResolver().insert(builder.build(), values);
3191     * long streamItemId = ContentUris.parseId(streamItemUri);
3192     *</pre>
3193     * </dd>
3194     * </dl>
3195     * </dd>
3196     * </p>
3197     * <p>
3198     * Once a {@link StreamItems} entry has been inserted, photos associated with that
3199     * social update can be inserted.  For example, after one of the insertions above,
3200     * photos could be added to the stream item in one of the following ways:
3201     * <dl>
3202     * <dt>Via a URI including the stream item ID:</dt>
3203     * <dd>
3204     * <pre>
3205     * values.clear();
3206     * values.put(StreamItemPhotos.SORT_INDEX, 1);
3207     * values.put(StreamItemPhotos.PHOTO, photoData);
3208     * getContentResolver().insert(Uri.withAppendedPath(
3209     *     ContentUris.withAppendedId(StreamItems.CONTENT_URI, streamItemId),
3210     *     StreamItems.StreamItemPhotos.CONTENT_DIRECTORY), values);
3211     * </pre>
3212     * </dd>
3213     * <dt>Via {@link ContactsContract.StreamItems#CONTENT_PHOTO_URI}:</dt>
3214     * <dd>
3215     * <pre>
3216     * values.clear();
3217     * values.put(StreamItemPhotos.STREAM_ITEM_ID, streamItemId);
3218     * values.put(StreamItemPhotos.SORT_INDEX, 1);
3219     * values.put(StreamItemPhotos.PHOTO, photoData);
3220     * getContentResolver().insert(StreamItems.CONTENT_PHOTO_URI, values);
3221     * </pre>
3222     * <p>Note that this latter form allows the insertion of a stream item and its
3223     * photos in a single transaction, by using {@link ContentProviderOperation} with
3224     * back references to populate the stream item ID in the {@link ContentValues}.
3225     * </dd>
3226     * </dl>
3227     * </p>
3228     * </dd>
3229     * <dt><b>Update</b></dt>
3230     * <dd>Updates can be performed by appending the stream item ID to the
3231     * {@link StreamItems#CONTENT_URI} URI.  Only social stream entries that were
3232     * created by the calling package can be updated.</dd>
3233     * <dt><b>Delete</b></dt>
3234     * <dd>Deletes can be performed by appending the stream item ID to the
3235     * {@link StreamItems#CONTENT_URI} URI.  Only social stream entries that were
3236     * created by the calling package can be deleted.</dd>
3237     * <dt><b>Query</b></dt>
3238     * <dl>
3239     * <dt>Finding all social stream updates for a given contact</dt>
3240     * <dd>By Contact ID:
3241     * <pre>
3242     * Cursor c = getContentResolver().query(Uri.withAppendedPath(
3243     *          ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId),
3244     *          Contacts.StreamItems.CONTENT_DIRECTORY),
3245     *          null, null, null, null);
3246     * </pre>
3247     * </dd>
3248     * <dd>By lookup key:
3249     * <pre>
3250     * Cursor c = getContentResolver().query(Contacts.CONTENT_URI.buildUpon()
3251     *          .appendPath(lookupKey)
3252     *          .appendPath(Contacts.StreamItems.CONTENT_DIRECTORY).build(),
3253     *          null, null, null, null);
3254     * </pre>
3255     * </dd>
3256     * <dt>Finding all social stream updates for a given raw contact</dt>
3257     * <dd>
3258     * <pre>
3259     * Cursor c = getContentResolver().query(Uri.withAppendedPath(
3260     *          ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactId),
3261     *          RawContacts.StreamItems.CONTENT_DIRECTORY)),
3262     *          null, null, null, null);
3263     * </pre>
3264     * </dd>
3265     * <dt>Querying for a specific stream item by ID</dt>
3266     * <dd>
3267     * <pre>
3268     * Cursor c = getContentResolver().query(ContentUris.withAppendedId(
3269     *          StreamItems.CONTENT_URI, streamItemId),
3270     *          null, null, null, null);
3271     * </pre>
3272     * </dd>
3273     * </dl>
3274     *
3275     * @deprecated - Do not use. This will not be supported in the future. In the future,
3276     * cursors returned from related queries will be empty.
3277     */
3278    @Deprecated
3279    public static final class StreamItems implements BaseColumns, StreamItemsColumns {
3280        /**
3281         * This utility class cannot be instantiated
3282         *
3283         * @deprecated - Do not use. This will not be supported in the future. In the future,
3284         * cursors returned from related queries will be empty.
3285         */
3286        @Deprecated
3287        private StreamItems() {
3288        }
3289
3290        /**
3291         * The content:// style URI for this table, which handles social network stream
3292         * updates for the user's contacts.
3293         *
3294         * @deprecated - Do not use. This will not be supported in the future. In the future,
3295         * cursors returned from related queries will be empty.
3296         */
3297        @Deprecated
3298        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "stream_items");
3299
3300        /**
3301         * <p>
3302         * A content:// style URI for the photos stored in a sub-table underneath
3303         * stream items.  This is only used for inserts, and updates - queries and deletes
3304         * for photos should be performed by appending
3305         * {@link StreamItems.StreamItemPhotos#CONTENT_DIRECTORY} path to URIs for a
3306         * specific stream item.
3307         * </p>
3308         * <p>
3309         * When using this URI, the stream item ID for the photo(s) must be identified
3310         * in the {@link ContentValues} passed in.
3311         * </p>
3312         *
3313         * @deprecated - Do not use. This will not be supported in the future. In the future,
3314         * cursors returned from related queries will be empty.
3315         */
3316        @Deprecated
3317        public static final Uri CONTENT_PHOTO_URI = Uri.withAppendedPath(CONTENT_URI, "photo");
3318
3319        /**
3320         * This URI allows the caller to query for the maximum number of stream items
3321         * that will be stored under any single raw contact.
3322         *
3323         * @deprecated - Do not use. This will not be supported in the future. In the future,
3324         * cursors returned from related queries will be empty.
3325         */
3326        @Deprecated
3327        public static final Uri CONTENT_LIMIT_URI =
3328                Uri.withAppendedPath(AUTHORITY_URI, "stream_items_limit");
3329
3330        /**
3331         * The MIME type of a directory of stream items.
3332         *
3333         * @deprecated - Do not use. This will not be supported in the future. In the future,
3334         * cursors returned from related queries will be empty.
3335         */
3336        @Deprecated
3337        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/stream_item";
3338
3339        /**
3340         * The MIME type of a single stream item.
3341         *
3342         * @deprecated - Do not use. This will not be supported in the future. In the future,
3343         * cursors returned from related queries will be empty.
3344         */
3345        @Deprecated
3346        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/stream_item";
3347
3348        /**
3349         * Queries to {@link ContactsContract.StreamItems#CONTENT_LIMIT_URI} will
3350         * contain this column, with the value indicating the maximum number of
3351         * stream items that will be stored under any single raw contact.
3352         *
3353         * @deprecated - Do not use. This will not be supported in the future. In the future,
3354         * cursors returned from related queries will be empty.
3355         */
3356        @Deprecated
3357        public static final String MAX_ITEMS = "max_items";
3358
3359        /**
3360         * <p>
3361         * A sub-directory of a single stream item entry that contains all of its
3362         * photo rows. To access this
3363         * directory append {@link StreamItems.StreamItemPhotos#CONTENT_DIRECTORY} to
3364         * an individual stream item URI.
3365         * </p>
3366         * <p>
3367         * Access to social stream photos requires additional permissions beyond the read/write
3368         * contact permissions required by the provider.  Querying for social stream photos
3369         * requires android.permission.READ_SOCIAL_STREAM permission, and inserting or updating
3370         * social stream photos requires android.permission.WRITE_SOCIAL_STREAM permission.
3371         * </p>
3372         *
3373         * @deprecated - Do not use. This will not be supported in the future. In the future,
3374         * cursors returned from related queries will be empty.
3375         */
3376        @Deprecated
3377        public static final class StreamItemPhotos
3378                implements BaseColumns, StreamItemPhotosColumns {
3379            /**
3380             * No public constructor since this is a utility class
3381             *
3382             * @deprecated - Do not use. This will not be supported in the future. In the future,
3383             * cursors returned from related queries will be empty.
3384             */
3385            @Deprecated
3386            private StreamItemPhotos() {
3387            }
3388
3389            /**
3390             * The directory twig for this sub-table
3391             *
3392             * @deprecated - Do not use. This will not be supported in the future. In the future,
3393             * cursors returned from related queries will be empty.
3394             */
3395            @Deprecated
3396            public static final String CONTENT_DIRECTORY = "photo";
3397
3398            /**
3399             * The MIME type of a directory of stream item photos.
3400             *
3401             * @deprecated - Do not use. This will not be supported in the future. In the future,
3402             * cursors returned from related queries will be empty.
3403             */
3404            @Deprecated
3405            public static final String CONTENT_TYPE = "vnd.android.cursor.dir/stream_item_photo";
3406
3407            /**
3408             * The MIME type of a single stream item photo.
3409             *
3410             * @deprecated - Do not use. This will not be supported in the future. In the future,
3411             * cursors returned from related queries will be empty.
3412             */
3413            @Deprecated
3414            public static final String CONTENT_ITEM_TYPE
3415                    = "vnd.android.cursor.item/stream_item_photo";
3416        }
3417    }
3418
3419    /**
3420     * Columns in the StreamItems table.
3421     *
3422     * @see ContactsContract.StreamItems
3423     * @deprecated - Do not use. This will not be supported in the future. In the future,
3424     * cursors returned from related queries will be empty.
3425     */
3426    @Deprecated
3427    protected interface StreamItemsColumns {
3428        /**
3429         * A reference to the {@link android.provider.ContactsContract.Contacts#_ID}
3430         * that this stream item belongs to.
3431         *
3432         * <p>Type: INTEGER</p>
3433         * <p>read-only</p>
3434         *
3435         * @deprecated - Do not use. This will not be supported in the future. In the future,
3436         * cursors returned from related queries will be empty.
3437         */
3438        @Deprecated
3439        public static final String CONTACT_ID = "contact_id";
3440
3441        /**
3442         * A reference to the {@link android.provider.ContactsContract.Contacts#LOOKUP_KEY}
3443         * that this stream item belongs to.
3444         *
3445         * <p>Type: TEXT</p>
3446         * <p>read-only</p>
3447         *
3448         * @deprecated - Do not use. This will not be supported in the future. In the future,
3449         * cursors returned from related queries will be empty.
3450         */
3451        @Deprecated
3452        public static final String CONTACT_LOOKUP_KEY = "contact_lookup";
3453
3454        /**
3455         * A reference to the {@link RawContacts#_ID}
3456         * that this stream item belongs to.
3457         * <p>Type: INTEGER</p>
3458         *
3459         * @deprecated - Do not use. This will not be supported in the future. In the future,
3460         * cursors returned from related queries will be empty.
3461         */
3462        @Deprecated
3463        public static final String RAW_CONTACT_ID = "raw_contact_id";
3464
3465        /**
3466         * The package name to use when creating {@link Resources} objects for
3467         * this stream item. This value is only designed for use when building
3468         * user interfaces, and should not be used to infer the owner.
3469         * <P>Type: TEXT</P>
3470         *
3471         * @deprecated - Do not use. This will not be supported in the future. In the future,
3472         * cursors returned from related queries will be empty.
3473         */
3474        @Deprecated
3475        public static final String RES_PACKAGE = "res_package";
3476
3477        /**
3478         * The account type to which the raw_contact of this item is associated. See
3479         * {@link RawContacts#ACCOUNT_TYPE}
3480         *
3481         * <p>Type: TEXT</p>
3482         * <p>read-only</p>
3483         *
3484         * @deprecated - Do not use. This will not be supported in the future. In the future,
3485         * cursors returned from related queries will be empty.
3486         */
3487        @Deprecated
3488        public static final String ACCOUNT_TYPE = "account_type";
3489
3490        /**
3491         * The account name to which the raw_contact of this item is associated. See
3492         * {@link RawContacts#ACCOUNT_NAME}
3493         *
3494         * <p>Type: TEXT</p>
3495         * <p>read-only</p>
3496         *
3497         * @deprecated - Do not use. This will not be supported in the future. In the future,
3498         * cursors returned from related queries will be empty.
3499         */
3500        @Deprecated
3501        public static final String ACCOUNT_NAME = "account_name";
3502
3503        /**
3504         * The data set within the account that the raw_contact of this row belongs to. This allows
3505         * multiple sync adapters for the same account type to distinguish between
3506         * each others' data.
3507         * {@link RawContacts#DATA_SET}
3508         *
3509         * <P>Type: TEXT</P>
3510         * <p>read-only</p>
3511         *
3512         * @deprecated - Do not use. This will not be supported in the future. In the future,
3513         * cursors returned from related queries will be empty.
3514         */
3515        @Deprecated
3516        public static final String DATA_SET = "data_set";
3517
3518        /**
3519         * The source_id of the raw_contact that this row belongs to.
3520         * {@link RawContacts#SOURCE_ID}
3521         *
3522         * <P>Type: TEXT</P>
3523         * <p>read-only</p>
3524         *
3525         * @deprecated - Do not use. This will not be supported in the future. In the future,
3526         * cursors returned from related queries will be empty.
3527         */
3528        @Deprecated
3529        public static final String RAW_CONTACT_SOURCE_ID = "raw_contact_source_id";
3530
3531        /**
3532         * The resource name of the icon for the source of the stream item.
3533         * This resource should be scoped by the {@link #RES_PACKAGE}. As this can only reference
3534         * drawables, the "@drawable/" prefix must be omitted.
3535         * <P>Type: TEXT</P>
3536         *
3537         * @deprecated - Do not use. This will not be supported in the future. In the future,
3538         * cursors returned from related queries will be empty.
3539         */
3540        @Deprecated
3541        public static final String RES_ICON = "icon";
3542
3543        /**
3544         * The resource name of the label describing the source of the status update, e.g. "Google
3545         * Talk". This resource should be scoped by the {@link #RES_PACKAGE}. As this can only
3546         * reference strings, the "@string/" prefix must be omitted.
3547         * <p>Type: TEXT</p>
3548         *
3549         * @deprecated - Do not use. This will not be supported in the future. In the future,
3550         * cursors returned from related queries will be empty.
3551         */
3552        @Deprecated
3553        public static final String RES_LABEL = "label";
3554
3555        /**
3556         * <P>
3557         * The main textual contents of the item. Typically this is content
3558         * that was posted by the source of this stream item, but it can also
3559         * be a textual representation of an action (e.g. ”Checked in at Joe's”).
3560         * This text is displayed to the user and allows formatting and embedded
3561         * resource images via HTML (as parseable via
3562         * {@link android.text.Html#fromHtml}).
3563         * </P>
3564         * <P>
3565         * Long content may be truncated and/or ellipsized - the exact behavior
3566         * is unspecified, but it should not break tags.
3567         * </P>
3568         * <P>Type: TEXT</P>
3569         *
3570         * @deprecated - Do not use. This will not be supported in the future. In the future,
3571         * cursors returned from related queries will be empty.
3572         */
3573        @Deprecated
3574        public static final String TEXT = "text";
3575
3576        /**
3577         * The absolute time (milliseconds since epoch) when this stream item was
3578         * inserted/updated.
3579         * <P>Type: NUMBER</P>
3580         *
3581         * @deprecated - Do not use. This will not be supported in the future. In the future,
3582         * cursors returned from related queries will be empty.
3583         */
3584        @Deprecated
3585        public static final String TIMESTAMP = "timestamp";
3586
3587        /**
3588         * <P>
3589         * Summary information about the stream item, for example to indicate how
3590         * many people have reshared it, how many have liked it, how many thumbs
3591         * up and/or thumbs down it has, what the original source was, etc.
3592         * </P>
3593         * <P>
3594         * This text is displayed to the user and allows simple formatting via
3595         * HTML, in the same manner as {@link #TEXT} allows.
3596         * </P>
3597         * <P>
3598         * Long content may be truncated and/or ellipsized - the exact behavior
3599         * is unspecified, but it should not break tags.
3600         * </P>
3601         * <P>Type: TEXT</P>
3602         *
3603         * @deprecated - Do not use. This will not be supported in the future. In the future,
3604         * cursors returned from related queries will be empty.
3605         */
3606        @Deprecated
3607        public static final String COMMENTS = "comments";
3608
3609        /**
3610         * Generic column for use by sync adapters.
3611         *
3612         * @deprecated - Do not use. This will not be supported in the future. In the future,
3613         * cursors returned from related queries will be empty.
3614         */
3615        @Deprecated
3616        public static final String SYNC1 = "stream_item_sync1";
3617        /**
3618         * Generic column for use by sync adapters.
3619         *
3620         * @deprecated - Do not use. This will not be supported in the future. In the future,
3621         * cursors returned from related queries will be empty.
3622         */
3623        @Deprecated
3624        public static final String SYNC2 = "stream_item_sync2";
3625        /**
3626         * Generic column for use by sync adapters.
3627         *
3628         * @deprecated - Do not use. This will not be supported in the future. In the future,
3629         * cursors returned from related queries will be empty.
3630         */
3631        @Deprecated
3632        public static final String SYNC3 = "stream_item_sync3";
3633        /**
3634         * Generic column for use by sync adapters.
3635         *
3636         * @deprecated - Do not use. This will not be supported in the future. In the future,
3637         * cursors returned from related queries will be empty.
3638         */
3639        @Deprecated
3640        public static final String SYNC4 = "stream_item_sync4";
3641    }
3642
3643    /**
3644     * <p>
3645     * Constants for the stream_item_photos table, which contains photos associated with
3646     * social stream updates.
3647     * </p>
3648     * <p>
3649     * Access to social stream photos requires additional permissions beyond the read/write
3650     * contact permissions required by the provider.  Querying for social stream photos
3651     * requires android.permission.READ_SOCIAL_STREAM permission, and inserting or updating
3652     * social stream photos requires android.permission.WRITE_SOCIAL_STREAM permission.
3653     * </p>
3654     * <h3>Account check</h3>
3655     * <p>
3656     * The content URIs to the insert, update and delete operations are required to have the account
3657     * information matching that of the owning raw contact as query parameters, namely
3658     * {@link RawContacts#ACCOUNT_TYPE} and {@link RawContacts#ACCOUNT_NAME}.
3659     * {@link RawContacts#DATA_SET} isn't required.
3660     * </p>
3661     * <h3>Operations</h3>
3662     * <dl>
3663     * <dt><b>Insert</b></dt>
3664     * <dd>
3665     * <p>Social stream photo entries are associated with a social stream item.  Photos
3666     * can be inserted into a social stream item in a couple of ways:
3667     * <dl>
3668     * <dt>
3669     * Via the {@link StreamItems.StreamItemPhotos#CONTENT_DIRECTORY} sub-path of a
3670     * stream item:
3671     * </dt>
3672     * <dd>
3673     * <pre>
3674     * ContentValues values = new ContentValues();
3675     * values.put(StreamItemPhotos.SORT_INDEX, 1);
3676     * values.put(StreamItemPhotos.PHOTO, photoData);
3677     * Uri.Builder builder = StreamItems.CONTENT_URI.buildUpon();
3678     * ContentUris.appendId(builder, streamItemId);
3679     * builder.appendEncodedPath(StreamItems.StreamItemPhotos.CONTENT_DIRECTORY);
3680     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3681     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3682     * Uri photoUri = getContentResolver().insert(builder.build(), values);
3683     * long photoId = ContentUris.parseId(photoUri);
3684     * </pre>
3685     * </dd>
3686     * <dt>Via the {@link ContactsContract.StreamItems#CONTENT_PHOTO_URI} URI:</dt>
3687     * <dd>
3688     * <pre>
3689     * ContentValues values = new ContentValues();
3690     * values.put(StreamItemPhotos.STREAM_ITEM_ID, streamItemId);
3691     * values.put(StreamItemPhotos.SORT_INDEX, 1);
3692     * values.put(StreamItemPhotos.PHOTO, photoData);
3693     * Uri.Builder builder = StreamItems.CONTENT_PHOTO_URI.buildUpon();
3694     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3695     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3696     * Uri photoUri = getContentResolver().insert(builder.build(), values);
3697     * long photoId = ContentUris.parseId(photoUri);
3698     * </pre>
3699     * </dd>
3700     * </dl>
3701     * </p>
3702     * </dd>
3703     * <dt><b>Update</b></dt>
3704     * <dd>
3705     * <p>Updates can only be made against a specific {@link StreamItemPhotos} entry,
3706     * identified by both the stream item ID it belongs to and the stream item photo ID.
3707     * This can be specified in two ways.
3708     * <dl>
3709     * <dt>Via the {@link StreamItems.StreamItemPhotos#CONTENT_DIRECTORY} sub-path of a
3710     * stream item:
3711     * </dt>
3712     * <dd>
3713     * <pre>
3714     * ContentValues values = new ContentValues();
3715     * values.put(StreamItemPhotos.PHOTO, newPhotoData);
3716     * Uri.Builder builder = StreamItems.CONTENT_URI.buildUpon();
3717     * ContentUris.appendId(builder, streamItemId);
3718     * builder.appendEncodedPath(StreamItems.StreamItemPhotos.CONTENT_DIRECTORY);
3719     * ContentUris.appendId(builder, streamItemPhotoId);
3720     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3721     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3722     * getContentResolver().update(builder.build(), values, null, null);
3723     * </pre>
3724     * </dd>
3725     * <dt>Via the {@link ContactsContract.StreamItems#CONTENT_PHOTO_URI} URI:</dt>
3726     * <dd>
3727     * <pre>
3728     * ContentValues values = new ContentValues();
3729     * values.put(StreamItemPhotos.STREAM_ITEM_ID, streamItemId);
3730     * values.put(StreamItemPhotos.PHOTO, newPhotoData);
3731     * Uri.Builder builder = StreamItems.CONTENT_PHOTO_URI.buildUpon();
3732     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3733     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3734     * getContentResolver().update(builder.build(), values);
3735     * </pre>
3736     * </dd>
3737     * </dl>
3738     * </p>
3739     * </dd>
3740     * <dt><b>Delete</b></dt>
3741     * <dd>Deletes can be made against either a specific photo item in a stream item, or
3742     * against all or a selected subset of photo items under a stream item.
3743     * For example:
3744     * <dl>
3745     * <dt>Deleting a single photo via the
3746     * {@link StreamItems.StreamItemPhotos#CONTENT_DIRECTORY} sub-path of a stream item:
3747     * </dt>
3748     * <dd>
3749     * <pre>
3750     * Uri.Builder builder = StreamItems.CONTENT_URI.buildUpon();
3751     * ContentUris.appendId(builder, streamItemId);
3752     * builder.appendEncodedPath(StreamItems.StreamItemPhotos.CONTENT_DIRECTORY);
3753     * ContentUris.appendId(builder, streamItemPhotoId);
3754     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3755     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3756     * getContentResolver().delete(builder.build(), null, null);
3757     * </pre>
3758     * </dd>
3759     * <dt>Deleting all photos under a stream item</dt>
3760     * <dd>
3761     * <pre>
3762     * Uri.Builder builder = StreamItems.CONTENT_URI.buildUpon();
3763     * ContentUris.appendId(builder, streamItemId);
3764     * builder.appendEncodedPath(StreamItems.StreamItemPhotos.CONTENT_DIRECTORY);
3765     * builder.appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName);
3766     * builder.appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType);
3767     * getContentResolver().delete(builder.build(), null, null);
3768     * </pre>
3769     * </dd>
3770     * </dl>
3771     * </dd>
3772     * <dt><b>Query</b></dt>
3773     * <dl>
3774     * <dt>Querying for a specific photo in a stream item</dt>
3775     * <dd>
3776     * <pre>
3777     * Cursor c = getContentResolver().query(
3778     *     ContentUris.withAppendedId(
3779     *         Uri.withAppendedPath(
3780     *             ContentUris.withAppendedId(StreamItems.CONTENT_URI, streamItemId)
3781     *             StreamItems.StreamItemPhotos#CONTENT_DIRECTORY),
3782     *         streamItemPhotoId), null, null, null, null);
3783     * </pre>
3784     * </dd>
3785     * <dt>Querying for all photos in a stream item</dt>
3786     * <dd>
3787     * <pre>
3788     * Cursor c = getContentResolver().query(
3789     *     Uri.withAppendedPath(
3790     *         ContentUris.withAppendedId(StreamItems.CONTENT_URI, streamItemId)
3791     *         StreamItems.StreamItemPhotos#CONTENT_DIRECTORY),
3792     *     null, null, null, StreamItemPhotos.SORT_INDEX);
3793     * </pre>
3794     * </dl>
3795     * The record will contain both a {@link StreamItemPhotos#PHOTO_FILE_ID} and a
3796     * {@link StreamItemPhotos#PHOTO_URI}.  The {@link StreamItemPhotos#PHOTO_FILE_ID}
3797     * can be used in conjunction with the {@link ContactsContract.DisplayPhoto} API to
3798     * retrieve photo content, or you can open the {@link StreamItemPhotos#PHOTO_URI} as
3799     * an asset file, as follows:
3800     * <pre>
3801     * public InputStream openDisplayPhoto(String photoUri) {
3802     *     try {
3803     *         AssetFileDescriptor fd = getContentResolver().openAssetFileDescriptor(photoUri, "r");
3804     *         return fd.createInputStream();
3805     *     } catch (IOException e) {
3806     *         return null;
3807     *     }
3808     * }
3809     * <pre>
3810     * </dd>
3811     * </dl>
3812     *
3813     * @deprecated - Do not use. This will not be supported in the future. In the future,
3814     * cursors returned from related queries will be empty.
3815     */
3816    @Deprecated
3817    public static final class StreamItemPhotos implements BaseColumns, StreamItemPhotosColumns {
3818        /**
3819         * No public constructor since this is a utility class
3820         *
3821         * @deprecated - Do not use. This will not be supported in the future. In the future,
3822         * cursors returned from related queries will be empty.
3823         */
3824        @Deprecated
3825        private StreamItemPhotos() {
3826        }
3827
3828        /**
3829         * <p>
3830         * The binary representation of the photo.  Any size photo can be inserted;
3831         * the provider will resize it appropriately for storage and display.
3832         * </p>
3833         * <p>
3834         * This is only intended for use when inserting or updating a stream item photo.
3835         * To retrieve the photo that was stored, open {@link StreamItemPhotos#PHOTO_URI}
3836         * as an asset file.
3837         * </p>
3838         * <P>Type: BLOB</P>
3839         *
3840         * @deprecated - Do not use. This will not be supported in the future. In the future,
3841         * cursors returned from related queries will be empty.
3842         */
3843        @Deprecated
3844        public static final String PHOTO = "photo";
3845    }
3846
3847    /**
3848     * Columns in the StreamItemPhotos table.
3849     *
3850     * @see ContactsContract.StreamItemPhotos
3851     * @deprecated - Do not use. This will not be supported in the future. In the future,
3852     * cursors returned from related queries will be empty.
3853     */
3854    @Deprecated
3855    protected interface StreamItemPhotosColumns {
3856        /**
3857         * A reference to the {@link StreamItems#_ID} this photo is associated with.
3858         * <P>Type: NUMBER</P>
3859         *
3860         * @deprecated - Do not use. This will not be supported in the future. In the future,
3861         * cursors returned from related queries will be empty.
3862         */
3863        @Deprecated
3864        public static final String STREAM_ITEM_ID = "stream_item_id";
3865
3866        /**
3867         * An integer to use for sort order for photos in the stream item.  If not
3868         * specified, the {@link StreamItemPhotos#_ID} will be used for sorting.
3869         * <P>Type: NUMBER</P>
3870         *
3871         * @deprecated - Do not use. This will not be supported in the future. In the future,
3872         * cursors returned from related queries will be empty.
3873         */
3874        @Deprecated
3875        public static final String SORT_INDEX = "sort_index";
3876
3877        /**
3878         * Photo file ID for the photo.
3879         * See {@link ContactsContract.DisplayPhoto}.
3880         * <P>Type: NUMBER</P>
3881         *
3882         * @deprecated - Do not use. This will not be supported in the future. In the future,
3883         * cursors returned from related queries will be empty.
3884         */
3885        @Deprecated
3886        public static final String PHOTO_FILE_ID = "photo_file_id";
3887
3888        /**
3889         * URI for retrieving the photo content, automatically populated.  Callers
3890         * may retrieve the photo content by opening this URI as an asset file.
3891         * <P>Type: TEXT</P>
3892         *
3893         * @deprecated - Do not use. This will not be supported in the future. In the future,
3894         * cursors returned from related queries will be empty.
3895         */
3896        @Deprecated
3897        public static final String PHOTO_URI = "photo_uri";
3898
3899        /**
3900         * Generic column for use by sync adapters.
3901         *
3902         * @deprecated - Do not use. This will not be supported in the future. In the future,
3903         * cursors returned from related queries will be empty.
3904         */
3905        @Deprecated
3906        public static final String SYNC1 = "stream_item_photo_sync1";
3907        /**
3908         * Generic column for use by sync adapters.
3909         *
3910         * @deprecated - Do not use. This will not be supported in the future. In the future,
3911         * cursors returned from related queries will be empty.
3912         */
3913        @Deprecated
3914        public static final String SYNC2 = "stream_item_photo_sync2";
3915        /**
3916         * Generic column for use by sync adapters.
3917         *
3918         * @deprecated - Do not use. This will not be supported in the future. In the future,
3919         * cursors returned from related queries will be empty.
3920         */
3921        @Deprecated
3922        public static final String SYNC3 = "stream_item_photo_sync3";
3923        /**
3924         * Generic column for use by sync adapters.
3925         *
3926         * @deprecated - Do not use. This will not be supported in the future. In the future,
3927         * cursors returned from related queries will be empty.
3928         */
3929        @Deprecated
3930        public static final String SYNC4 = "stream_item_photo_sync4";
3931    }
3932
3933    /**
3934     * <p>
3935     * Constants for the photo files table, which tracks metadata for hi-res photos
3936     * stored in the file system.
3937     * </p>
3938     *
3939     * @hide
3940     */
3941    public static final class PhotoFiles implements BaseColumns, PhotoFilesColumns {
3942        /**
3943         * No public constructor since this is a utility class
3944         */
3945        private PhotoFiles() {
3946        }
3947    }
3948
3949    /**
3950     * Columns in the PhotoFiles table.
3951     *
3952     * @see ContactsContract.PhotoFiles
3953     *
3954     * @hide
3955     */
3956    protected interface PhotoFilesColumns {
3957
3958        /**
3959         * The height, in pixels, of the photo this entry is associated with.
3960         * <P>Type: NUMBER</P>
3961         */
3962        public static final String HEIGHT = "height";
3963
3964        /**
3965         * The width, in pixels, of the photo this entry is associated with.
3966         * <P>Type: NUMBER</P>
3967         */
3968        public static final String WIDTH = "width";
3969
3970        /**
3971         * The size, in bytes, of the photo stored on disk.
3972         * <P>Type: NUMBER</P>
3973         */
3974        public static final String FILESIZE = "filesize";
3975    }
3976
3977    /**
3978     * Columns in the Data table.
3979     *
3980     * @see ContactsContract.Data
3981     */
3982    protected interface DataColumns {
3983        /**
3984         * The package name to use when creating {@link Resources} objects for
3985         * this data row. This value is only designed for use when building user
3986         * interfaces, and should not be used to infer the owner.
3987         */
3988        public static final String RES_PACKAGE = "res_package";
3989
3990        /**
3991         * The MIME type of the item represented by this row.
3992         */
3993        public static final String MIMETYPE = "mimetype";
3994
3995        /**
3996         * Hash id on the data fields, used for backup and restore.
3997         *
3998         * @hide
3999         */
4000        public static final String HASH_ID = "hash_id";
4001
4002        /**
4003         * A reference to the {@link RawContacts#_ID}
4004         * that this data belongs to.
4005         */
4006        public static final String RAW_CONTACT_ID = "raw_contact_id";
4007
4008        /**
4009         * Whether this is the primary entry of its kind for the raw contact it belongs to.
4010         * <P>Type: INTEGER (if set, non-0 means true)</P>
4011         */
4012        public static final String IS_PRIMARY = "is_primary";
4013
4014        /**
4015         * Whether this is the primary entry of its kind for the aggregate
4016         * contact it belongs to. Any data record that is "super primary" must
4017         * also be "primary".
4018         * <P>Type: INTEGER (if set, non-0 means true)</P>
4019         */
4020        public static final String IS_SUPER_PRIMARY = "is_super_primary";
4021
4022        /**
4023         * The "read-only" flag: "0" by default, "1" if the row cannot be modified or
4024         * deleted except by a sync adapter.  See {@link ContactsContract#CALLER_IS_SYNCADAPTER}.
4025         * <P>Type: INTEGER</P>
4026         */
4027        public static final String IS_READ_ONLY = "is_read_only";
4028
4029        /**
4030         * The version of this data record. This is a read-only value. The data column is
4031         * guaranteed to not change without the version going up. This value is monotonically
4032         * increasing.
4033         * <P>Type: INTEGER</P>
4034         */
4035        public static final String DATA_VERSION = "data_version";
4036
4037        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4038        public static final String DATA1 = "data1";
4039        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4040        public static final String DATA2 = "data2";
4041        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4042        public static final String DATA3 = "data3";
4043        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4044        public static final String DATA4 = "data4";
4045        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4046        public static final String DATA5 = "data5";
4047        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4048        public static final String DATA6 = "data6";
4049        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4050        public static final String DATA7 = "data7";
4051        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4052        public static final String DATA8 = "data8";
4053        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4054        public static final String DATA9 = "data9";
4055        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4056        public static final String DATA10 = "data10";
4057        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4058        public static final String DATA11 = "data11";
4059        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4060        public static final String DATA12 = "data12";
4061        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4062        public static final String DATA13 = "data13";
4063        /** Generic data column, the meaning is {@link #MIMETYPE} specific */
4064        public static final String DATA14 = "data14";
4065        /**
4066         * Generic data column, the meaning is {@link #MIMETYPE} specific. By convention,
4067         * this field is used to store BLOBs (binary data).
4068         */
4069        public static final String DATA15 = "data15";
4070
4071        /** Generic column for use by sync adapters. */
4072        public static final String SYNC1 = "data_sync1";
4073        /** Generic column for use by sync adapters. */
4074        public static final String SYNC2 = "data_sync2";
4075        /** Generic column for use by sync adapters. */
4076        public static final String SYNC3 = "data_sync3";
4077        /** Generic column for use by sync adapters. */
4078        public static final String SYNC4 = "data_sync4";
4079
4080        /**
4081         * Carrier presence information.
4082         * <P>
4083         * Type: INTEGER (A bitmask of CARRIER_PRESENCE_* fields)
4084         * </P>
4085         */
4086        public static final String CARRIER_PRESENCE = "carrier_presence";
4087
4088        /**
4089         * Bitmask flags for CARRIER_PRESENCE column. Each value represents
4090         * a bit (or a set of bits) which may be set independently of each
4091         * other.
4092         */
4093        public static final int CARRIER_PRESENCE_VT_CAPABLE = 0x01;
4094    }
4095
4096    /**
4097     * Columns in the Data_Usage_Stat table
4098     */
4099    protected interface DataUsageStatColumns {
4100        /** The last time (in milliseconds) this {@link Data} was used. */
4101        public static final String LAST_TIME_USED = "last_time_used";
4102
4103        /** The number of times the referenced {@link Data} has been used. */
4104        public static final String TIMES_USED = "times_used";
4105    }
4106
4107    /**
4108     * Combines all columns returned by {@link ContactsContract.Data} table queries.
4109     *
4110     * @see ContactsContract.Data
4111     */
4112    protected interface DataColumnsWithJoins extends BaseColumns, DataColumns, StatusColumns,
4113            RawContactsColumns, ContactsColumns, ContactNameColumns, ContactOptionsColumns,
4114            ContactStatusColumns, DataUsageStatColumns {
4115    }
4116
4117    /**
4118     * <p>
4119     * Constants for the data table, which contains data points tied to a raw
4120     * contact.  Each row of the data table is typically used to store a single
4121     * piece of contact
4122     * information (such as a phone number) and its
4123     * associated metadata (such as whether it is a work or home number).
4124     * </p>
4125     * <h3>Data kinds</h3>
4126     * <p>
4127     * Data is a generic table that can hold any kind of contact data.
4128     * The kind of data stored in a given row is specified by the row's
4129     * {@link #MIMETYPE} value, which determines the meaning of the
4130     * generic columns {@link #DATA1} through
4131     * {@link #DATA15}.
4132     * For example, if the data kind is
4133     * {@link CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE}, then the column
4134     * {@link #DATA1} stores the
4135     * phone number, but if the data kind is
4136     * {@link CommonDataKinds.Email Email.CONTENT_ITEM_TYPE}, then {@link #DATA1}
4137     * stores the email address.
4138     * Sync adapters and applications can introduce their own data kinds.
4139     * </p>
4140     * <p>
4141     * ContactsContract defines a small number of pre-defined data kinds, e.g.
4142     * {@link CommonDataKinds.Phone}, {@link CommonDataKinds.Email} etc. As a
4143     * convenience, these classes define data kind specific aliases for DATA1 etc.
4144     * For example, {@link CommonDataKinds.Phone Phone.NUMBER} is the same as
4145     * {@link ContactsContract.Data Data.DATA1}.
4146     * </p>
4147     * <p>
4148     * {@link #DATA1} is an indexed column and should be used for the data element that is
4149     * expected to be most frequently used in query selections. For example, in the
4150     * case of a row representing email addresses {@link #DATA1} should probably
4151     * be used for the email address itself, while {@link #DATA2} etc can be
4152     * used for auxiliary information like type of email address.
4153     * <p>
4154     * <p>
4155     * By convention, {@link #DATA15} is used for storing BLOBs (binary data).
4156     * </p>
4157     * <p>
4158     * The sync adapter for a given account type must correctly handle every data type
4159     * used in the corresponding raw contacts.  Otherwise it could result in lost or
4160     * corrupted data.
4161     * </p>
4162     * <p>
4163     * Similarly, you should refrain from introducing new kinds of data for an other
4164     * party's account types. For example, if you add a data row for
4165     * "favorite song" to a raw contact owned by a Google account, it will not
4166     * get synced to the server, because the Google sync adapter does not know
4167     * how to handle this data kind. Thus new data kinds are typically
4168     * introduced along with new account types, i.e. new sync adapters.
4169     * </p>
4170     * <h3>Batch operations</h3>
4171     * <p>
4172     * Data rows can be inserted/updated/deleted using the traditional
4173     * {@link ContentResolver#insert}, {@link ContentResolver#update} and
4174     * {@link ContentResolver#delete} methods, however the newer mechanism based
4175     * on a batch of {@link ContentProviderOperation} will prove to be a better
4176     * choice in almost all cases. All operations in a batch are executed in a
4177     * single transaction, which ensures that the phone-side and server-side
4178     * state of a raw contact are always consistent. Also, the batch-based
4179     * approach is far more efficient: not only are the database operations
4180     * faster when executed in a single transaction, but also sending a batch of
4181     * commands to the content provider saves a lot of time on context switching
4182     * between your process and the process in which the content provider runs.
4183     * </p>
4184     * <p>
4185     * The flip side of using batched operations is that a large batch may lock
4186     * up the database for a long time preventing other applications from
4187     * accessing data and potentially causing ANRs ("Application Not Responding"
4188     * dialogs.)
4189     * </p>
4190     * <p>
4191     * To avoid such lockups of the database, make sure to insert "yield points"
4192     * in the batch. A yield point indicates to the content provider that before
4193     * executing the next operation it can commit the changes that have already
4194     * been made, yield to other requests, open another transaction and continue
4195     * processing operations. A yield point will not automatically commit the
4196     * transaction, but only if there is another request waiting on the
4197     * database. Normally a sync adapter should insert a yield point at the
4198     * beginning of each raw contact operation sequence in the batch. See
4199     * {@link ContentProviderOperation.Builder#withYieldAllowed(boolean)}.
4200     * </p>
4201     * <h3>Operations</h3>
4202     * <dl>
4203     * <dt><b>Insert</b></dt>
4204     * <dd>
4205     * <p>
4206     * An individual data row can be inserted using the traditional
4207     * {@link ContentResolver#insert(Uri, ContentValues)} method. Multiple rows
4208     * should always be inserted as a batch.
4209     * </p>
4210     * <p>
4211     * An example of a traditional insert:
4212     * <pre>
4213     * ContentValues values = new ContentValues();
4214     * values.put(Data.RAW_CONTACT_ID, rawContactId);
4215     * values.put(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE);
4216     * values.put(Phone.NUMBER, "1-800-GOOG-411");
4217     * values.put(Phone.TYPE, Phone.TYPE_CUSTOM);
4218     * values.put(Phone.LABEL, "free directory assistance");
4219     * Uri dataUri = getContentResolver().insert(Data.CONTENT_URI, values);
4220     * </pre>
4221     * <p>
4222     * The same done using ContentProviderOperations:
4223     * <pre>
4224     * ArrayList&lt;ContentProviderOperation&gt; ops =
4225     *          new ArrayList&lt;ContentProviderOperation&gt;();
4226     *
4227     * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
4228     *          .withValue(Data.RAW_CONTACT_ID, rawContactId)
4229     *          .withValue(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE)
4230     *          .withValue(Phone.NUMBER, "1-800-GOOG-411")
4231     *          .withValue(Phone.TYPE, Phone.TYPE_CUSTOM)
4232     *          .withValue(Phone.LABEL, "free directory assistance")
4233     *          .build());
4234     * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
4235     * </pre>
4236     * </p>
4237     * <dt><b>Update</b></dt>
4238     * <dd>
4239     * <p>
4240     * Just as with insert, update can be done incrementally or as a batch,
4241     * the batch mode being the preferred method:
4242     * <pre>
4243     * ArrayList&lt;ContentProviderOperation&gt; ops =
4244     *          new ArrayList&lt;ContentProviderOperation&gt;();
4245     *
4246     * ops.add(ContentProviderOperation.newUpdate(Data.CONTENT_URI)
4247     *          .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)})
4248     *          .withValue(Email.DATA, "somebody@android.com")
4249     *          .build());
4250     * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
4251     * </pre>
4252     * </p>
4253     * </dd>
4254     * <dt><b>Delete</b></dt>
4255     * <dd>
4256     * <p>
4257     * Just as with insert and update, deletion can be done either using the
4258     * {@link ContentResolver#delete} method or using a ContentProviderOperation:
4259     * <pre>
4260     * ArrayList&lt;ContentProviderOperation&gt; ops =
4261     *          new ArrayList&lt;ContentProviderOperation&gt;();
4262     *
4263     * ops.add(ContentProviderOperation.newDelete(Data.CONTENT_URI)
4264     *          .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)})
4265     *          .build());
4266     * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
4267     * </pre>
4268     * </p>
4269     * </dd>
4270     * <dt><b>Query</b></dt>
4271     * <dd>
4272     * <p>
4273     * <dl>
4274     * <dt>Finding all Data of a given type for a given contact</dt>
4275     * <dd>
4276     * <pre>
4277     * Cursor c = getContentResolver().query(Data.CONTENT_URI,
4278     *          new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},
4279     *          Data.CONTACT_ID + &quot;=?&quot; + " AND "
4280     *                  + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",
4281     *          new String[] {String.valueOf(contactId)}, null);
4282     * </pre>
4283     * </p>
4284     * <p>
4285     * </dd>
4286     * <dt>Finding all Data of a given type for a given raw contact</dt>
4287     * <dd>
4288     * <pre>
4289     * Cursor c = getContentResolver().query(Data.CONTENT_URI,
4290     *          new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},
4291     *          Data.RAW_CONTACT_ID + &quot;=?&quot; + " AND "
4292     *                  + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",
4293     *          new String[] {String.valueOf(rawContactId)}, null);
4294     * </pre>
4295     * </dd>
4296     * <dt>Finding all Data for a given raw contact</dt>
4297     * <dd>
4298     * Most sync adapters will want to read all data rows for a raw contact
4299     * along with the raw contact itself.  For that you should use the
4300     * {@link RawContactsEntity}. See also {@link RawContacts}.
4301     * </dd>
4302     * </dl>
4303     * </p>
4304     * </dd>
4305     * </dl>
4306     * <h2>Columns</h2>
4307     * <p>
4308     * Many columns are available via a {@link Data#CONTENT_URI} query.  For best performance you
4309     * should explicitly specify a projection to only those columns that you need.
4310     * </p>
4311     * <table class="jd-sumtable">
4312     * <tr>
4313     * <th colspan='4'>Data</th>
4314     * </tr>
4315     * <tr>
4316     * <td style="width: 7em;">long</td>
4317     * <td style="width: 20em;">{@link #_ID}</td>
4318     * <td style="width: 5em;">read-only</td>
4319     * <td>Row ID. Sync adapter should try to preserve row IDs during updates. In other words,
4320     * it would be a bad idea to delete and reinsert a data row. A sync adapter should
4321     * always do an update instead.</td>
4322     * </tr>
4323     * <tr>
4324     * <td>String</td>
4325     * <td>{@link #MIMETYPE}</td>
4326     * <td>read/write-once</td>
4327     * <td>
4328     * <p>The MIME type of the item represented by this row. Examples of common
4329     * MIME types are:
4330     * <ul>
4331     * <li>{@link CommonDataKinds.StructuredName StructuredName.CONTENT_ITEM_TYPE}</li>
4332     * <li>{@link CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE}</li>
4333     * <li>{@link CommonDataKinds.Email Email.CONTENT_ITEM_TYPE}</li>
4334     * <li>{@link CommonDataKinds.Photo Photo.CONTENT_ITEM_TYPE}</li>
4335     * <li>{@link CommonDataKinds.Organization Organization.CONTENT_ITEM_TYPE}</li>
4336     * <li>{@link CommonDataKinds.Im Im.CONTENT_ITEM_TYPE}</li>
4337     * <li>{@link CommonDataKinds.Nickname Nickname.CONTENT_ITEM_TYPE}</li>
4338     * <li>{@link CommonDataKinds.Note Note.CONTENT_ITEM_TYPE}</li>
4339     * <li>{@link CommonDataKinds.StructuredPostal StructuredPostal.CONTENT_ITEM_TYPE}</li>
4340     * <li>{@link CommonDataKinds.GroupMembership GroupMembership.CONTENT_ITEM_TYPE}</li>
4341     * <li>{@link CommonDataKinds.Website Website.CONTENT_ITEM_TYPE}</li>
4342     * <li>{@link CommonDataKinds.Event Event.CONTENT_ITEM_TYPE}</li>
4343     * <li>{@link CommonDataKinds.Relation Relation.CONTENT_ITEM_TYPE}</li>
4344     * <li>{@link CommonDataKinds.SipAddress SipAddress.CONTENT_ITEM_TYPE}</li>
4345     * </ul>
4346     * </p>
4347     * </td>
4348     * </tr>
4349     * <tr>
4350     * <td>long</td>
4351     * <td>{@link #RAW_CONTACT_ID}</td>
4352     * <td>read/write-once</td>
4353     * <td>The id of the row in the {@link RawContacts} table that this data belongs to.</td>
4354     * </tr>
4355     * <tr>
4356     * <td>int</td>
4357     * <td>{@link #IS_PRIMARY}</td>
4358     * <td>read/write</td>
4359     * <td>Whether this is the primary entry of its kind for the raw contact it belongs to.
4360     * "1" if true, "0" if false.
4361     * </td>
4362     * </tr>
4363     * <tr>
4364     * <td>int</td>
4365     * <td>{@link #IS_SUPER_PRIMARY}</td>
4366     * <td>read/write</td>
4367     * <td>Whether this is the primary entry of its kind for the aggregate
4368     * contact it belongs to. Any data record that is "super primary" must
4369     * also be "primary".  For example, the super-primary entry may be
4370     * interpreted as the default contact value of its kind (for example,
4371     * the default phone number to use for the contact).</td>
4372     * </tr>
4373     * <tr>
4374     * <td>int</td>
4375     * <td>{@link #DATA_VERSION}</td>
4376     * <td>read-only</td>
4377     * <td>The version of this data record. Whenever the data row changes
4378     * the version goes up. This value is monotonically increasing.</td>
4379     * </tr>
4380     * <tr>
4381     * <td>Any type</td>
4382     * <td>
4383     * {@link #DATA1}<br>
4384     * {@link #DATA2}<br>
4385     * {@link #DATA3}<br>
4386     * {@link #DATA4}<br>
4387     * {@link #DATA5}<br>
4388     * {@link #DATA6}<br>
4389     * {@link #DATA7}<br>
4390     * {@link #DATA8}<br>
4391     * {@link #DATA9}<br>
4392     * {@link #DATA10}<br>
4393     * {@link #DATA11}<br>
4394     * {@link #DATA12}<br>
4395     * {@link #DATA13}<br>
4396     * {@link #DATA14}<br>
4397     * {@link #DATA15}
4398     * </td>
4399     * <td>read/write</td>
4400     * <td>
4401     * <p>
4402     * Generic data columns.  The meaning of each column is determined by the
4403     * {@link #MIMETYPE}.  By convention, {@link #DATA15} is used for storing
4404     * BLOBs (binary data).
4405     * </p>
4406     * <p>
4407     * Data columns whose meaning is not explicitly defined for a given MIMETYPE
4408     * should not be used.  There is no guarantee that any sync adapter will
4409     * preserve them.  Sync adapters themselves should not use such columns either,
4410     * but should instead use {@link #SYNC1}-{@link #SYNC4}.
4411     * </p>
4412     * </td>
4413     * </tr>
4414     * <tr>
4415     * <td>Any type</td>
4416     * <td>
4417     * {@link #SYNC1}<br>
4418     * {@link #SYNC2}<br>
4419     * {@link #SYNC3}<br>
4420     * {@link #SYNC4}
4421     * </td>
4422     * <td>read/write</td>
4423     * <td>Generic columns for use by sync adapters. For example, a Photo row
4424     * may store the image URL in SYNC1, a status (not loaded, loading, loaded, error)
4425     * in SYNC2, server-side version number in SYNC3 and error code in SYNC4.</td>
4426     * </tr>
4427     * </table>
4428     *
4429     * <p>
4430     * Some columns from the most recent associated status update are also available
4431     * through an implicit join.
4432     * </p>
4433     * <table class="jd-sumtable">
4434     * <tr>
4435     * <th colspan='4'>Join with {@link StatusUpdates}</th>
4436     * </tr>
4437     * <tr>
4438     * <td style="width: 7em;">int</td>
4439     * <td style="width: 20em;">{@link #PRESENCE}</td>
4440     * <td style="width: 5em;">read-only</td>
4441     * <td>IM presence status linked to this data row. Compare with
4442     * {@link #CONTACT_PRESENCE}, which contains the contact's presence across
4443     * all IM rows. See {@link StatusUpdates} for individual status definitions.
4444     * The provider may choose not to store this value
4445     * in persistent storage. The expectation is that presence status will be
4446     * updated on a regular basis.
4447     * </td>
4448     * </tr>
4449     * <tr>
4450     * <td>String</td>
4451     * <td>{@link #STATUS}</td>
4452     * <td>read-only</td>
4453     * <td>Latest status update linked with this data row.</td>
4454     * </tr>
4455     * <tr>
4456     * <td>long</td>
4457     * <td>{@link #STATUS_TIMESTAMP}</td>
4458     * <td>read-only</td>
4459     * <td>The absolute time in milliseconds when the latest status was
4460     * inserted/updated for this data row.</td>
4461     * </tr>
4462     * <tr>
4463     * <td>String</td>
4464     * <td>{@link #STATUS_RES_PACKAGE}</td>
4465     * <td>read-only</td>
4466     * <td>The package containing resources for this status: label and icon.</td>
4467     * </tr>
4468     * <tr>
4469     * <td>long</td>
4470     * <td>{@link #STATUS_LABEL}</td>
4471     * <td>read-only</td>
4472     * <td>The resource ID of the label describing the source of status update linked
4473     * to this data row. This resource is scoped by the {@link #STATUS_RES_PACKAGE}.</td>
4474     * </tr>
4475     * <tr>
4476     * <td>long</td>
4477     * <td>{@link #STATUS_ICON}</td>
4478     * <td>read-only</td>
4479     * <td>The resource ID of the icon for the source of the status update linked
4480     * to this data row. This resource is scoped by the {@link #STATUS_RES_PACKAGE}.</td>
4481     * </tr>
4482     * </table>
4483     *
4484     * <p>
4485     * Some columns from the associated raw contact are also available through an
4486     * implicit join.  The other columns are excluded as uninteresting in this
4487     * context.
4488     * </p>
4489     *
4490     * <table class="jd-sumtable">
4491     * <tr>
4492     * <th colspan='4'>Join with {@link ContactsContract.RawContacts}</th>
4493     * </tr>
4494     * <tr>
4495     * <td style="width: 7em;">long</td>
4496     * <td style="width: 20em;">{@link #CONTACT_ID}</td>
4497     * <td style="width: 5em;">read-only</td>
4498     * <td>The id of the row in the {@link Contacts} table that this data belongs
4499     * to.</td>
4500     * </tr>
4501     * <tr>
4502     * <td>int</td>
4503     * <td>{@link #AGGREGATION_MODE}</td>
4504     * <td>read-only</td>
4505     * <td>See {@link RawContacts}.</td>
4506     * </tr>
4507     * <tr>
4508     * <td>int</td>
4509     * <td>{@link #DELETED}</td>
4510     * <td>read-only</td>
4511     * <td>See {@link RawContacts}.</td>
4512     * </tr>
4513     * </table>
4514     *
4515     * <p>
4516     * The ID column for the associated aggregated contact table
4517     * {@link ContactsContract.Contacts} is available
4518     * via the implicit join to the {@link RawContacts} table, see above.
4519     * The remaining columns from this table are also
4520     * available, through an implicit join.  This
4521     * facilitates lookup by
4522     * the value of a single data element, such as the email address.
4523     * </p>
4524     *
4525     * <table class="jd-sumtable">
4526     * <tr>
4527     * <th colspan='4'>Join with {@link ContactsContract.Contacts}</th>
4528     * </tr>
4529     * <tr>
4530     * <td style="width: 7em;">String</td>
4531     * <td style="width: 20em;">{@link #LOOKUP_KEY}</td>
4532     * <td style="width: 5em;">read-only</td>
4533     * <td>See {@link ContactsContract.Contacts}</td>
4534     * </tr>
4535     * <tr>
4536     * <td>String</td>
4537     * <td>{@link #DISPLAY_NAME}</td>
4538     * <td>read-only</td>
4539     * <td>See {@link ContactsContract.Contacts}</td>
4540     * </tr>
4541     * <tr>
4542     * <td>long</td>
4543     * <td>{@link #PHOTO_ID}</td>
4544     * <td>read-only</td>
4545     * <td>See {@link ContactsContract.Contacts}.</td>
4546     * </tr>
4547     * <tr>
4548     * <td>int</td>
4549     * <td>{@link #IN_VISIBLE_GROUP}</td>
4550     * <td>read-only</td>
4551     * <td>See {@link ContactsContract.Contacts}.</td>
4552     * </tr>
4553     * <tr>
4554     * <td>int</td>
4555     * <td>{@link #HAS_PHONE_NUMBER}</td>
4556     * <td>read-only</td>
4557     * <td>See {@link ContactsContract.Contacts}.</td>
4558     * </tr>
4559     * <tr>
4560     * <td>int</td>
4561     * <td>{@link #TIMES_CONTACTED}</td>
4562     * <td>read-only</td>
4563     * <td>See {@link ContactsContract.Contacts}.</td>
4564     * </tr>
4565     * <tr>
4566     * <td>long</td>
4567     * <td>{@link #LAST_TIME_CONTACTED}</td>
4568     * <td>read-only</td>
4569     * <td>See {@link ContactsContract.Contacts}.</td>
4570     * </tr>
4571     * <tr>
4572     * <td>int</td>
4573     * <td>{@link #STARRED}</td>
4574     * <td>read-only</td>
4575     * <td>See {@link ContactsContract.Contacts}.</td>
4576     * </tr>
4577     * <tr>
4578     * <td>String</td>
4579     * <td>{@link #CUSTOM_RINGTONE}</td>
4580     * <td>read-only</td>
4581     * <td>See {@link ContactsContract.Contacts}.</td>
4582     * </tr>
4583     * <tr>
4584     * <td>int</td>
4585     * <td>{@link #SEND_TO_VOICEMAIL}</td>
4586     * <td>read-only</td>
4587     * <td>See {@link ContactsContract.Contacts}.</td>
4588     * </tr>
4589     * <tr>
4590     * <td>int</td>
4591     * <td>{@link #CONTACT_PRESENCE}</td>
4592     * <td>read-only</td>
4593     * <td>See {@link ContactsContract.Contacts}.</td>
4594     * </tr>
4595     * <tr>
4596     * <td>String</td>
4597     * <td>{@link #CONTACT_STATUS}</td>
4598     * <td>read-only</td>
4599     * <td>See {@link ContactsContract.Contacts}.</td>
4600     * </tr>
4601     * <tr>
4602     * <td>long</td>
4603     * <td>{@link #CONTACT_STATUS_TIMESTAMP}</td>
4604     * <td>read-only</td>
4605     * <td>See {@link ContactsContract.Contacts}.</td>
4606     * </tr>
4607     * <tr>
4608     * <td>String</td>
4609     * <td>{@link #CONTACT_STATUS_RES_PACKAGE}</td>
4610     * <td>read-only</td>
4611     * <td>See {@link ContactsContract.Contacts}.</td>
4612     * </tr>
4613     * <tr>
4614     * <td>long</td>
4615     * <td>{@link #CONTACT_STATUS_LABEL}</td>
4616     * <td>read-only</td>
4617     * <td>See {@link ContactsContract.Contacts}.</td>
4618     * </tr>
4619     * <tr>
4620     * <td>long</td>
4621     * <td>{@link #CONTACT_STATUS_ICON}</td>
4622     * <td>read-only</td>
4623     * <td>See {@link ContactsContract.Contacts}.</td>
4624     * </tr>
4625     * </table>
4626     */
4627    public final static class Data implements DataColumnsWithJoins, ContactCounts {
4628        /**
4629         * This utility class cannot be instantiated
4630         */
4631        private Data() {}
4632
4633        /**
4634         * The content:// style URI for this table, which requests a directory
4635         * of data rows matching the selection criteria.
4636         */
4637        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data");
4638
4639        /**
4640        * The content:// style URI for this table in managed profile, which requests a directory
4641        * of data rows matching the selection criteria.
4642        *
4643        * @hide
4644        */
4645        static final Uri ENTERPRISE_CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI,
4646                "data_enterprise");
4647
4648        /**
4649         * A boolean parameter for {@link Data#CONTENT_URI}.
4650         * This specifies whether or not the returned data items should be filtered to show
4651         * data items belonging to visible contacts only.
4652         */
4653        public static final String VISIBLE_CONTACTS_ONLY = "visible_contacts_only";
4654
4655        /**
4656         * The MIME type of the results from {@link #CONTENT_URI}.
4657         */
4658        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data";
4659
4660        /**
4661         * <p>
4662         * Build a {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}
4663         * style {@link Uri} for the parent {@link android.provider.ContactsContract.Contacts}
4664         * entry of the given {@link ContactsContract.Data} entry.
4665         * </p>
4666         * <p>
4667         * Returns the Uri for the contact in the first entry returned by
4668         * {@link ContentResolver#query(Uri, String[], String, String[], String)}
4669         * for the provided {@code dataUri}.  If the query returns null or empty
4670         * results, silently returns null.
4671         * </p>
4672         */
4673        public static Uri getContactLookupUri(ContentResolver resolver, Uri dataUri) {
4674            final Cursor cursor = resolver.query(dataUri, new String[] {
4675                    RawContacts.CONTACT_ID, Contacts.LOOKUP_KEY
4676            }, null, null, null);
4677
4678            Uri lookupUri = null;
4679            try {
4680                if (cursor != null && cursor.moveToFirst()) {
4681                    final long contactId = cursor.getLong(0);
4682                    final String lookupKey = cursor.getString(1);
4683                    return Contacts.getLookupUri(contactId, lookupKey);
4684                }
4685            } finally {
4686                if (cursor != null) cursor.close();
4687            }
4688            return lookupUri;
4689        }
4690    }
4691
4692    /**
4693     * <p>
4694     * Constants for the raw contacts entities table, which can be thought of as
4695     * an outer join of the raw_contacts table with the data table.  It is a strictly
4696     * read-only table.
4697     * </p>
4698     * <p>
4699     * If a raw contact has data rows, the RawContactsEntity cursor will contain
4700     * a one row for each data row. If the raw contact has no data rows, the
4701     * cursor will still contain one row with the raw contact-level information
4702     * and nulls for data columns.
4703     *
4704     * <pre>
4705     * Uri entityUri = ContentUris.withAppendedId(RawContactsEntity.CONTENT_URI, rawContactId);
4706     * Cursor c = getContentResolver().query(entityUri,
4707     *          new String[]{
4708     *              RawContactsEntity.SOURCE_ID,
4709     *              RawContactsEntity.DATA_ID,
4710     *              RawContactsEntity.MIMETYPE,
4711     *              RawContactsEntity.DATA1
4712     *          }, null, null, null);
4713     * try {
4714     *     while (c.moveToNext()) {
4715     *         String sourceId = c.getString(0);
4716     *         if (!c.isNull(1)) {
4717     *             String mimeType = c.getString(2);
4718     *             String data = c.getString(3);
4719     *             ...
4720     *         }
4721     *     }
4722     * } finally {
4723     *     c.close();
4724     * }
4725     * </pre>
4726     *
4727     * <h3>Columns</h3>
4728     * RawContactsEntity has a combination of RawContact and Data columns.
4729     *
4730     * <table class="jd-sumtable">
4731     * <tr>
4732     * <th colspan='4'>RawContacts</th>
4733     * </tr>
4734     * <tr>
4735     * <td style="width: 7em;">long</td>
4736     * <td style="width: 20em;">{@link #_ID}</td>
4737     * <td style="width: 5em;">read-only</td>
4738     * <td>Raw contact row ID. See {@link RawContacts}.</td>
4739     * </tr>
4740     * <tr>
4741     * <td>long</td>
4742     * <td>{@link #CONTACT_ID}</td>
4743     * <td>read-only</td>
4744     * <td>See {@link RawContacts}.</td>
4745     * </tr>
4746     * <tr>
4747     * <td>int</td>
4748     * <td>{@link #AGGREGATION_MODE}</td>
4749     * <td>read-only</td>
4750     * <td>See {@link RawContacts}.</td>
4751     * </tr>
4752     * <tr>
4753     * <td>int</td>
4754     * <td>{@link #DELETED}</td>
4755     * <td>read-only</td>
4756     * <td>See {@link RawContacts}.</td>
4757     * </tr>
4758     * </table>
4759     *
4760     * <table class="jd-sumtable">
4761     * <tr>
4762     * <th colspan='4'>Data</th>
4763     * </tr>
4764     * <tr>
4765     * <td style="width: 7em;">long</td>
4766     * <td style="width: 20em;">{@link #DATA_ID}</td>
4767     * <td style="width: 5em;">read-only</td>
4768     * <td>Data row ID. It will be null if the raw contact has no data rows.</td>
4769     * </tr>
4770     * <tr>
4771     * <td>String</td>
4772     * <td>{@link #MIMETYPE}</td>
4773     * <td>read-only</td>
4774     * <td>See {@link ContactsContract.Data}.</td>
4775     * </tr>
4776     * <tr>
4777     * <td>int</td>
4778     * <td>{@link #IS_PRIMARY}</td>
4779     * <td>read-only</td>
4780     * <td>See {@link ContactsContract.Data}.</td>
4781     * </tr>
4782     * <tr>
4783     * <td>int</td>
4784     * <td>{@link #IS_SUPER_PRIMARY}</td>
4785     * <td>read-only</td>
4786     * <td>See {@link ContactsContract.Data}.</td>
4787     * </tr>
4788     * <tr>
4789     * <td>int</td>
4790     * <td>{@link #DATA_VERSION}</td>
4791     * <td>read-only</td>
4792     * <td>See {@link ContactsContract.Data}.</td>
4793     * </tr>
4794     * <tr>
4795     * <td>Any type</td>
4796     * <td>
4797     * {@link #DATA1}<br>
4798     * {@link #DATA2}<br>
4799     * {@link #DATA3}<br>
4800     * {@link #DATA4}<br>
4801     * {@link #DATA5}<br>
4802     * {@link #DATA6}<br>
4803     * {@link #DATA7}<br>
4804     * {@link #DATA8}<br>
4805     * {@link #DATA9}<br>
4806     * {@link #DATA10}<br>
4807     * {@link #DATA11}<br>
4808     * {@link #DATA12}<br>
4809     * {@link #DATA13}<br>
4810     * {@link #DATA14}<br>
4811     * {@link #DATA15}
4812     * </td>
4813     * <td>read-only</td>
4814     * <td>See {@link ContactsContract.Data}.</td>
4815     * </tr>
4816     * <tr>
4817     * <td>Any type</td>
4818     * <td>
4819     * {@link #SYNC1}<br>
4820     * {@link #SYNC2}<br>
4821     * {@link #SYNC3}<br>
4822     * {@link #SYNC4}
4823     * </td>
4824     * <td>read-only</td>
4825     * <td>See {@link ContactsContract.Data}.</td>
4826     * </tr>
4827     * </table>
4828     */
4829    public final static class RawContactsEntity
4830            implements BaseColumns, DataColumns, RawContactsColumns {
4831        /**
4832         * This utility class cannot be instantiated
4833         */
4834        private RawContactsEntity() {}
4835
4836        /**
4837         * The content:// style URI for this table
4838         */
4839        public static final Uri CONTENT_URI =
4840                Uri.withAppendedPath(AUTHORITY_URI, "raw_contact_entities");
4841
4842        /**
4843        * The content:// style URI for this table in corp profile
4844        *
4845        * @hide
4846        */
4847        public static final Uri CORP_CONTENT_URI =
4848                Uri.withAppendedPath(AUTHORITY_URI, "raw_contact_entities_corp");
4849
4850        /**
4851         * The content:// style URI for this table, specific to the user's profile.
4852         */
4853        public static final Uri PROFILE_CONTENT_URI =
4854                Uri.withAppendedPath(Profile.CONTENT_URI, "raw_contact_entities");
4855
4856        /**
4857         * The MIME type of {@link #CONTENT_URI} providing a directory of raw contact entities.
4858         */
4859        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/raw_contact_entity";
4860
4861        /**
4862         * If {@link #FOR_EXPORT_ONLY} is explicitly set to "1", returned Cursor toward
4863         * Data.CONTENT_URI contains only exportable data.
4864         *
4865         * This flag is useful (currently) only for vCard exporter in Contacts app, which
4866         * needs to exclude "un-exportable" data from available data to export, while
4867         * Contacts app itself has priviledge to access all data including "un-expotable"
4868         * ones and providers return all of them regardless of the callers' intention.
4869         * <P>Type: INTEGER</p>
4870         *
4871         * @hide Maybe available only in Eclair and not really ready for public use.
4872         * TODO: remove, or implement this feature completely. As of now (Eclair),
4873         * we only use this flag in queryEntities(), not query().
4874         */
4875        public static final String FOR_EXPORT_ONLY = "for_export_only";
4876
4877        /**
4878         * The ID of the data column. The value will be null if this raw contact has no data rows.
4879         * <P>Type: INTEGER</P>
4880         */
4881        public static final String DATA_ID = "data_id";
4882    }
4883
4884    /**
4885     * @see PhoneLookup
4886     */
4887    protected interface PhoneLookupColumns {
4888        /**
4889         * The phone number as the user entered it.
4890         * <P>Type: TEXT</P>
4891         */
4892        public static final String NUMBER = "number";
4893
4894        /**
4895         * The type of phone number, for example Home or Work.
4896         * <P>Type: INTEGER</P>
4897         */
4898        public static final String TYPE = "type";
4899
4900        /**
4901         * The user defined label for the phone number.
4902         * <P>Type: TEXT</P>
4903         */
4904        public static final String LABEL = "label";
4905
4906        /**
4907         * The phone number's E164 representation.
4908         * <P>Type: TEXT</P>
4909         */
4910        public static final String NORMALIZED_NUMBER = "normalized_number";
4911    }
4912
4913    /**
4914     * A table that represents the result of looking up a phone number, for
4915     * example for caller ID. To perform a lookup you must append the number you
4916     * want to find to {@link #CONTENT_FILTER_URI}.  This query is highly
4917     * optimized.
4918     * <pre>
4919     * Uri uri = Uri.withAppendedPath(PhoneLookup.CONTENT_FILTER_URI, Uri.encode(phoneNumber));
4920     * resolver.query(uri, new String[]{PhoneLookup.DISPLAY_NAME,...
4921     * </pre>
4922     *
4923     * <h3>Columns</h3>
4924     *
4925     * <table class="jd-sumtable">
4926     * <tr>
4927     * <th colspan='4'>PhoneLookup</th>
4928     * </tr>
4929     * <tr>
4930     * <td>String</td>
4931     * <td>{@link #NUMBER}</td>
4932     * <td>read-only</td>
4933     * <td>Phone number.</td>
4934     * </tr>
4935     * <tr>
4936     * <td>String</td>
4937     * <td>{@link #TYPE}</td>
4938     * <td>read-only</td>
4939     * <td>Phone number type. See {@link CommonDataKinds.Phone}.</td>
4940     * </tr>
4941     * <tr>
4942     * <td>String</td>
4943     * <td>{@link #LABEL}</td>
4944     * <td>read-only</td>
4945     * <td>Custom label for the phone number. See {@link CommonDataKinds.Phone}.</td>
4946     * </tr>
4947     * </table>
4948     * <p>
4949     * Columns from the Contacts table are also available through a join.
4950     * </p>
4951     * <table class="jd-sumtable">
4952     * <tr>
4953     * <th colspan='4'>Join with {@link Contacts}</th>
4954     * </tr>
4955     * <tr>
4956     * <td>long</td>
4957     * <td>{@link #_ID}</td>
4958     * <td>read-only</td>
4959     * <td>Contact ID.</td>
4960     * </tr>
4961     * <tr>
4962     * <td>String</td>
4963     * <td>{@link #LOOKUP_KEY}</td>
4964     * <td>read-only</td>
4965     * <td>See {@link ContactsContract.Contacts}</td>
4966     * </tr>
4967     * <tr>
4968     * <td>String</td>
4969     * <td>{@link #DISPLAY_NAME}</td>
4970     * <td>read-only</td>
4971     * <td>See {@link ContactsContract.Contacts}</td>
4972     * </tr>
4973     * <tr>
4974     * <td>long</td>
4975     * <td>{@link #PHOTO_ID}</td>
4976     * <td>read-only</td>
4977     * <td>See {@link ContactsContract.Contacts}.</td>
4978     * </tr>
4979     * <tr>
4980     * <td>int</td>
4981     * <td>{@link #IN_VISIBLE_GROUP}</td>
4982     * <td>read-only</td>
4983     * <td>See {@link ContactsContract.Contacts}.</td>
4984     * </tr>
4985     * <tr>
4986     * <td>int</td>
4987     * <td>{@link #HAS_PHONE_NUMBER}</td>
4988     * <td>read-only</td>
4989     * <td>See {@link ContactsContract.Contacts}.</td>
4990     * </tr>
4991     * <tr>
4992     * <td>int</td>
4993     * <td>{@link #TIMES_CONTACTED}</td>
4994     * <td>read-only</td>
4995     * <td>See {@link ContactsContract.Contacts}.</td>
4996     * </tr>
4997     * <tr>
4998     * <td>long</td>
4999     * <td>{@link #LAST_TIME_CONTACTED}</td>
5000     * <td>read-only</td>
5001     * <td>See {@link ContactsContract.Contacts}.</td>
5002     * </tr>
5003     * <tr>
5004     * <td>int</td>
5005     * <td>{@link #STARRED}</td>
5006     * <td>read-only</td>
5007     * <td>See {@link ContactsContract.Contacts}.</td>
5008     * </tr>
5009     * <tr>
5010     * <td>String</td>
5011     * <td>{@link #CUSTOM_RINGTONE}</td>
5012     * <td>read-only</td>
5013     * <td>See {@link ContactsContract.Contacts}.</td>
5014     * </tr>
5015     * <tr>
5016     * <td>int</td>
5017     * <td>{@link #SEND_TO_VOICEMAIL}</td>
5018     * <td>read-only</td>
5019     * <td>See {@link ContactsContract.Contacts}.</td>
5020     * </tr>
5021     * </table>
5022     */
5023    public static final class PhoneLookup implements BaseColumns, PhoneLookupColumns,
5024            ContactsColumns, ContactOptionsColumns {
5025        /**
5026         * This utility class cannot be instantiated
5027         */
5028        private PhoneLookup() {}
5029
5030        /**
5031         * The content:// style URI for this table. Append the phone number you want to lookup
5032         * to this URI and query it to perform a lookup. For example:
5033         * <pre>
5034         * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_FILTER_URI,
5035         *         Uri.encode(phoneNumber));
5036         * </pre>
5037         */
5038        public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(AUTHORITY_URI,
5039                "phone_lookup");
5040
5041        /**
5042         * <p>URI used for the "enterprise caller-id".</p>
5043         *
5044         * <p>
5045         * It supports the same semantics as {@link #CONTENT_FILTER_URI} and returns the same
5046         * columns.  If the device has no corp profile that is linked to the current profile, it
5047         * behaves in the exact same way as {@link #CONTENT_FILTER_URI}.  If there is a corp profile
5048         * linked to the current profile, it first queries against the personal contact database,
5049         * and if no matching contacts are found there, then queries against the
5050         * corp contacts database.
5051         * </p>
5052         * <p>
5053         * If a result is from the corp profile, it makes the following changes to the data:
5054         * <ul>
5055         *     <li>
5056         *     {@link #PHOTO_THUMBNAIL_URI} and {@link #PHOTO_URI} will be rewritten to special
5057         *     URIs.  Use {@link ContentResolver#openAssetFileDescriptor} or its siblings to
5058         *     load pictures from them.
5059         *     {@link #PHOTO_ID} and {@link #PHOTO_FILE_ID} will be set to null.  Do not use them.
5060         *     </li>
5061         *     <li>
5062         *     Corp contacts will get artificial {@link #_ID}s.  In order to tell whether a contact
5063         *     is from the corp profile, use
5064         *     {@link ContactsContract.Contacts#isEnterpriseContactId(long)}.
5065         *     </li>
5066         *     <li>
5067         *     Corp contacts will get artificial {@link #LOOKUP_KEY}s too.
5068         *     </li>
5069         * </ul>
5070         * <p>
5071         * A contact lookup URL built by
5072         * {@link ContactsContract.Contacts#getLookupUri(long, String)}
5073         * with an {@link #_ID} and a {@link #LOOKUP_KEY} returned by this API can be passed to
5074         * {@link ContactsContract.QuickContact#showQuickContact} even if a contact is from the
5075         * corp profile.
5076         * </p>
5077         *
5078         * <pre>
5079         * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.ENTERPRISE_CONTENT_FILTER_URI,
5080         *         Uri.encode(phoneNumber));
5081         * </pre>
5082         */
5083        public static final Uri ENTERPRISE_CONTENT_FILTER_URI = Uri.withAppendedPath(AUTHORITY_URI,
5084                "phone_lookup_enterprise");
5085
5086        /**
5087         * The MIME type of {@link #CONTENT_FILTER_URI} providing a directory of phone lookup rows.
5088         *
5089         * @hide
5090         */
5091        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/phone_lookup";
5092
5093        /**
5094         * If this boolean parameter is set to true, then the appended query is treated as a
5095         * SIP address and the lookup will be performed against SIP addresses in the user's
5096         * contacts.
5097         */
5098        public static final String QUERY_PARAMETER_SIP_ADDRESS = "sip";
5099    }
5100
5101    /**
5102     * Additional data mixed in with {@link StatusColumns} to link
5103     * back to specific {@link ContactsContract.Data#_ID} entries.
5104     *
5105     * @see StatusUpdates
5106     */
5107    protected interface PresenceColumns {
5108
5109        /**
5110         * Reference to the {@link Data#_ID} entry that owns this presence.
5111         * <P>Type: INTEGER</P>
5112         */
5113        public static final String DATA_ID = "presence_data_id";
5114
5115        /**
5116         * See {@link CommonDataKinds.Im} for a list of defined protocol constants.
5117         * <p>Type: NUMBER</p>
5118         */
5119        public static final String PROTOCOL = "protocol";
5120
5121        /**
5122         * Name of the custom protocol.  Should be supplied along with the {@link #PROTOCOL} value
5123         * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}.  Should be null or
5124         * omitted if {@link #PROTOCOL} value is not
5125         * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}.
5126         *
5127         * <p>Type: NUMBER</p>
5128         */
5129        public static final String CUSTOM_PROTOCOL = "custom_protocol";
5130
5131        /**
5132         * The IM handle the presence item is for. The handle is scoped to
5133         * {@link #PROTOCOL}.
5134         * <P>Type: TEXT</P>
5135         */
5136        public static final String IM_HANDLE = "im_handle";
5137
5138        /**
5139         * The IM account for the local user that the presence data came from.
5140         * <P>Type: TEXT</P>
5141         */
5142        public static final String IM_ACCOUNT = "im_account";
5143    }
5144
5145    /**
5146     * <p>
5147     * A status update is linked to a {@link ContactsContract.Data} row and captures
5148     * the user's latest status update via the corresponding source, e.g.
5149     * "Having lunch" via "Google Talk".
5150     * </p>
5151     * <p>
5152     * There are two ways a status update can be inserted: by explicitly linking
5153     * it to a Data row using {@link #DATA_ID} or indirectly linking it to a data row
5154     * using a combination of {@link #PROTOCOL} (or {@link #CUSTOM_PROTOCOL}) and
5155     * {@link #IM_HANDLE}.  There is no difference between insert and update, you can use
5156     * either.
5157     * </p>
5158     * <p>
5159     * Inserting or updating a status update for the user's profile requires either using
5160     * the {@link #DATA_ID} to identify the data row to attach the update to, or
5161     * {@link StatusUpdates#PROFILE_CONTENT_URI} to ensure that the change is scoped to the
5162     * profile.
5163     * </p>
5164     * <p>
5165     * You cannot use {@link ContentResolver#update} to change a status, but
5166     * {@link ContentResolver#insert} will replace the latests status if it already
5167     * exists.
5168     * </p>
5169     * <p>
5170     * Use {@link ContentResolver#bulkInsert(Uri, ContentValues[])} to insert/update statuses
5171     * for multiple contacts at once.
5172     * </p>
5173     *
5174     * <h3>Columns</h3>
5175     * <table class="jd-sumtable">
5176     * <tr>
5177     * <th colspan='4'>StatusUpdates</th>
5178     * </tr>
5179     * <tr>
5180     * <td>long</td>
5181     * <td>{@link #DATA_ID}</td>
5182     * <td>read/write</td>
5183     * <td>Reference to the {@link Data#_ID} entry that owns this presence. If this
5184     * field is <i>not</i> specified, the provider will attempt to find a data row
5185     * that matches the {@link #PROTOCOL} (or {@link #CUSTOM_PROTOCOL}) and
5186     * {@link #IM_HANDLE} columns.
5187     * </td>
5188     * </tr>
5189     * <tr>
5190     * <td>long</td>
5191     * <td>{@link #PROTOCOL}</td>
5192     * <td>read/write</td>
5193     * <td>See {@link CommonDataKinds.Im} for a list of defined protocol constants.</td>
5194     * </tr>
5195     * <tr>
5196     * <td>String</td>
5197     * <td>{@link #CUSTOM_PROTOCOL}</td>
5198     * <td>read/write</td>
5199     * <td>Name of the custom protocol.  Should be supplied along with the {@link #PROTOCOL} value
5200     * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}.  Should be null or
5201     * omitted if {@link #PROTOCOL} value is not
5202     * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}.</td>
5203     * </tr>
5204     * <tr>
5205     * <td>String</td>
5206     * <td>{@link #IM_HANDLE}</td>
5207     * <td>read/write</td>
5208     * <td> The IM handle the presence item is for. The handle is scoped to
5209     * {@link #PROTOCOL}.</td>
5210     * </tr>
5211     * <tr>
5212     * <td>String</td>
5213     * <td>{@link #IM_ACCOUNT}</td>
5214     * <td>read/write</td>
5215     * <td>The IM account for the local user that the presence data came from.</td>
5216     * </tr>
5217     * <tr>
5218     * <td>int</td>
5219     * <td>{@link #PRESENCE}</td>
5220     * <td>read/write</td>
5221     * <td>Contact IM presence status. The allowed values are:
5222     * <p>
5223     * <ul>
5224     * <li>{@link #OFFLINE}</li>
5225     * <li>{@link #INVISIBLE}</li>
5226     * <li>{@link #AWAY}</li>
5227     * <li>{@link #IDLE}</li>
5228     * <li>{@link #DO_NOT_DISTURB}</li>
5229     * <li>{@link #AVAILABLE}</li>
5230     * </ul>
5231     * </p>
5232     * <p>
5233     * Since presence status is inherently volatile, the content provider
5234     * may choose not to store this field in long-term storage.
5235     * </p>
5236     * </td>
5237     * </tr>
5238     * <tr>
5239     * <td>int</td>
5240     * <td>{@link #CHAT_CAPABILITY}</td>
5241     * <td>read/write</td>
5242     * <td>Contact IM chat compatibility value. The allowed values combinations of the following
5243     * flags. If None of these flags is set, the device can only do text messaging.
5244     * <p>
5245     * <ul>
5246     * <li>{@link #CAPABILITY_HAS_VIDEO}</li>
5247     * <li>{@link #CAPABILITY_HAS_VOICE}</li>
5248     * <li>{@link #CAPABILITY_HAS_CAMERA}</li>
5249     * </ul>
5250     * </p>
5251     * <p>
5252     * Since chat compatibility is inherently volatile as the contact's availability moves from
5253     * one device to another, the content provider may choose not to store this field in long-term
5254     * storage.
5255     * </p>
5256     * </td>
5257     * </tr>
5258     * <tr>
5259     * <td>String</td>
5260     * <td>{@link #STATUS}</td>
5261     * <td>read/write</td>
5262     * <td>Contact's latest status update, e.g. "having toast for breakfast"</td>
5263     * </tr>
5264     * <tr>
5265     * <td>long</td>
5266     * <td>{@link #STATUS_TIMESTAMP}</td>
5267     * <td>read/write</td>
5268     * <td>The absolute time in milliseconds when the status was
5269     * entered by the user. If this value is not provided, the provider will follow
5270     * this logic: if there was no prior status update, the value will be left as null.
5271     * If there was a prior status update, the provider will default this field
5272     * to the current time.</td>
5273     * </tr>
5274     * <tr>
5275     * <td>String</td>
5276     * <td>{@link #STATUS_RES_PACKAGE}</td>
5277     * <td>read/write</td>
5278     * <td> The package containing resources for this status: label and icon.</td>
5279     * </tr>
5280     * <tr>
5281     * <td>long</td>
5282     * <td>{@link #STATUS_LABEL}</td>
5283     * <td>read/write</td>
5284     * <td>The resource ID of the label describing the source of contact status,
5285     * e.g. "Google Talk". This resource is scoped by the
5286     * {@link #STATUS_RES_PACKAGE}.</td>
5287     * </tr>
5288     * <tr>
5289     * <td>long</td>
5290     * <td>{@link #STATUS_ICON}</td>
5291     * <td>read/write</td>
5292     * <td>The resource ID of the icon for the source of contact status. This
5293     * resource is scoped by the {@link #STATUS_RES_PACKAGE}.</td>
5294     * </tr>
5295     * </table>
5296     */
5297    public static class StatusUpdates implements StatusColumns, PresenceColumns {
5298
5299        /**
5300         * This utility class cannot be instantiated
5301         */
5302        private StatusUpdates() {}
5303
5304        /**
5305         * The content:// style URI for this table
5306         */
5307        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "status_updates");
5308
5309        /**
5310         * The content:// style URI for this table, specific to the user's profile.
5311         */
5312        public static final Uri PROFILE_CONTENT_URI =
5313                Uri.withAppendedPath(Profile.CONTENT_URI, "status_updates");
5314
5315        /**
5316         * Gets the resource ID for the proper presence icon.
5317         *
5318         * @param status the status to get the icon for
5319         * @return the resource ID for the proper presence icon
5320         */
5321        public static final int getPresenceIconResourceId(int status) {
5322            switch (status) {
5323                case AVAILABLE:
5324                    return android.R.drawable.presence_online;
5325                case IDLE:
5326                case AWAY:
5327                    return android.R.drawable.presence_away;
5328                case DO_NOT_DISTURB:
5329                    return android.R.drawable.presence_busy;
5330                case INVISIBLE:
5331                    return android.R.drawable.presence_invisible;
5332                case OFFLINE:
5333                default:
5334                    return android.R.drawable.presence_offline;
5335            }
5336        }
5337
5338        /**
5339         * Returns the precedence of the status code the higher number being the higher precedence.
5340         *
5341         * @param status The status code.
5342         * @return An integer representing the precedence, 0 being the lowest.
5343         */
5344        public static final int getPresencePrecedence(int status) {
5345            // Keep this function here incase we want to enforce a different precedence than the
5346            // natural order of the status constants.
5347            return status;
5348        }
5349
5350        /**
5351         * The MIME type of {@link #CONTENT_URI} providing a directory of
5352         * status update details.
5353         */
5354        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/status-update";
5355
5356        /**
5357         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single
5358         * status update detail.
5359         */
5360        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/status-update";
5361    }
5362
5363    /**
5364     * @deprecated This old name was never meant to be made public. Do not use.
5365     */
5366    @Deprecated
5367    public static final class Presence extends StatusUpdates {
5368
5369    }
5370
5371    /**
5372     * Additional column returned by
5373     * {@link ContactsContract.Contacts#CONTENT_FILTER_URI Contacts.CONTENT_FILTER_URI} explaining
5374     * why the filter matched the contact. This column will contain extracts from the contact's
5375     * constituent {@link Data Data} items, formatted in a way that indicates the section of the
5376     * snippet that matched the filter.
5377     *
5378     * <p>
5379     * The following example searches for all contacts that match the query "presi" and requests
5380     * the snippet column as well.
5381     * <pre>
5382     * Builder builder = Contacts.CONTENT_FILTER_URI.buildUpon();
5383     * builder.appendPath("presi");
5384     * // Defer snippeting to the client side if possible, for performance reasons.
5385     * builder.appendQueryParameter(SearchSnippets.DEFERRED_SNIPPETING_KEY,"1");
5386     *
5387     * Cursor cursor = getContentResolver().query(builder.build());
5388     *
5389     * Bundle extras = cursor.getExtras();
5390     * if (extras.getBoolean(ContactsContract.DEFERRED_SNIPPETING)) {
5391     *     // Do our own snippet formatting.
5392     *     // For a contact with the email address (president@organization.com), the snippet
5393     *     // column will contain the string "president@organization.com".
5394     * } else {
5395     *     // The snippet has already been pre-formatted, we can display it as is.
5396     *     // For a contact with the email address (president@organization.com), the snippet
5397     *     // column will contain the string "[presi]dent@organization.com".
5398     * }
5399     * </pre>
5400     * </p>
5401     */
5402    public static class SearchSnippets {
5403
5404        /**
5405         * The search snippet constructed by SQLite snippeting functionality.
5406         * <p>
5407         * The snippet may contain (parts of) several data elements belonging to the contact,
5408         * with the matching parts optionally surrounded by special characters that indicate the
5409         * start and end of matching text.
5410         *
5411         * For example, if a contact has an address "123 Main Street", using a filter "mai" would
5412         * return the formatted snippet "123 [Mai]n street".
5413         *
5414         * @see <a href="http://www.sqlite.org/fts3.html#snippet">
5415         *         http://www.sqlite.org/fts3.html#snippet</a>
5416         */
5417        public static final String SNIPPET = "snippet";
5418
5419        /**
5420         * Comma-separated parameters for the generation of the snippet:
5421         * <ul>
5422         * <li>The "start match" text. Default is '['</li>
5423         * <li>The "end match" text. Default is ']'</li>
5424         * <li>The "ellipsis" text. Default is "..."</li>
5425         * <li>Maximum number of tokens to include in the snippet. Can be either
5426         * a positive or a negative number: A positive number indicates how many
5427         * tokens can be returned in total. A negative number indicates how many
5428         * tokens can be returned per occurrence of the search terms.</li>
5429         * </ul>
5430         *
5431         * @hide
5432         */
5433        public static final String SNIPPET_ARGS_PARAM_KEY = "snippet_args";
5434
5435        /**
5436         * The key to ask the provider to defer the formatting of the snippet to the client if
5437         * possible, for performance reasons.
5438         * A value of 1 indicates true, 0 indicates false. False is the default.
5439         * When a cursor is returned to the client, it should check for an extra with the name
5440         * {@link ContactsContract#DEFERRED_SNIPPETING} in the cursor. If it exists, the client
5441         * should do its own formatting of the snippet. If it doesn't exist, the snippet column
5442         * in the cursor should already contain a formatted snippet.
5443         */
5444        public static final String DEFERRED_SNIPPETING_KEY = "deferred_snippeting";
5445    }
5446
5447    /**
5448     * Container for definitions of common data types stored in the {@link ContactsContract.Data}
5449     * table.
5450     */
5451    public static final class CommonDataKinds {
5452        /**
5453         * This utility class cannot be instantiated
5454         */
5455        private CommonDataKinds() {}
5456
5457        /**
5458         * The {@link Data#RES_PACKAGE} value for common data that should be
5459         * shown using a default style.
5460         *
5461         * @hide RES_PACKAGE is hidden
5462         */
5463        public static final String PACKAGE_COMMON = "common";
5464
5465        /**
5466         * The base types that all "Typed" data kinds support.
5467         */
5468        public interface BaseTypes {
5469            /**
5470             * A custom type. The custom label should be supplied by user.
5471             */
5472            public static int TYPE_CUSTOM = 0;
5473        }
5474
5475        /**
5476         * Columns common across the specific types.
5477         */
5478        protected interface CommonColumns extends BaseTypes {
5479            /**
5480             * The data for the contact method.
5481             * <P>Type: TEXT</P>
5482             */
5483            public static final String DATA = DataColumns.DATA1;
5484
5485            /**
5486             * The type of data, for example Home or Work.
5487             * <P>Type: INTEGER</P>
5488             */
5489            public static final String TYPE = DataColumns.DATA2;
5490
5491            /**
5492             * The user defined label for the the contact method.
5493             * <P>Type: TEXT</P>
5494             */
5495            public static final String LABEL = DataColumns.DATA3;
5496        }
5497
5498        /**
5499         * A data kind representing the contact's proper name. You can use all
5500         * columns defined for {@link ContactsContract.Data} as well as the following aliases.
5501         *
5502         * <h2>Column aliases</h2>
5503         * <table class="jd-sumtable">
5504         * <tr>
5505         * <th>Type</th><th>Alias</th><th colspan='2'>Data column</th>
5506         * </tr>
5507         * <tr>
5508         * <td>String</td>
5509         * <td>{@link #DISPLAY_NAME}</td>
5510         * <td>{@link #DATA1}</td>
5511         * <td></td>
5512         * </tr>
5513         * <tr>
5514         * <td>String</td>
5515         * <td>{@link #GIVEN_NAME}</td>
5516         * <td>{@link #DATA2}</td>
5517         * <td></td>
5518         * </tr>
5519         * <tr>
5520         * <td>String</td>
5521         * <td>{@link #FAMILY_NAME}</td>
5522         * <td>{@link #DATA3}</td>
5523         * <td></td>
5524         * </tr>
5525         * <tr>
5526         * <td>String</td>
5527         * <td>{@link #PREFIX}</td>
5528         * <td>{@link #DATA4}</td>
5529         * <td>Common prefixes in English names are "Mr", "Ms", "Dr" etc.</td>
5530         * </tr>
5531         * <tr>
5532         * <td>String</td>
5533         * <td>{@link #MIDDLE_NAME}</td>
5534         * <td>{@link #DATA5}</td>
5535         * <td></td>
5536         * </tr>
5537         * <tr>
5538         * <td>String</td>
5539         * <td>{@link #SUFFIX}</td>
5540         * <td>{@link #DATA6}</td>
5541         * <td>Common suffixes in English names are "Sr", "Jr", "III" etc.</td>
5542         * </tr>
5543         * <tr>
5544         * <td>String</td>
5545         * <td>{@link #PHONETIC_GIVEN_NAME}</td>
5546         * <td>{@link #DATA7}</td>
5547         * <td>Used for phonetic spelling of the name, e.g. Pinyin, Katakana, Hiragana</td>
5548         * </tr>
5549         * <tr>
5550         * <td>String</td>
5551         * <td>{@link #PHONETIC_MIDDLE_NAME}</td>
5552         * <td>{@link #DATA8}</td>
5553         * <td></td>
5554         * </tr>
5555         * <tr>
5556         * <td>String</td>
5557         * <td>{@link #PHONETIC_FAMILY_NAME}</td>
5558         * <td>{@link #DATA9}</td>
5559         * <td></td>
5560         * </tr>
5561         * </table>
5562         */
5563        public static final class StructuredName implements DataColumnsWithJoins, ContactCounts {
5564            /**
5565             * This utility class cannot be instantiated
5566             */
5567            private StructuredName() {}
5568
5569            /** MIME type used when storing this in data table. */
5570            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/name";
5571
5572            /**
5573             * The name that should be used to display the contact.
5574             * <i>Unstructured component of the name should be consistent with
5575             * its structured representation.</i>
5576             * <p>
5577             * Type: TEXT
5578             */
5579            public static final String DISPLAY_NAME = DATA1;
5580
5581            /**
5582             * The given name for the contact.
5583             * <P>Type: TEXT</P>
5584             */
5585            public static final String GIVEN_NAME = DATA2;
5586
5587            /**
5588             * The family name for the contact.
5589             * <P>Type: TEXT</P>
5590             */
5591            public static final String FAMILY_NAME = DATA3;
5592
5593            /**
5594             * The contact's honorific prefix, e.g. "Sir"
5595             * <P>Type: TEXT</P>
5596             */
5597            public static final String PREFIX = DATA4;
5598
5599            /**
5600             * The contact's middle name
5601             * <P>Type: TEXT</P>
5602             */
5603            public static final String MIDDLE_NAME = DATA5;
5604
5605            /**
5606             * The contact's honorific suffix, e.g. "Jr"
5607             */
5608            public static final String SUFFIX = DATA6;
5609
5610            /**
5611             * The phonetic version of the given name for the contact.
5612             * <P>Type: TEXT</P>
5613             */
5614            public static final String PHONETIC_GIVEN_NAME = DATA7;
5615
5616            /**
5617             * The phonetic version of the additional name for the contact.
5618             * <P>Type: TEXT</P>
5619             */
5620            public static final String PHONETIC_MIDDLE_NAME = DATA8;
5621
5622            /**
5623             * The phonetic version of the family name for the contact.
5624             * <P>Type: TEXT</P>
5625             */
5626            public static final String PHONETIC_FAMILY_NAME = DATA9;
5627
5628            /**
5629             * The style used for combining given/middle/family name into a full name.
5630             * See {@link ContactsContract.FullNameStyle}.
5631             */
5632            public static final String FULL_NAME_STYLE = DATA10;
5633
5634            /**
5635             * The alphabet used for capturing the phonetic name.
5636             * See ContactsContract.PhoneticNameStyle.
5637             * @hide
5638             */
5639            public static final String PHONETIC_NAME_STYLE = DATA11;
5640        }
5641
5642        /**
5643         * <p>A data kind representing the contact's nickname. For example, for
5644         * Bob Parr ("Mr. Incredible"):
5645         * <pre>
5646         * ArrayList&lt;ContentProviderOperation&gt; ops =
5647         *          new ArrayList&lt;ContentProviderOperation&gt;();
5648         *
5649         * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
5650         *          .withValue(Data.RAW_CONTACT_ID, rawContactId)
5651         *          .withValue(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE)
5652         *          .withValue(StructuredName.DISPLAY_NAME, &quot;Bob Parr&quot;)
5653         *          .build());
5654         *
5655         * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
5656         *          .withValue(Data.RAW_CONTACT_ID, rawContactId)
5657         *          .withValue(Data.MIMETYPE, Nickname.CONTENT_ITEM_TYPE)
5658         *          .withValue(Nickname.NAME, "Mr. Incredible")
5659         *          .withValue(Nickname.TYPE, Nickname.TYPE_CUSTOM)
5660         *          .withValue(Nickname.LABEL, "Superhero")
5661         *          .build());
5662         *
5663         * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
5664         * </pre>
5665         * </p>
5666         * <p>
5667         * You can use all columns defined for {@link ContactsContract.Data} as well as the
5668         * following aliases.
5669         * </p>
5670         *
5671         * <h2>Column aliases</h2>
5672         * <table class="jd-sumtable">
5673         * <tr>
5674         * <th>Type</th><th>Alias</th><th colspan='2'>Data column</th>
5675         * </tr>
5676         * <tr>
5677         * <td>String</td>
5678         * <td>{@link #NAME}</td>
5679         * <td>{@link #DATA1}</td>
5680         * <td></td>
5681         * </tr>
5682         * <tr>
5683         * <td>int</td>
5684         * <td>{@link #TYPE}</td>
5685         * <td>{@link #DATA2}</td>
5686         * <td>
5687         * Allowed values are:
5688         * <p>
5689         * <ul>
5690         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
5691         * <li>{@link #TYPE_DEFAULT}</li>
5692         * <li>{@link #TYPE_OTHER_NAME}</li>
5693         * <li>{@link #TYPE_MAIDEN_NAME}</li>
5694         * <li>{@link #TYPE_SHORT_NAME}</li>
5695         * <li>{@link #TYPE_INITIALS}</li>
5696         * </ul>
5697         * </p>
5698         * </td>
5699         * </tr>
5700         * <tr>
5701         * <td>String</td>
5702         * <td>{@link #LABEL}</td>
5703         * <td>{@link #DATA3}</td>
5704         * <td></td>
5705         * </tr>
5706         * </table>
5707         */
5708        public static final class Nickname implements DataColumnsWithJoins, CommonColumns,
5709                ContactCounts{
5710            /**
5711             * This utility class cannot be instantiated
5712             */
5713            private Nickname() {}
5714
5715            /** MIME type used when storing this in data table. */
5716            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/nickname";
5717
5718            public static final int TYPE_DEFAULT = 1;
5719            public static final int TYPE_OTHER_NAME = 2;
5720            public static final int TYPE_MAIDEN_NAME = 3;
5721            /** @deprecated Use TYPE_MAIDEN_NAME instead. */
5722            @Deprecated
5723            public static final int TYPE_MAINDEN_NAME = 3;
5724            public static final int TYPE_SHORT_NAME = 4;
5725            public static final int TYPE_INITIALS = 5;
5726
5727            /**
5728             * The name itself
5729             */
5730            public static final String NAME = DATA;
5731        }
5732
5733        /**
5734         * <p>
5735         * A data kind representing a telephone number.
5736         * </p>
5737         * <p>
5738         * You can use all columns defined for {@link ContactsContract.Data} as
5739         * well as the following aliases.
5740         * </p>
5741         * <h2>Column aliases</h2>
5742         * <table class="jd-sumtable">
5743         * <tr>
5744         * <th>Type</th>
5745         * <th>Alias</th><th colspan='2'>Data column</th>
5746         * </tr>
5747         * <tr>
5748         * <td>String</td>
5749         * <td>{@link #NUMBER}</td>
5750         * <td>{@link #DATA1}</td>
5751         * <td></td>
5752         * </tr>
5753         * <tr>
5754         * <td>int</td>
5755         * <td>{@link #TYPE}</td>
5756         * <td>{@link #DATA2}</td>
5757         * <td>Allowed values are:
5758         * <p>
5759         * <ul>
5760         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
5761         * <li>{@link #TYPE_HOME}</li>
5762         * <li>{@link #TYPE_MOBILE}</li>
5763         * <li>{@link #TYPE_WORK}</li>
5764         * <li>{@link #TYPE_FAX_WORK}</li>
5765         * <li>{@link #TYPE_FAX_HOME}</li>
5766         * <li>{@link #TYPE_PAGER}</li>
5767         * <li>{@link #TYPE_OTHER}</li>
5768         * <li>{@link #TYPE_CALLBACK}</li>
5769         * <li>{@link #TYPE_CAR}</li>
5770         * <li>{@link #TYPE_COMPANY_MAIN}</li>
5771         * <li>{@link #TYPE_ISDN}</li>
5772         * <li>{@link #TYPE_MAIN}</li>
5773         * <li>{@link #TYPE_OTHER_FAX}</li>
5774         * <li>{@link #TYPE_RADIO}</li>
5775         * <li>{@link #TYPE_TELEX}</li>
5776         * <li>{@link #TYPE_TTY_TDD}</li>
5777         * <li>{@link #TYPE_WORK_MOBILE}</li>
5778         * <li>{@link #TYPE_WORK_PAGER}</li>
5779         * <li>{@link #TYPE_ASSISTANT}</li>
5780         * <li>{@link #TYPE_MMS}</li>
5781         * </ul>
5782         * </p>
5783         * </td>
5784         * </tr>
5785         * <tr>
5786         * <td>String</td>
5787         * <td>{@link #LABEL}</td>
5788         * <td>{@link #DATA3}</td>
5789         * <td></td>
5790         * </tr>
5791         * </table>
5792         */
5793        public static final class Phone implements DataColumnsWithJoins, CommonColumns,
5794                ContactCounts {
5795            /**
5796             * This utility class cannot be instantiated
5797             */
5798            private Phone() {}
5799
5800            /** MIME type used when storing this in data table. */
5801            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone_v2";
5802
5803            /**
5804             * The MIME type of {@link #CONTENT_URI} providing a directory of
5805             * phones.
5806             */
5807            public static final String CONTENT_TYPE = "vnd.android.cursor.dir/phone_v2";
5808
5809            /**
5810             * The content:// style URI for all data records of the
5811             * {@link #CONTENT_ITEM_TYPE} MIME type, combined with the
5812             * associated raw contact and aggregate contact data.
5813             */
5814            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
5815                    "phones");
5816
5817            /**
5818            * URI used for getting all contacts from primary and managed profile.
5819            *
5820            * It supports the same semantics as {@link #CONTENT_URI} and returns the same
5821            * columns.  If the device has no corp profile that is linked to the current profile, it
5822            * behaves in the exact same way as {@link #CONTENT_URI}.  If there is a corp profile
5823            * linked to the current profile, it will merge corp profile and current profile's
5824            * results and return
5825            *
5826            * @hide
5827            */
5828            public static final Uri ENTERPRISE_CONTENT_URI =
5829                    Uri.withAppendedPath(Data.ENTERPRISE_CONTENT_URI, "phones");
5830
5831            /**
5832             * The content:// style URL for phone lookup using a filter. The filter returns
5833             * records of MIME type {@link #CONTENT_ITEM_TYPE}. The filter is applied
5834             * to display names as well as phone numbers. The filter argument should be passed
5835             * as an additional path segment after this URI.
5836             */
5837            public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI,
5838                    "filter");
5839
5840            /**
5841             * A boolean query parameter that can be used with {@link #CONTENT_FILTER_URI}.
5842             * If "1" or "true", display names are searched.  If "0" or "false", display names
5843             * are not searched.  Default is "1".
5844             */
5845            public static final String SEARCH_DISPLAY_NAME_KEY = "search_display_name";
5846
5847            /**
5848             * A boolean query parameter that can be used with {@link #CONTENT_FILTER_URI}.
5849             * If "1" or "true", phone numbers are searched.  If "0" or "false", phone numbers
5850             * are not searched.  Default is "1".
5851             */
5852            public static final String SEARCH_PHONE_NUMBER_KEY = "search_phone_number";
5853
5854            public static final int TYPE_HOME = 1;
5855            public static final int TYPE_MOBILE = 2;
5856            public static final int TYPE_WORK = 3;
5857            public static final int TYPE_FAX_WORK = 4;
5858            public static final int TYPE_FAX_HOME = 5;
5859            public static final int TYPE_PAGER = 6;
5860            public static final int TYPE_OTHER = 7;
5861            public static final int TYPE_CALLBACK = 8;
5862            public static final int TYPE_CAR = 9;
5863            public static final int TYPE_COMPANY_MAIN = 10;
5864            public static final int TYPE_ISDN = 11;
5865            public static final int TYPE_MAIN = 12;
5866            public static final int TYPE_OTHER_FAX = 13;
5867            public static final int TYPE_RADIO = 14;
5868            public static final int TYPE_TELEX = 15;
5869            public static final int TYPE_TTY_TDD = 16;
5870            public static final int TYPE_WORK_MOBILE = 17;
5871            public static final int TYPE_WORK_PAGER = 18;
5872            public static final int TYPE_ASSISTANT = 19;
5873            public static final int TYPE_MMS = 20;
5874
5875            /**
5876             * The phone number as the user entered it.
5877             * <P>Type: TEXT</P>
5878             */
5879            public static final String NUMBER = DATA;
5880
5881            /**
5882             * The phone number's E164 representation. This value can be omitted in which
5883             * case the provider will try to automatically infer it.  (It'll be left null if the
5884             * provider fails to infer.)
5885             * If present, {@link #NUMBER} has to be set as well (it will be ignored otherwise).
5886             * <P>Type: TEXT</P>
5887             */
5888            public static final String NORMALIZED_NUMBER = DATA4;
5889
5890            /**
5891             * @deprecated use {@link #getTypeLabel(Resources, int, CharSequence)} instead.
5892             * @hide
5893             */
5894            @Deprecated
5895            public static final CharSequence getDisplayLabel(Context context, int type,
5896                    CharSequence label, CharSequence[] labelArray) {
5897                return getTypeLabel(context.getResources(), type, label);
5898            }
5899
5900            /**
5901             * @deprecated use {@link #getTypeLabel(Resources, int, CharSequence)} instead.
5902             * @hide
5903             */
5904            @Deprecated
5905            public static final CharSequence getDisplayLabel(Context context, int type,
5906                    CharSequence label) {
5907                return getTypeLabel(context.getResources(), type, label);
5908            }
5909
5910            /**
5911             * Return the string resource that best describes the given
5912             * {@link #TYPE}. Will always return a valid resource.
5913             */
5914            public static final int getTypeLabelResource(int type) {
5915                switch (type) {
5916                    case TYPE_HOME: return com.android.internal.R.string.phoneTypeHome;
5917                    case TYPE_MOBILE: return com.android.internal.R.string.phoneTypeMobile;
5918                    case TYPE_WORK: return com.android.internal.R.string.phoneTypeWork;
5919                    case TYPE_FAX_WORK: return com.android.internal.R.string.phoneTypeFaxWork;
5920                    case TYPE_FAX_HOME: return com.android.internal.R.string.phoneTypeFaxHome;
5921                    case TYPE_PAGER: return com.android.internal.R.string.phoneTypePager;
5922                    case TYPE_OTHER: return com.android.internal.R.string.phoneTypeOther;
5923                    case TYPE_CALLBACK: return com.android.internal.R.string.phoneTypeCallback;
5924                    case TYPE_CAR: return com.android.internal.R.string.phoneTypeCar;
5925                    case TYPE_COMPANY_MAIN: return com.android.internal.R.string.phoneTypeCompanyMain;
5926                    case TYPE_ISDN: return com.android.internal.R.string.phoneTypeIsdn;
5927                    case TYPE_MAIN: return com.android.internal.R.string.phoneTypeMain;
5928                    case TYPE_OTHER_FAX: return com.android.internal.R.string.phoneTypeOtherFax;
5929                    case TYPE_RADIO: return com.android.internal.R.string.phoneTypeRadio;
5930                    case TYPE_TELEX: return com.android.internal.R.string.phoneTypeTelex;
5931                    case TYPE_TTY_TDD: return com.android.internal.R.string.phoneTypeTtyTdd;
5932                    case TYPE_WORK_MOBILE: return com.android.internal.R.string.phoneTypeWorkMobile;
5933                    case TYPE_WORK_PAGER: return com.android.internal.R.string.phoneTypeWorkPager;
5934                    case TYPE_ASSISTANT: return com.android.internal.R.string.phoneTypeAssistant;
5935                    case TYPE_MMS: return com.android.internal.R.string.phoneTypeMms;
5936                    default: return com.android.internal.R.string.phoneTypeCustom;
5937                }
5938            }
5939
5940            /**
5941             * Return a {@link CharSequence} that best describes the given type,
5942             * possibly substituting the given {@link #LABEL} value
5943             * for {@link #TYPE_CUSTOM}.
5944             */
5945            public static final CharSequence getTypeLabel(Resources res, int type,
5946                    CharSequence label) {
5947                if ((type == TYPE_CUSTOM || type == TYPE_ASSISTANT) && !TextUtils.isEmpty(label)) {
5948                    return label;
5949                } else {
5950                    final int labelRes = getTypeLabelResource(type);
5951                    return res.getText(labelRes);
5952                }
5953            }
5954        }
5955
5956        /**
5957         * <p>
5958         * A data kind representing an email address.
5959         * </p>
5960         * <p>
5961         * You can use all columns defined for {@link ContactsContract.Data} as
5962         * well as the following aliases.
5963         * </p>
5964         * <h2>Column aliases</h2>
5965         * <table class="jd-sumtable">
5966         * <tr>
5967         * <th>Type</th>
5968         * <th>Alias</th><th colspan='2'>Data column</th>
5969         * </tr>
5970         * <tr>
5971         * <td>String</td>
5972         * <td>{@link #ADDRESS}</td>
5973         * <td>{@link #DATA1}</td>
5974         * <td>Email address itself.</td>
5975         * </tr>
5976         * <tr>
5977         * <td>int</td>
5978         * <td>{@link #TYPE}</td>
5979         * <td>{@link #DATA2}</td>
5980         * <td>Allowed values are:
5981         * <p>
5982         * <ul>
5983         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
5984         * <li>{@link #TYPE_HOME}</li>
5985         * <li>{@link #TYPE_WORK}</li>
5986         * <li>{@link #TYPE_OTHER}</li>
5987         * <li>{@link #TYPE_MOBILE}</li>
5988         * </ul>
5989         * </p>
5990         * </td>
5991         * </tr>
5992         * <tr>
5993         * <td>String</td>
5994         * <td>{@link #LABEL}</td>
5995         * <td>{@link #DATA3}</td>
5996         * <td></td>
5997         * </tr>
5998         * </table>
5999         */
6000        public static final class Email implements DataColumnsWithJoins, CommonColumns,
6001                ContactCounts {
6002            /**
6003             * This utility class cannot be instantiated
6004             */
6005            private Email() {}
6006
6007            /** MIME type used when storing this in data table. */
6008            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/email_v2";
6009
6010            /**
6011             * The MIME type of {@link #CONTENT_URI} providing a directory of email addresses.
6012             */
6013            public static final String CONTENT_TYPE = "vnd.android.cursor.dir/email_v2";
6014
6015            /**
6016             * The content:// style URI for all data records of the
6017             * {@link #CONTENT_ITEM_TYPE} MIME type, combined with the
6018             * associated raw contact and aggregate contact data.
6019             */
6020            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
6021                    "emails");
6022
6023            /**
6024             * <p>
6025             * The content:// style URL for looking up data rows by email address. The
6026             * lookup argument, an email address, should be passed as an additional path segment
6027             * after this URI.
6028             * </p>
6029             * <p>Example:
6030             * <pre>
6031             * Uri uri = Uri.withAppendedPath(Email.CONTENT_LOOKUP_URI, Uri.encode(email));
6032             * Cursor c = getContentResolver().query(uri,
6033             *          new String[]{Email.CONTACT_ID, Email.DISPLAY_NAME, Email.DATA},
6034             *          null, null, null);
6035             * </pre>
6036             * </p>
6037             */
6038            public static final Uri CONTENT_LOOKUP_URI = Uri.withAppendedPath(CONTENT_URI,
6039                    "lookup");
6040
6041            /**
6042            * <p>URI used for enterprise email lookup.</p>
6043            *
6044            * <p>
6045            * It supports the same semantics as {@link #CONTENT_LOOKUP_URI} and returns the same
6046            * columns.  If the device has no corp profile that is linked to the current profile, it
6047            * behaves in the exact same way as {@link #CONTENT_LOOKUP_URI}.  If there is a
6048            * corp profile linked to the current profile, it first queries against the personal contact database,
6049            * and if no matching contacts are found there, then queries against the
6050            * corp contacts database.
6051            * </p>
6052            * <p>
6053            * If a result is from the corp profile, it makes the following changes to the data:
6054            * <ul>
6055            *     <li>
6056            *     {@link #PHOTO_THUMBNAIL_URI} and {@link #PHOTO_URI} will be rewritten to special
6057            *     URIs.  Use {@link ContentResolver#openAssetFileDescriptor} or its siblings to
6058            *     load pictures from them.
6059            *     {@link #PHOTO_ID} and {@link #PHOTO_FILE_ID} will be set to null.  Do not
6060            *     use them.
6061            *     </li>
6062            *     <li>
6063            *     Corp contacts will get artificial {@link #CONTACT_ID}s.  In order to tell whether
6064            *     a contact
6065            *     is from the corp profile, use
6066            *     {@link ContactsContract.Contacts#isEnterpriseContactId(long)}.
6067             *     </li>
6068             *     <li>
6069             *     Corp contacts will get artificial {@link #LOOKUP_KEY}s too.
6070             *     </li>
6071             * </ul>
6072             * <p>
6073             * A contact lookup URL built by
6074             * {@link ContactsContract.Contacts#getLookupUri(long, String)}
6075             * with an {@link #_ID} and a {@link #LOOKUP_KEY} returned by this API can be passed to
6076             * {@link ContactsContract.QuickContact#showQuickContact} even if a contact is from the
6077             * corp profile.
6078             * </p>
6079            *
6080            * <pre>
6081            * Uri lookupUri = Uri.withAppendedPath(Email.ENTERPRISE_CONTENT_LOOKUP_URI,
6082            *         Uri.encode(email));
6083            * </pre>
6084            */
6085            public static final Uri ENTERPRISE_CONTENT_LOOKUP_URI =
6086                    Uri.withAppendedPath(CONTENT_URI, "lookup_enterprise");
6087
6088            /**
6089             * <p>
6090             * The content:// style URL for email lookup using a filter. The filter returns
6091             * records of MIME type {@link #CONTENT_ITEM_TYPE}. The filter is applied
6092             * to display names as well as email addresses. The filter argument should be passed
6093             * as an additional path segment after this URI.
6094             * </p>
6095             * <p>The query in the following example will return "Robert Parr (bob@incredibles.com)"
6096             * as well as "Bob Parr (incredible@android.com)".
6097             * <pre>
6098             * Uri uri = Uri.withAppendedPath(Email.CONTENT_LOOKUP_URI, Uri.encode("bob"));
6099             * Cursor c = getContentResolver().query(uri,
6100             *          new String[]{Email.DISPLAY_NAME, Email.DATA},
6101             *          null, null, null);
6102             * </pre>
6103             * </p>
6104             */
6105            public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI,
6106                    "filter");
6107
6108            /**
6109             * The email address.
6110             * <P>Type: TEXT</P>
6111             */
6112            public static final String ADDRESS = DATA1;
6113
6114            public static final int TYPE_HOME = 1;
6115            public static final int TYPE_WORK = 2;
6116            public static final int TYPE_OTHER = 3;
6117            public static final int TYPE_MOBILE = 4;
6118
6119            /**
6120             * The display name for the email address
6121             * <P>Type: TEXT</P>
6122             */
6123            public static final String DISPLAY_NAME = DATA4;
6124
6125            /**
6126             * Return the string resource that best describes the given
6127             * {@link #TYPE}. Will always return a valid resource.
6128             */
6129            public static final int getTypeLabelResource(int type) {
6130                switch (type) {
6131                    case TYPE_HOME: return com.android.internal.R.string.emailTypeHome;
6132                    case TYPE_WORK: return com.android.internal.R.string.emailTypeWork;
6133                    case TYPE_OTHER: return com.android.internal.R.string.emailTypeOther;
6134                    case TYPE_MOBILE: return com.android.internal.R.string.emailTypeMobile;
6135                    default: return com.android.internal.R.string.emailTypeCustom;
6136                }
6137            }
6138
6139            /**
6140             * Return a {@link CharSequence} that best describes the given type,
6141             * possibly substituting the given {@link #LABEL} value
6142             * for {@link #TYPE_CUSTOM}.
6143             */
6144            public static final CharSequence getTypeLabel(Resources res, int type,
6145                    CharSequence label) {
6146                if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) {
6147                    return label;
6148                } else {
6149                    final int labelRes = getTypeLabelResource(type);
6150                    return res.getText(labelRes);
6151                }
6152            }
6153        }
6154
6155        /**
6156         * <p>
6157         * A data kind representing a postal addresses.
6158         * </p>
6159         * <p>
6160         * You can use all columns defined for {@link ContactsContract.Data} as
6161         * well as the following aliases.
6162         * </p>
6163         * <h2>Column aliases</h2>
6164         * <table class="jd-sumtable">
6165         * <tr>
6166         * <th>Type</th>
6167         * <th>Alias</th><th colspan='2'>Data column</th>
6168         * </tr>
6169         * <tr>
6170         * <td>String</td>
6171         * <td>{@link #FORMATTED_ADDRESS}</td>
6172         * <td>{@link #DATA1}</td>
6173         * <td></td>
6174         * </tr>
6175         * <tr>
6176         * <td>int</td>
6177         * <td>{@link #TYPE}</td>
6178         * <td>{@link #DATA2}</td>
6179         * <td>Allowed values are:
6180         * <p>
6181         * <ul>
6182         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
6183         * <li>{@link #TYPE_HOME}</li>
6184         * <li>{@link #TYPE_WORK}</li>
6185         * <li>{@link #TYPE_OTHER}</li>
6186         * </ul>
6187         * </p>
6188         * </td>
6189         * </tr>
6190         * <tr>
6191         * <td>String</td>
6192         * <td>{@link #LABEL}</td>
6193         * <td>{@link #DATA3}</td>
6194         * <td></td>
6195         * </tr>
6196         * <tr>
6197         * <td>String</td>
6198         * <td>{@link #STREET}</td>
6199         * <td>{@link #DATA4}</td>
6200         * <td></td>
6201         * </tr>
6202         * <tr>
6203         * <td>String</td>
6204         * <td>{@link #POBOX}</td>
6205         * <td>{@link #DATA5}</td>
6206         * <td>Post Office Box number</td>
6207         * </tr>
6208         * <tr>
6209         * <td>String</td>
6210         * <td>{@link #NEIGHBORHOOD}</td>
6211         * <td>{@link #DATA6}</td>
6212         * <td></td>
6213         * </tr>
6214         * <tr>
6215         * <td>String</td>
6216         * <td>{@link #CITY}</td>
6217         * <td>{@link #DATA7}</td>
6218         * <td></td>
6219         * </tr>
6220         * <tr>
6221         * <td>String</td>
6222         * <td>{@link #REGION}</td>
6223         * <td>{@link #DATA8}</td>
6224         * <td></td>
6225         * </tr>
6226         * <tr>
6227         * <td>String</td>
6228         * <td>{@link #POSTCODE}</td>
6229         * <td>{@link #DATA9}</td>
6230         * <td></td>
6231         * </tr>
6232         * <tr>
6233         * <td>String</td>
6234         * <td>{@link #COUNTRY}</td>
6235         * <td>{@link #DATA10}</td>
6236         * <td></td>
6237         * </tr>
6238         * </table>
6239         */
6240        public static final class StructuredPostal implements DataColumnsWithJoins, CommonColumns,
6241                ContactCounts {
6242            /**
6243             * This utility class cannot be instantiated
6244             */
6245            private StructuredPostal() {
6246            }
6247
6248            /** MIME type used when storing this in data table. */
6249            public static final String CONTENT_ITEM_TYPE =
6250                    "vnd.android.cursor.item/postal-address_v2";
6251
6252            /**
6253             * The MIME type of {@link #CONTENT_URI} providing a directory of
6254             * postal addresses.
6255             */
6256            public static final String CONTENT_TYPE = "vnd.android.cursor.dir/postal-address_v2";
6257
6258            /**
6259             * The content:// style URI for all data records of the
6260             * {@link StructuredPostal#CONTENT_ITEM_TYPE} MIME type.
6261             */
6262            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
6263                    "postals");
6264
6265            public static final int TYPE_HOME = 1;
6266            public static final int TYPE_WORK = 2;
6267            public static final int TYPE_OTHER = 3;
6268
6269            /**
6270             * The full, unstructured postal address. <i>This field must be
6271             * consistent with any structured data.</i>
6272             * <p>
6273             * Type: TEXT
6274             */
6275            public static final String FORMATTED_ADDRESS = DATA;
6276
6277            /**
6278             * Can be street, avenue, road, etc. This element also includes the
6279             * house number and room/apartment/flat/floor number.
6280             * <p>
6281             * Type: TEXT
6282             */
6283            public static final String STREET = DATA4;
6284
6285            /**
6286             * Covers actual P.O. boxes, drawers, locked bags, etc. This is
6287             * usually but not always mutually exclusive with street.
6288             * <p>
6289             * Type: TEXT
6290             */
6291            public static final String POBOX = DATA5;
6292
6293            /**
6294             * This is used to disambiguate a street address when a city
6295             * contains more than one street with the same name, or to specify a
6296             * small place whose mail is routed through a larger postal town. In
6297             * China it could be a county or a minor city.
6298             * <p>
6299             * Type: TEXT
6300             */
6301            public static final String NEIGHBORHOOD = DATA6;
6302
6303            /**
6304             * Can be city, village, town, borough, etc. This is the postal town
6305             * and not necessarily the place of residence or place of business.
6306             * <p>
6307             * Type: TEXT
6308             */
6309            public static final String CITY = DATA7;
6310
6311            /**
6312             * A state, province, county (in Ireland), Land (in Germany),
6313             * departement (in France), etc.
6314             * <p>
6315             * Type: TEXT
6316             */
6317            public static final String REGION = DATA8;
6318
6319            /**
6320             * Postal code. Usually country-wide, but sometimes specific to the
6321             * city (e.g. "2" in "Dublin 2, Ireland" addresses).
6322             * <p>
6323             * Type: TEXT
6324             */
6325            public static final String POSTCODE = DATA9;
6326
6327            /**
6328             * The name or code of the country.
6329             * <p>
6330             * Type: TEXT
6331             */
6332            public static final String COUNTRY = DATA10;
6333
6334            /**
6335             * Return the string resource that best describes the given
6336             * {@link #TYPE}. Will always return a valid resource.
6337             */
6338            public static final int getTypeLabelResource(int type) {
6339                switch (type) {
6340                    case TYPE_HOME: return com.android.internal.R.string.postalTypeHome;
6341                    case TYPE_WORK: return com.android.internal.R.string.postalTypeWork;
6342                    case TYPE_OTHER: return com.android.internal.R.string.postalTypeOther;
6343                    default: return com.android.internal.R.string.postalTypeCustom;
6344                }
6345            }
6346
6347            /**
6348             * Return a {@link CharSequence} that best describes the given type,
6349             * possibly substituting the given {@link #LABEL} value
6350             * for {@link #TYPE_CUSTOM}.
6351             */
6352            public static final CharSequence getTypeLabel(Resources res, int type,
6353                    CharSequence label) {
6354                if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) {
6355                    return label;
6356                } else {
6357                    final int labelRes = getTypeLabelResource(type);
6358                    return res.getText(labelRes);
6359                }
6360            }
6361        }
6362
6363        /**
6364         * <p>
6365         * A data kind representing an IM address
6366         * </p>
6367         * <p>
6368         * You can use all columns defined for {@link ContactsContract.Data} as
6369         * well as the following aliases.
6370         * </p>
6371         * <h2>Column aliases</h2>
6372         * <table class="jd-sumtable">
6373         * <tr>
6374         * <th>Type</th>
6375         * <th>Alias</th><th colspan='2'>Data column</th>
6376         * </tr>
6377         * <tr>
6378         * <td>String</td>
6379         * <td>{@link #DATA}</td>
6380         * <td>{@link #DATA1}</td>
6381         * <td></td>
6382         * </tr>
6383         * <tr>
6384         * <td>int</td>
6385         * <td>{@link #TYPE}</td>
6386         * <td>{@link #DATA2}</td>
6387         * <td>Allowed values are:
6388         * <p>
6389         * <ul>
6390         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
6391         * <li>{@link #TYPE_HOME}</li>
6392         * <li>{@link #TYPE_WORK}</li>
6393         * <li>{@link #TYPE_OTHER}</li>
6394         * </ul>
6395         * </p>
6396         * </td>
6397         * </tr>
6398         * <tr>
6399         * <td>String</td>
6400         * <td>{@link #LABEL}</td>
6401         * <td>{@link #DATA3}</td>
6402         * <td></td>
6403         * </tr>
6404         * <tr>
6405         * <td>String</td>
6406         * <td>{@link #PROTOCOL}</td>
6407         * <td>{@link #DATA5}</td>
6408         * <td>
6409         * <p>
6410         * Allowed values:
6411         * <ul>
6412         * <li>{@link #PROTOCOL_CUSTOM}. Also provide the actual protocol name
6413         * as {@link #CUSTOM_PROTOCOL}.</li>
6414         * <li>{@link #PROTOCOL_AIM}</li>
6415         * <li>{@link #PROTOCOL_MSN}</li>
6416         * <li>{@link #PROTOCOL_YAHOO}</li>
6417         * <li>{@link #PROTOCOL_SKYPE}</li>
6418         * <li>{@link #PROTOCOL_QQ}</li>
6419         * <li>{@link #PROTOCOL_GOOGLE_TALK}</li>
6420         * <li>{@link #PROTOCOL_ICQ}</li>
6421         * <li>{@link #PROTOCOL_JABBER}</li>
6422         * <li>{@link #PROTOCOL_NETMEETING}</li>
6423         * </ul>
6424         * </p>
6425         * </td>
6426         * </tr>
6427         * <tr>
6428         * <td>String</td>
6429         * <td>{@link #CUSTOM_PROTOCOL}</td>
6430         * <td>{@link #DATA6}</td>
6431         * <td></td>
6432         * </tr>
6433         * </table>
6434         */
6435        public static final class Im implements DataColumnsWithJoins, CommonColumns, ContactCounts {
6436            /**
6437             * This utility class cannot be instantiated
6438             */
6439            private Im() {}
6440
6441            /** MIME type used when storing this in data table. */
6442            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im";
6443
6444            public static final int TYPE_HOME = 1;
6445            public static final int TYPE_WORK = 2;
6446            public static final int TYPE_OTHER = 3;
6447
6448            /**
6449             * This column should be populated with one of the defined
6450             * constants, e.g. {@link #PROTOCOL_YAHOO}. If the value of this
6451             * column is {@link #PROTOCOL_CUSTOM}, the {@link #CUSTOM_PROTOCOL}
6452             * should contain the name of the custom protocol.
6453             */
6454            public static final String PROTOCOL = DATA5;
6455
6456            public static final String CUSTOM_PROTOCOL = DATA6;
6457
6458            /*
6459             * The predefined IM protocol types.
6460             */
6461            public static final int PROTOCOL_CUSTOM = -1;
6462            public static final int PROTOCOL_AIM = 0;
6463            public static final int PROTOCOL_MSN = 1;
6464            public static final int PROTOCOL_YAHOO = 2;
6465            public static final int PROTOCOL_SKYPE = 3;
6466            public static final int PROTOCOL_QQ = 4;
6467            public static final int PROTOCOL_GOOGLE_TALK = 5;
6468            public static final int PROTOCOL_ICQ = 6;
6469            public static final int PROTOCOL_JABBER = 7;
6470            public static final int PROTOCOL_NETMEETING = 8;
6471
6472            /**
6473             * Return the string resource that best describes the given
6474             * {@link #TYPE}. Will always return a valid resource.
6475             */
6476            public static final int getTypeLabelResource(int type) {
6477                switch (type) {
6478                    case TYPE_HOME: return com.android.internal.R.string.imTypeHome;
6479                    case TYPE_WORK: return com.android.internal.R.string.imTypeWork;
6480                    case TYPE_OTHER: return com.android.internal.R.string.imTypeOther;
6481                    default: return com.android.internal.R.string.imTypeCustom;
6482                }
6483            }
6484
6485            /**
6486             * Return a {@link CharSequence} that best describes the given type,
6487             * possibly substituting the given {@link #LABEL} value
6488             * for {@link #TYPE_CUSTOM}.
6489             */
6490            public static final CharSequence getTypeLabel(Resources res, int type,
6491                    CharSequence label) {
6492                if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) {
6493                    return label;
6494                } else {
6495                    final int labelRes = getTypeLabelResource(type);
6496                    return res.getText(labelRes);
6497                }
6498            }
6499
6500            /**
6501             * Return the string resource that best describes the given
6502             * {@link #PROTOCOL}. Will always return a valid resource.
6503             */
6504            public static final int getProtocolLabelResource(int type) {
6505                switch (type) {
6506                    case PROTOCOL_AIM: return com.android.internal.R.string.imProtocolAim;
6507                    case PROTOCOL_MSN: return com.android.internal.R.string.imProtocolMsn;
6508                    case PROTOCOL_YAHOO: return com.android.internal.R.string.imProtocolYahoo;
6509                    case PROTOCOL_SKYPE: return com.android.internal.R.string.imProtocolSkype;
6510                    case PROTOCOL_QQ: return com.android.internal.R.string.imProtocolQq;
6511                    case PROTOCOL_GOOGLE_TALK: return com.android.internal.R.string.imProtocolGoogleTalk;
6512                    case PROTOCOL_ICQ: return com.android.internal.R.string.imProtocolIcq;
6513                    case PROTOCOL_JABBER: return com.android.internal.R.string.imProtocolJabber;
6514                    case PROTOCOL_NETMEETING: return com.android.internal.R.string.imProtocolNetMeeting;
6515                    default: return com.android.internal.R.string.imProtocolCustom;
6516                }
6517            }
6518
6519            /**
6520             * Return a {@link CharSequence} that best describes the given
6521             * protocol, possibly substituting the given
6522             * {@link #CUSTOM_PROTOCOL} value for {@link #PROTOCOL_CUSTOM}.
6523             */
6524            public static final CharSequence getProtocolLabel(Resources res, int type,
6525                    CharSequence label) {
6526                if (type == PROTOCOL_CUSTOM && !TextUtils.isEmpty(label)) {
6527                    return label;
6528                } else {
6529                    final int labelRes = getProtocolLabelResource(type);
6530                    return res.getText(labelRes);
6531                }
6532            }
6533        }
6534
6535        /**
6536         * <p>
6537         * A data kind representing an organization.
6538         * </p>
6539         * <p>
6540         * You can use all columns defined for {@link ContactsContract.Data} as
6541         * well as the following aliases.
6542         * </p>
6543         * <h2>Column aliases</h2>
6544         * <table class="jd-sumtable">
6545         * <tr>
6546         * <th>Type</th>
6547         * <th>Alias</th><th colspan='2'>Data column</th>
6548         * </tr>
6549         * <tr>
6550         * <td>String</td>
6551         * <td>{@link #COMPANY}</td>
6552         * <td>{@link #DATA1}</td>
6553         * <td></td>
6554         * </tr>
6555         * <tr>
6556         * <td>int</td>
6557         * <td>{@link #TYPE}</td>
6558         * <td>{@link #DATA2}</td>
6559         * <td>Allowed values are:
6560         * <p>
6561         * <ul>
6562         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
6563         * <li>{@link #TYPE_WORK}</li>
6564         * <li>{@link #TYPE_OTHER}</li>
6565         * </ul>
6566         * </p>
6567         * </td>
6568         * </tr>
6569         * <tr>
6570         * <td>String</td>
6571         * <td>{@link #LABEL}</td>
6572         * <td>{@link #DATA3}</td>
6573         * <td></td>
6574         * </tr>
6575         * <tr>
6576         * <td>String</td>
6577         * <td>{@link #TITLE}</td>
6578         * <td>{@link #DATA4}</td>
6579         * <td></td>
6580         * </tr>
6581         * <tr>
6582         * <td>String</td>
6583         * <td>{@link #DEPARTMENT}</td>
6584         * <td>{@link #DATA5}</td>
6585         * <td></td>
6586         * </tr>
6587         * <tr>
6588         * <td>String</td>
6589         * <td>{@link #JOB_DESCRIPTION}</td>
6590         * <td>{@link #DATA6}</td>
6591         * <td></td>
6592         * </tr>
6593         * <tr>
6594         * <td>String</td>
6595         * <td>{@link #SYMBOL}</td>
6596         * <td>{@link #DATA7}</td>
6597         * <td></td>
6598         * </tr>
6599         * <tr>
6600         * <td>String</td>
6601         * <td>{@link #PHONETIC_NAME}</td>
6602         * <td>{@link #DATA8}</td>
6603         * <td></td>
6604         * </tr>
6605         * <tr>
6606         * <td>String</td>
6607         * <td>{@link #OFFICE_LOCATION}</td>
6608         * <td>{@link #DATA9}</td>
6609         * <td></td>
6610         * </tr>
6611         * <tr>
6612         * <td>String</td>
6613         * <td>PHONETIC_NAME_STYLE</td>
6614         * <td>{@link #DATA10}</td>
6615         * <td></td>
6616         * </tr>
6617         * </table>
6618         */
6619        public static final class Organization implements DataColumnsWithJoins, CommonColumns,
6620                ContactCounts {
6621            /**
6622             * This utility class cannot be instantiated
6623             */
6624            private Organization() {}
6625
6626            /** MIME type used when storing this in data table. */
6627            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/organization";
6628
6629            public static final int TYPE_WORK = 1;
6630            public static final int TYPE_OTHER = 2;
6631
6632            /**
6633             * The company as the user entered it.
6634             * <P>Type: TEXT</P>
6635             */
6636            public static final String COMPANY = DATA;
6637
6638            /**
6639             * The position title at this company as the user entered it.
6640             * <P>Type: TEXT</P>
6641             */
6642            public static final String TITLE = DATA4;
6643
6644            /**
6645             * The department at this company as the user entered it.
6646             * <P>Type: TEXT</P>
6647             */
6648            public static final String DEPARTMENT = DATA5;
6649
6650            /**
6651             * The job description at this company as the user entered it.
6652             * <P>Type: TEXT</P>
6653             */
6654            public static final String JOB_DESCRIPTION = DATA6;
6655
6656            /**
6657             * The symbol of this company as the user entered it.
6658             * <P>Type: TEXT</P>
6659             */
6660            public static final String SYMBOL = DATA7;
6661
6662            /**
6663             * The phonetic name of this company as the user entered it.
6664             * <P>Type: TEXT</P>
6665             */
6666            public static final String PHONETIC_NAME = DATA8;
6667
6668            /**
6669             * The office location of this organization.
6670             * <P>Type: TEXT</P>
6671             */
6672            public static final String OFFICE_LOCATION = DATA9;
6673
6674            /**
6675             * The alphabet used for capturing the phonetic name.
6676             * See {@link ContactsContract.PhoneticNameStyle}.
6677             * @hide
6678             */
6679            public static final String PHONETIC_NAME_STYLE = DATA10;
6680
6681            /**
6682             * Return the string resource that best describes the given
6683             * {@link #TYPE}. Will always return a valid resource.
6684             */
6685            public static final int getTypeLabelResource(int type) {
6686                switch (type) {
6687                    case TYPE_WORK: return com.android.internal.R.string.orgTypeWork;
6688                    case TYPE_OTHER: return com.android.internal.R.string.orgTypeOther;
6689                    default: return com.android.internal.R.string.orgTypeCustom;
6690                }
6691            }
6692
6693            /**
6694             * Return a {@link CharSequence} that best describes the given type,
6695             * possibly substituting the given {@link #LABEL} value
6696             * for {@link #TYPE_CUSTOM}.
6697             */
6698            public static final CharSequence getTypeLabel(Resources res, int type,
6699                    CharSequence label) {
6700                if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) {
6701                    return label;
6702                } else {
6703                    final int labelRes = getTypeLabelResource(type);
6704                    return res.getText(labelRes);
6705                }
6706            }
6707        }
6708
6709        /**
6710         * <p>
6711         * A data kind representing a relation.
6712         * </p>
6713         * <p>
6714         * You can use all columns defined for {@link ContactsContract.Data} as
6715         * well as the following aliases.
6716         * </p>
6717         * <h2>Column aliases</h2>
6718         * <table class="jd-sumtable">
6719         * <tr>
6720         * <th>Type</th>
6721         * <th>Alias</th><th colspan='2'>Data column</th>
6722         * </tr>
6723         * <tr>
6724         * <td>String</td>
6725         * <td>{@link #NAME}</td>
6726         * <td>{@link #DATA1}</td>
6727         * <td></td>
6728         * </tr>
6729         * <tr>
6730         * <td>int</td>
6731         * <td>{@link #TYPE}</td>
6732         * <td>{@link #DATA2}</td>
6733         * <td>Allowed values are:
6734         * <p>
6735         * <ul>
6736         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
6737         * <li>{@link #TYPE_ASSISTANT}</li>
6738         * <li>{@link #TYPE_BROTHER}</li>
6739         * <li>{@link #TYPE_CHILD}</li>
6740         * <li>{@link #TYPE_DOMESTIC_PARTNER}</li>
6741         * <li>{@link #TYPE_FATHER}</li>
6742         * <li>{@link #TYPE_FRIEND}</li>
6743         * <li>{@link #TYPE_MANAGER}</li>
6744         * <li>{@link #TYPE_MOTHER}</li>
6745         * <li>{@link #TYPE_PARENT}</li>
6746         * <li>{@link #TYPE_PARTNER}</li>
6747         * <li>{@link #TYPE_REFERRED_BY}</li>
6748         * <li>{@link #TYPE_RELATIVE}</li>
6749         * <li>{@link #TYPE_SISTER}</li>
6750         * <li>{@link #TYPE_SPOUSE}</li>
6751         * </ul>
6752         * </p>
6753         * </td>
6754         * </tr>
6755         * <tr>
6756         * <td>String</td>
6757         * <td>{@link #LABEL}</td>
6758         * <td>{@link #DATA3}</td>
6759         * <td></td>
6760         * </tr>
6761         * </table>
6762         */
6763        public static final class Relation implements DataColumnsWithJoins, CommonColumns,
6764                ContactCounts {
6765            /**
6766             * This utility class cannot be instantiated
6767             */
6768            private Relation() {}
6769
6770            /** MIME type used when storing this in data table. */
6771            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/relation";
6772
6773            public static final int TYPE_ASSISTANT = 1;
6774            public static final int TYPE_BROTHER = 2;
6775            public static final int TYPE_CHILD = 3;
6776            public static final int TYPE_DOMESTIC_PARTNER = 4;
6777            public static final int TYPE_FATHER = 5;
6778            public static final int TYPE_FRIEND = 6;
6779            public static final int TYPE_MANAGER = 7;
6780            public static final int TYPE_MOTHER = 8;
6781            public static final int TYPE_PARENT = 9;
6782            public static final int TYPE_PARTNER = 10;
6783            public static final int TYPE_REFERRED_BY = 11;
6784            public static final int TYPE_RELATIVE = 12;
6785            public static final int TYPE_SISTER = 13;
6786            public static final int TYPE_SPOUSE = 14;
6787
6788            /**
6789             * The name of the relative as the user entered it.
6790             * <P>Type: TEXT</P>
6791             */
6792            public static final String NAME = DATA;
6793
6794            /**
6795             * Return the string resource that best describes the given
6796             * {@link #TYPE}. Will always return a valid resource.
6797             */
6798            public static final int getTypeLabelResource(int type) {
6799                switch (type) {
6800                    case TYPE_ASSISTANT: return com.android.internal.R.string.relationTypeAssistant;
6801                    case TYPE_BROTHER: return com.android.internal.R.string.relationTypeBrother;
6802                    case TYPE_CHILD: return com.android.internal.R.string.relationTypeChild;
6803                    case TYPE_DOMESTIC_PARTNER:
6804                            return com.android.internal.R.string.relationTypeDomesticPartner;
6805                    case TYPE_FATHER: return com.android.internal.R.string.relationTypeFather;
6806                    case TYPE_FRIEND: return com.android.internal.R.string.relationTypeFriend;
6807                    case TYPE_MANAGER: return com.android.internal.R.string.relationTypeManager;
6808                    case TYPE_MOTHER: return com.android.internal.R.string.relationTypeMother;
6809                    case TYPE_PARENT: return com.android.internal.R.string.relationTypeParent;
6810                    case TYPE_PARTNER: return com.android.internal.R.string.relationTypePartner;
6811                    case TYPE_REFERRED_BY:
6812                            return com.android.internal.R.string.relationTypeReferredBy;
6813                    case TYPE_RELATIVE: return com.android.internal.R.string.relationTypeRelative;
6814                    case TYPE_SISTER: return com.android.internal.R.string.relationTypeSister;
6815                    case TYPE_SPOUSE: return com.android.internal.R.string.relationTypeSpouse;
6816                    default: return com.android.internal.R.string.orgTypeCustom;
6817                }
6818            }
6819
6820            /**
6821             * Return a {@link CharSequence} that best describes the given type,
6822             * possibly substituting the given {@link #LABEL} value
6823             * for {@link #TYPE_CUSTOM}.
6824             */
6825            public static final CharSequence getTypeLabel(Resources res, int type,
6826                    CharSequence label) {
6827                if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) {
6828                    return label;
6829                } else {
6830                    final int labelRes = getTypeLabelResource(type);
6831                    return res.getText(labelRes);
6832                }
6833            }
6834        }
6835
6836        /**
6837         * <p>
6838         * A data kind representing an event.
6839         * </p>
6840         * <p>
6841         * You can use all columns defined for {@link ContactsContract.Data} as
6842         * well as the following aliases.
6843         * </p>
6844         * <h2>Column aliases</h2>
6845         * <table class="jd-sumtable">
6846         * <tr>
6847         * <th>Type</th>
6848         * <th>Alias</th><th colspan='2'>Data column</th>
6849         * </tr>
6850         * <tr>
6851         * <td>String</td>
6852         * <td>{@link #START_DATE}</td>
6853         * <td>{@link #DATA1}</td>
6854         * <td></td>
6855         * </tr>
6856         * <tr>
6857         * <td>int</td>
6858         * <td>{@link #TYPE}</td>
6859         * <td>{@link #DATA2}</td>
6860         * <td>Allowed values are:
6861         * <p>
6862         * <ul>
6863         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
6864         * <li>{@link #TYPE_ANNIVERSARY}</li>
6865         * <li>{@link #TYPE_OTHER}</li>
6866         * <li>{@link #TYPE_BIRTHDAY}</li>
6867         * </ul>
6868         * </p>
6869         * </td>
6870         * </tr>
6871         * <tr>
6872         * <td>String</td>
6873         * <td>{@link #LABEL}</td>
6874         * <td>{@link #DATA3}</td>
6875         * <td></td>
6876         * </tr>
6877         * </table>
6878         */
6879        public static final class Event implements DataColumnsWithJoins, CommonColumns,
6880                ContactCounts {
6881            /**
6882             * This utility class cannot be instantiated
6883             */
6884            private Event() {}
6885
6886            /** MIME type used when storing this in data table. */
6887            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contact_event";
6888
6889            public static final int TYPE_ANNIVERSARY = 1;
6890            public static final int TYPE_OTHER = 2;
6891            public static final int TYPE_BIRTHDAY = 3;
6892
6893            /**
6894             * The event start date as the user entered it.
6895             * <P>Type: TEXT</P>
6896             */
6897            public static final String START_DATE = DATA;
6898
6899            /**
6900             * Return the string resource that best describes the given
6901             * {@link #TYPE}. Will always return a valid resource.
6902             */
6903            public static int getTypeResource(Integer type) {
6904                if (type == null) {
6905                    return com.android.internal.R.string.eventTypeOther;
6906                }
6907                switch (type) {
6908                    case TYPE_ANNIVERSARY:
6909                        return com.android.internal.R.string.eventTypeAnniversary;
6910                    case TYPE_BIRTHDAY: return com.android.internal.R.string.eventTypeBirthday;
6911                    case TYPE_OTHER: return com.android.internal.R.string.eventTypeOther;
6912                    default: return com.android.internal.R.string.eventTypeCustom;
6913                }
6914            }
6915
6916            /**
6917             * Return a {@link CharSequence} that best describes the given type,
6918             * possibly substituting the given {@link #LABEL} value
6919             * for {@link #TYPE_CUSTOM}.
6920             */
6921            public static final CharSequence getTypeLabel(Resources res, int type,
6922                    CharSequence label) {
6923                if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) {
6924                    return label;
6925                } else {
6926                    final int labelRes = getTypeResource(type);
6927                    return res.getText(labelRes);
6928                }
6929            }
6930        }
6931
6932        /**
6933         * <p>
6934         * A data kind representing a photo for the contact.
6935         * </p>
6936         * <p>
6937         * Some sync adapters will choose to download photos in a separate
6938         * pass. A common pattern is to use columns {@link ContactsContract.Data#SYNC1}
6939         * through {@link ContactsContract.Data#SYNC4} to store temporary
6940         * data, e.g. the image URL or ID, state of download, server-side version
6941         * of the image.  It is allowed for the {@link #PHOTO} to be null.
6942         * </p>
6943         * <p>
6944         * You can use all columns defined for {@link ContactsContract.Data} as
6945         * well as the following aliases.
6946         * </p>
6947         * <h2>Column aliases</h2>
6948         * <table class="jd-sumtable">
6949         * <tr>
6950         * <th>Type</th>
6951         * <th>Alias</th><th colspan='2'>Data column</th>
6952         * </tr>
6953         * <tr>
6954         * <td>NUMBER</td>
6955         * <td>{@link #PHOTO_FILE_ID}</td>
6956         * <td>{@link #DATA14}</td>
6957         * <td>ID of the hi-res photo file.</td>
6958         * </tr>
6959         * <tr>
6960         * <td>BLOB</td>
6961         * <td>{@link #PHOTO}</td>
6962         * <td>{@link #DATA15}</td>
6963         * <td>By convention, binary data is stored in DATA15.  The thumbnail of the
6964         * photo is stored in this column.</td>
6965         * </tr>
6966         * </table>
6967         */
6968        public static final class Photo implements DataColumnsWithJoins, ContactCounts {
6969            /**
6970             * This utility class cannot be instantiated
6971             */
6972            private Photo() {}
6973
6974            /** MIME type used when storing this in data table. */
6975            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/photo";
6976
6977            /**
6978             * Photo file ID for the display photo of the raw contact.
6979             * See {@link ContactsContract.DisplayPhoto}.
6980             * <p>
6981             * Type: NUMBER
6982             */
6983            public static final String PHOTO_FILE_ID = DATA14;
6984
6985            /**
6986             * Thumbnail photo of the raw contact. This is the raw bytes of an image
6987             * that could be inflated using {@link android.graphics.BitmapFactory}.
6988             * <p>
6989             * Type: BLOB
6990             */
6991            public static final String PHOTO = DATA15;
6992        }
6993
6994        /**
6995         * <p>
6996         * Notes about the contact.
6997         * </p>
6998         * <p>
6999         * You can use all columns defined for {@link ContactsContract.Data} as
7000         * well as the following aliases.
7001         * </p>
7002         * <h2>Column aliases</h2>
7003         * <table class="jd-sumtable">
7004         * <tr>
7005         * <th>Type</th>
7006         * <th>Alias</th><th colspan='2'>Data column</th>
7007         * </tr>
7008         * <tr>
7009         * <td>String</td>
7010         * <td>{@link #NOTE}</td>
7011         * <td>{@link #DATA1}</td>
7012         * <td></td>
7013         * </tr>
7014         * </table>
7015         */
7016        public static final class Note implements DataColumnsWithJoins, ContactCounts {
7017            /**
7018             * This utility class cannot be instantiated
7019             */
7020            private Note() {}
7021
7022            /** MIME type used when storing this in data table. */
7023            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/note";
7024
7025            /**
7026             * The note text.
7027             * <P>Type: TEXT</P>
7028             */
7029            public static final String NOTE = DATA1;
7030        }
7031
7032        /**
7033         * <p>
7034         * Group Membership.
7035         * </p>
7036         * <p>
7037         * You can use all columns defined for {@link ContactsContract.Data} as
7038         * well as the following aliases.
7039         * </p>
7040         * <h2>Column aliases</h2>
7041         * <table class="jd-sumtable">
7042         * <tr>
7043         * <th>Type</th>
7044         * <th>Alias</th><th colspan='2'>Data column</th>
7045         * </tr>
7046         * <tr>
7047         * <td>long</td>
7048         * <td>{@link #GROUP_ROW_ID}</td>
7049         * <td>{@link #DATA1}</td>
7050         * <td></td>
7051         * </tr>
7052         * <tr>
7053         * <td>String</td>
7054         * <td>{@link #GROUP_SOURCE_ID}</td>
7055         * <td>none</td>
7056         * <td>
7057         * <p>
7058         * The sourceid of the group that this group membership refers to.
7059         * Exactly one of this or {@link #GROUP_ROW_ID} must be set when
7060         * inserting a row.
7061         * </p>
7062         * <p>
7063         * If this field is specified, the provider will first try to
7064         * look up a group with this {@link Groups Groups.SOURCE_ID}.  If such a group
7065         * is found, it will use the corresponding row id.  If the group is not
7066         * found, it will create one.
7067         * </td>
7068         * </tr>
7069         * </table>
7070         */
7071        public static final class GroupMembership implements DataColumnsWithJoins, ContactCounts {
7072            /**
7073             * This utility class cannot be instantiated
7074             */
7075            private GroupMembership() {}
7076
7077            /** MIME type used when storing this in data table. */
7078            public static final String CONTENT_ITEM_TYPE =
7079                    "vnd.android.cursor.item/group_membership";
7080
7081            /**
7082             * The row id of the group that this group membership refers to. Exactly one of
7083             * this or {@link #GROUP_SOURCE_ID} must be set when inserting a row.
7084             * <P>Type: INTEGER</P>
7085             */
7086            public static final String GROUP_ROW_ID = DATA1;
7087
7088            /**
7089             * The sourceid of the group that this group membership refers to.  Exactly one of
7090             * this or {@link #GROUP_ROW_ID} must be set when inserting a row.
7091             * <P>Type: TEXT</P>
7092             */
7093            public static final String GROUP_SOURCE_ID = "group_sourceid";
7094        }
7095
7096        /**
7097         * <p>
7098         * A data kind representing a website related to the contact.
7099         * </p>
7100         * <p>
7101         * You can use all columns defined for {@link ContactsContract.Data} as
7102         * well as the following aliases.
7103         * </p>
7104         * <h2>Column aliases</h2>
7105         * <table class="jd-sumtable">
7106         * <tr>
7107         * <th>Type</th>
7108         * <th>Alias</th><th colspan='2'>Data column</th>
7109         * </tr>
7110         * <tr>
7111         * <td>String</td>
7112         * <td>{@link #URL}</td>
7113         * <td>{@link #DATA1}</td>
7114         * <td></td>
7115         * </tr>
7116         * <tr>
7117         * <td>int</td>
7118         * <td>{@link #TYPE}</td>
7119         * <td>{@link #DATA2}</td>
7120         * <td>Allowed values are:
7121         * <p>
7122         * <ul>
7123         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
7124         * <li>{@link #TYPE_HOMEPAGE}</li>
7125         * <li>{@link #TYPE_BLOG}</li>
7126         * <li>{@link #TYPE_PROFILE}</li>
7127         * <li>{@link #TYPE_HOME}</li>
7128         * <li>{@link #TYPE_WORK}</li>
7129         * <li>{@link #TYPE_FTP}</li>
7130         * <li>{@link #TYPE_OTHER}</li>
7131         * </ul>
7132         * </p>
7133         * </td>
7134         * </tr>
7135         * <tr>
7136         * <td>String</td>
7137         * <td>{@link #LABEL}</td>
7138         * <td>{@link #DATA3}</td>
7139         * <td></td>
7140         * </tr>
7141         * </table>
7142         */
7143        public static final class Website implements DataColumnsWithJoins, CommonColumns,
7144                ContactCounts {
7145            /**
7146             * This utility class cannot be instantiated
7147             */
7148            private Website() {}
7149
7150            /** MIME type used when storing this in data table. */
7151            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/website";
7152
7153            public static final int TYPE_HOMEPAGE = 1;
7154            public static final int TYPE_BLOG = 2;
7155            public static final int TYPE_PROFILE = 3;
7156            public static final int TYPE_HOME = 4;
7157            public static final int TYPE_WORK = 5;
7158            public static final int TYPE_FTP = 6;
7159            public static final int TYPE_OTHER = 7;
7160
7161            /**
7162             * The website URL string.
7163             * <P>Type: TEXT</P>
7164             */
7165            public static final String URL = DATA;
7166        }
7167
7168        /**
7169         * <p>
7170         * A data kind representing a SIP address for the contact.
7171         * </p>
7172         * <p>
7173         * You can use all columns defined for {@link ContactsContract.Data} as
7174         * well as the following aliases.
7175         * </p>
7176         * <h2>Column aliases</h2>
7177         * <table class="jd-sumtable">
7178         * <tr>
7179         * <th>Type</th>
7180         * <th>Alias</th><th colspan='2'>Data column</th>
7181         * </tr>
7182         * <tr>
7183         * <td>String</td>
7184         * <td>{@link #SIP_ADDRESS}</td>
7185         * <td>{@link #DATA1}</td>
7186         * <td></td>
7187         * </tr>
7188         * <tr>
7189         * <td>int</td>
7190         * <td>{@link #TYPE}</td>
7191         * <td>{@link #DATA2}</td>
7192         * <td>Allowed values are:
7193         * <p>
7194         * <ul>
7195         * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li>
7196         * <li>{@link #TYPE_HOME}</li>
7197         * <li>{@link #TYPE_WORK}</li>
7198         * <li>{@link #TYPE_OTHER}</li>
7199         * </ul>
7200         * </p>
7201         * </td>
7202         * </tr>
7203         * <tr>
7204         * <td>String</td>
7205         * <td>{@link #LABEL}</td>
7206         * <td>{@link #DATA3}</td>
7207         * <td></td>
7208         * </tr>
7209         * </table>
7210         */
7211        public static final class SipAddress implements DataColumnsWithJoins, CommonColumns,
7212                ContactCounts {
7213            /**
7214             * This utility class cannot be instantiated
7215             */
7216            private SipAddress() {}
7217
7218            /** MIME type used when storing this in data table. */
7219            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/sip_address";
7220
7221            public static final int TYPE_HOME = 1;
7222            public static final int TYPE_WORK = 2;
7223            public static final int TYPE_OTHER = 3;
7224
7225            /**
7226             * The SIP address.
7227             * <P>Type: TEXT</P>
7228             */
7229            public static final String SIP_ADDRESS = DATA1;
7230            // ...and TYPE and LABEL come from the CommonColumns interface.
7231
7232            /**
7233             * Return the string resource that best describes the given
7234             * {@link #TYPE}. Will always return a valid resource.
7235             */
7236            public static final int getTypeLabelResource(int type) {
7237                switch (type) {
7238                    case TYPE_HOME: return com.android.internal.R.string.sipAddressTypeHome;
7239                    case TYPE_WORK: return com.android.internal.R.string.sipAddressTypeWork;
7240                    case TYPE_OTHER: return com.android.internal.R.string.sipAddressTypeOther;
7241                    default: return com.android.internal.R.string.sipAddressTypeCustom;
7242                }
7243            }
7244
7245            /**
7246             * Return a {@link CharSequence} that best describes the given type,
7247             * possibly substituting the given {@link #LABEL} value
7248             * for {@link #TYPE_CUSTOM}.
7249             */
7250            public static final CharSequence getTypeLabel(Resources res, int type,
7251                    CharSequence label) {
7252                if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) {
7253                    return label;
7254                } else {
7255                    final int labelRes = getTypeLabelResource(type);
7256                    return res.getText(labelRes);
7257                }
7258            }
7259        }
7260
7261        /**
7262         * A data kind representing an Identity related to the contact.
7263         * <p>
7264         * This can be used as a signal by the aggregator to combine raw contacts into
7265         * contacts, e.g. if two contacts have Identity rows with
7266         * the same NAMESPACE and IDENTITY values the aggregator can know that they refer
7267         * to the same person.
7268         * </p>
7269         */
7270        public static final class Identity implements DataColumnsWithJoins, ContactCounts {
7271            /**
7272             * This utility class cannot be instantiated
7273             */
7274            private Identity() {}
7275
7276            /** MIME type used when storing this in data table. */
7277            public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/identity";
7278
7279            /**
7280             * The identity string.
7281             * <P>Type: TEXT</P>
7282             */
7283            public static final String IDENTITY = DataColumns.DATA1;
7284
7285            /**
7286             * The namespace of the identity string, e.g. "com.google"
7287             * <P>Type: TEXT</P>
7288             */
7289            public static final String NAMESPACE = DataColumns.DATA2;
7290        }
7291
7292        /**
7293         * <p>
7294         * Convenient functionalities for "callable" data. Note that, this is NOT a separate data
7295         * kind.
7296         * </p>
7297         * <p>
7298         * This URI allows the ContactsProvider to return a unified result for "callable" data
7299         * that users can use for calling purposes. {@link Phone} and {@link SipAddress} are the
7300         * current examples for "callable", but may be expanded to the other types.
7301         * </p>
7302         * <p>
7303         * Each returned row may have a different MIMETYPE and thus different interpretation for
7304         * each column. For example the meaning for {@link Phone}'s type is different than
7305         * {@link SipAddress}'s.
7306         * </p>
7307         */
7308        public static final class Callable implements DataColumnsWithJoins, CommonColumns,
7309                ContactCounts {
7310            /**
7311             * Similar to {@link Phone#CONTENT_URI}, but returns callable data instead of only
7312             * phone numbers.
7313             */
7314            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
7315                    "callables");
7316            /**
7317             * Similar to {@link Phone#CONTENT_FILTER_URI}, but allows users to filter callable
7318             * data.
7319             */
7320            public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI,
7321                    "filter");
7322        }
7323
7324        /**
7325         * A special class of data items, used to refer to types of data that can be used to attempt
7326         * to start communicating with a person ({@link Phone} and {@link Email}). Note that this
7327         * is NOT a separate data kind.
7328         *
7329         * This URI allows the ContactsProvider to return a unified result for data items that users
7330         * can use to initiate communications with another contact. {@link Phone} and {@link Email}
7331         * are the current data types in this category.
7332         */
7333        public static final class Contactables implements DataColumnsWithJoins, CommonColumns,
7334                ContactCounts {
7335            /**
7336             * The content:// style URI for these data items, which requests a directory of data
7337             * rows matching the selection criteria.
7338             */
7339            public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI,
7340                    "contactables");
7341
7342            /**
7343             * The content:// style URI for these data items, which allows for a query parameter to
7344             * be appended onto the end to filter for data items matching the query.
7345             */
7346            public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(
7347                    Contactables.CONTENT_URI, "filter");
7348
7349            /**
7350             * A boolean parameter for {@link Data#CONTENT_URI}.
7351             * This specifies whether or not the returned data items should be filtered to show
7352             * data items belonging to visible contacts only.
7353             */
7354            public static final String VISIBLE_CONTACTS_ONLY = "visible_contacts_only";
7355        }
7356    }
7357
7358    /**
7359     * @see Groups
7360     */
7361    protected interface GroupsColumns {
7362        /**
7363         * The data set within the account that this group belongs to.  This allows
7364         * multiple sync adapters for the same account type to distinguish between
7365         * each others' group data.
7366         *
7367         * This is empty by default, and is completely optional.  It only needs to
7368         * be populated if multiple sync adapters are entering distinct group data
7369         * for the same account type and account name.
7370         * <P>Type: TEXT</P>
7371         */
7372        public static final String DATA_SET = "data_set";
7373
7374        /**
7375         * A concatenation of the account type and data set (delimited by a forward
7376         * slash) - if the data set is empty, this will be the same as the account
7377         * type.  For applications that need to be aware of the data set, this can
7378         * be used instead of account type to distinguish sets of data.  This is
7379         * never intended to be used for specifying accounts.
7380         * @hide
7381         */
7382        public static final String ACCOUNT_TYPE_AND_DATA_SET = "account_type_and_data_set";
7383
7384        /**
7385         * The display title of this group.
7386         * <p>
7387         * Type: TEXT
7388         */
7389        public static final String TITLE = "title";
7390
7391        /**
7392         * The package name to use when creating {@link Resources} objects for
7393         * this group. This value is only designed for use when building user
7394         * interfaces, and should not be used to infer the owner.
7395         */
7396        public static final String RES_PACKAGE = "res_package";
7397
7398        /**
7399         * The display title of this group to load as a resource from
7400         * {@link #RES_PACKAGE}, which may be localized.
7401         * <P>Type: TEXT</P>
7402         */
7403        public static final String TITLE_RES = "title_res";
7404
7405        /**
7406         * Notes about the group.
7407         * <p>
7408         * Type: TEXT
7409         */
7410        public static final String NOTES = "notes";
7411
7412        /**
7413         * The ID of this group if it is a System Group, i.e. a group that has a special meaning
7414         * to the sync adapter, null otherwise.
7415         * <P>Type: TEXT</P>
7416         */
7417        public static final String SYSTEM_ID = "system_id";
7418
7419        /**
7420         * The total number of {@link Contacts} that have
7421         * {@link CommonDataKinds.GroupMembership} in this group. Read-only value that is only
7422         * present when querying {@link Groups#CONTENT_SUMMARY_URI}.
7423         * <p>
7424         * Type: INTEGER
7425         */
7426        public static final String SUMMARY_COUNT = "summ_count";
7427
7428        /**
7429         * A boolean query parameter that can be used with {@link Groups#CONTENT_SUMMARY_URI}.
7430         * It will additionally return {@link #SUMMARY_GROUP_COUNT_PER_ACCOUNT}.
7431         *
7432         * @hide
7433         */
7434        public static final String PARAM_RETURN_GROUP_COUNT_PER_ACCOUNT =
7435                "return_group_count_per_account";
7436
7437        /**
7438         * The total number of groups of the account that a group belongs to.
7439         * This column is available only when the parameter
7440         * {@link #PARAM_RETURN_GROUP_COUNT_PER_ACCOUNT} is specified in
7441         * {@link Groups#CONTENT_SUMMARY_URI}.
7442         *
7443         * For example, when the account "A" has two groups "group1" and "group2", and the account
7444         * "B" has a group "group3", the rows for "group1" and "group2" return "2" and the row for
7445         * "group3" returns "1" for this column.
7446         *
7447         * Note: This counts only non-favorites, non-auto-add, and not deleted groups.
7448         *
7449         * Type: INTEGER
7450         * @hide
7451         */
7452        public static final String SUMMARY_GROUP_COUNT_PER_ACCOUNT = "group_count_per_account";
7453
7454        /**
7455         * The total number of {@link Contacts} that have both
7456         * {@link CommonDataKinds.GroupMembership} in this group, and also have phone numbers.
7457         * Read-only value that is only present when querying
7458         * {@link Groups#CONTENT_SUMMARY_URI}.
7459         * <p>
7460         * Type: INTEGER
7461         */
7462        public static final String SUMMARY_WITH_PHONES = "summ_phones";
7463
7464        /**
7465         * Flag indicating if the contacts belonging to this group should be
7466         * visible in any user interface.
7467         * <p>
7468         * Type: INTEGER (boolean)
7469         */
7470        public static final String GROUP_VISIBLE = "group_visible";
7471
7472        /**
7473         * The "deleted" flag: "0" by default, "1" if the row has been marked
7474         * for deletion. When {@link android.content.ContentResolver#delete} is
7475         * called on a group, it is marked for deletion. The sync adaptor
7476         * deletes the group on the server and then calls ContactResolver.delete
7477         * once more, this time setting the the
7478         * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to
7479         * finalize the data removal.
7480         * <P>Type: INTEGER</P>
7481         */
7482        public static final String DELETED = "deleted";
7483
7484        /**
7485         * Whether this group should be synced if the SYNC_EVERYTHING settings
7486         * is false for this group's account.
7487         * <p>
7488         * Type: INTEGER (boolean)
7489         */
7490        public static final String SHOULD_SYNC = "should_sync";
7491
7492        /**
7493         * Any newly created contacts will automatically be added to groups that have this
7494         * flag set to true.
7495         * <p>
7496         * Type: INTEGER (boolean)
7497         */
7498        public static final String AUTO_ADD = "auto_add";
7499
7500        /**
7501         * When a contacts is marked as a favorites it will be automatically added
7502         * to the groups that have this flag set, and when it is removed from favorites
7503         * it will be removed from these groups.
7504         * <p>
7505         * Type: INTEGER (boolean)
7506         */
7507        public static final String FAVORITES = "favorites";
7508
7509        /**
7510         * The "read-only" flag: "0" by default, "1" if the row cannot be modified or
7511         * deleted except by a sync adapter.  See {@link ContactsContract#CALLER_IS_SYNCADAPTER}.
7512         * <P>Type: INTEGER</P>
7513         */
7514        public static final String GROUP_IS_READ_ONLY = "group_is_read_only";
7515    }
7516
7517    /**
7518     * Constants for the groups table. Only per-account groups are supported.
7519     * <h2>Columns</h2>
7520     * <table class="jd-sumtable">
7521     * <tr>
7522     * <th colspan='4'>Groups</th>
7523     * </tr>
7524     * <tr>
7525     * <td>long</td>
7526     * <td>{@link #_ID}</td>
7527     * <td>read-only</td>
7528     * <td>Row ID. Sync adapter should try to preserve row IDs during updates.
7529     * In other words, it would be a really bad idea to delete and reinsert a
7530     * group. A sync adapter should always do an update instead.</td>
7531     * </tr>
7532     # <tr>
7533     * <td>String</td>
7534     * <td>{@link #DATA_SET}</td>
7535     * <td>read/write-once</td>
7536     * <td>
7537     * <p>
7538     * The data set within the account that this group belongs to.  This allows
7539     * multiple sync adapters for the same account type to distinguish between
7540     * each others' group data.  The combination of {@link #ACCOUNT_TYPE},
7541     * {@link #ACCOUNT_NAME}, and {@link #DATA_SET} identifies a set of data
7542     * that is associated with a single sync adapter.
7543     * </p>
7544     * <p>
7545     * This is empty by default, and is completely optional.  It only needs to
7546     * be populated if multiple sync adapters are entering distinct data for
7547     * the same account type and account name.
7548     * </p>
7549     * <p>
7550     * It should be set at the time the group is inserted and never changed
7551     * afterwards.
7552     * </p>
7553     * </td>
7554     * </tr>
7555     * <tr>
7556     * <td>String</td>
7557     * <td>{@link #TITLE}</td>
7558     * <td>read/write</td>
7559     * <td>The display title of this group.</td>
7560     * </tr>
7561     * <tr>
7562     * <td>String</td>
7563     * <td>{@link #NOTES}</td>
7564     * <td>read/write</td>
7565     * <td>Notes about the group.</td>
7566     * </tr>
7567     * <tr>
7568     * <td>String</td>
7569     * <td>{@link #SYSTEM_ID}</td>
7570     * <td>read/write</td>
7571     * <td>The ID of this group if it is a System Group, i.e. a group that has a
7572     * special meaning to the sync adapter, null otherwise.</td>
7573     * </tr>
7574     * <tr>
7575     * <td>int</td>
7576     * <td>{@link #SUMMARY_COUNT}</td>
7577     * <td>read-only</td>
7578     * <td>The total number of {@link Contacts} that have
7579     * {@link CommonDataKinds.GroupMembership} in this group. Read-only value
7580     * that is only present when querying {@link Groups#CONTENT_SUMMARY_URI}.</td>
7581     * </tr>
7582     * <tr>
7583     * <td>int</td>
7584     * <td>{@link #SUMMARY_WITH_PHONES}</td>
7585     * <td>read-only</td>
7586     * <td>The total number of {@link Contacts} that have both
7587     * {@link CommonDataKinds.GroupMembership} in this group, and also have
7588     * phone numbers. Read-only value that is only present when querying
7589     * {@link Groups#CONTENT_SUMMARY_URI}.</td>
7590     * </tr>
7591     * <tr>
7592     * <td>int</td>
7593     * <td>{@link #GROUP_VISIBLE}</td>
7594     * <td>read-only</td>
7595     * <td>Flag indicating if the contacts belonging to this group should be
7596     * visible in any user interface. Allowed values: 0 and 1.</td>
7597     * </tr>
7598     * <tr>
7599     * <td>int</td>
7600     * <td>{@link #DELETED}</td>
7601     * <td>read/write</td>
7602     * <td>The "deleted" flag: "0" by default, "1" if the row has been marked
7603     * for deletion. When {@link android.content.ContentResolver#delete} is
7604     * called on a group, it is marked for deletion. The sync adaptor deletes
7605     * the group on the server and then calls ContactResolver.delete once more,
7606     * this time setting the the {@link ContactsContract#CALLER_IS_SYNCADAPTER}
7607     * query parameter to finalize the data removal.</td>
7608     * </tr>
7609     * <tr>
7610     * <td>int</td>
7611     * <td>{@link #SHOULD_SYNC}</td>
7612     * <td>read/write</td>
7613     * <td>Whether this group should be synced if the SYNC_EVERYTHING settings
7614     * is false for this group's account.</td>
7615     * </tr>
7616     * </table>
7617     */
7618    public static final class Groups implements BaseColumns, GroupsColumns, SyncColumns {
7619        /**
7620         * This utility class cannot be instantiated
7621         */
7622        private Groups() {
7623        }
7624
7625        /**
7626         * The content:// style URI for this table
7627         */
7628        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "groups");
7629
7630        /**
7631         * The content:// style URI for this table joined with details data from
7632         * {@link ContactsContract.Data}.
7633         */
7634        public static final Uri CONTENT_SUMMARY_URI = Uri.withAppendedPath(AUTHORITY_URI,
7635                "groups_summary");
7636
7637        /**
7638         * The MIME type of a directory of groups.
7639         */
7640        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/group";
7641
7642        /**
7643         * The MIME type of a single group.
7644         */
7645        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/group";
7646
7647        public static EntityIterator newEntityIterator(Cursor cursor) {
7648            return new EntityIteratorImpl(cursor);
7649        }
7650
7651        private static class EntityIteratorImpl extends CursorEntityIterator {
7652            public EntityIteratorImpl(Cursor cursor) {
7653                super(cursor);
7654            }
7655
7656            @Override
7657            public Entity getEntityAndIncrementCursor(Cursor cursor) throws RemoteException {
7658                // we expect the cursor is already at the row we need to read from
7659                final ContentValues values = new ContentValues();
7660                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, _ID);
7661                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, ACCOUNT_NAME);
7662                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, ACCOUNT_TYPE);
7663                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, DIRTY);
7664                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, VERSION);
7665                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SOURCE_ID);
7666                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, RES_PACKAGE);
7667                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, TITLE);
7668                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, TITLE_RES);
7669                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, GROUP_VISIBLE);
7670                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC1);
7671                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC2);
7672                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC3);
7673                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC4);
7674                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYSTEM_ID);
7675                DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, DELETED);
7676                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, NOTES);
7677                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SHOULD_SYNC);
7678                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, FAVORITES);
7679                DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, AUTO_ADD);
7680                cursor.moveToNext();
7681                return new Entity(values);
7682            }
7683        }
7684    }
7685
7686    /**
7687     * <p>
7688     * Constants for the contact aggregation exceptions table, which contains
7689     * aggregation rules overriding those used by automatic aggregation. This
7690     * type only supports query and update. Neither insert nor delete are
7691     * supported.
7692     * </p>
7693     * <h2>Columns</h2>
7694     * <table class="jd-sumtable">
7695     * <tr>
7696     * <th colspan='4'>AggregationExceptions</th>
7697     * </tr>
7698     * <tr>
7699     * <td>int</td>
7700     * <td>{@link #TYPE}</td>
7701     * <td>read/write</td>
7702     * <td>The type of exception: {@link #TYPE_KEEP_TOGETHER},
7703     * {@link #TYPE_KEEP_SEPARATE} or {@link #TYPE_AUTOMATIC}.</td>
7704     * </tr>
7705     * <tr>
7706     * <td>long</td>
7707     * <td>{@link #RAW_CONTACT_ID1}</td>
7708     * <td>read/write</td>
7709     * <td>A reference to the {@link RawContacts#_ID} of the raw contact that
7710     * the rule applies to.</td>
7711     * </tr>
7712     * <tr>
7713     * <td>long</td>
7714     * <td>{@link #RAW_CONTACT_ID2}</td>
7715     * <td>read/write</td>
7716     * <td>A reference to the other {@link RawContacts#_ID} of the raw contact
7717     * that the rule applies to.</td>
7718     * </tr>
7719     * </table>
7720     */
7721    public static final class AggregationExceptions implements BaseColumns {
7722        /**
7723         * This utility class cannot be instantiated
7724         */
7725        private AggregationExceptions() {}
7726
7727        /**
7728         * The content:// style URI for this table
7729         */
7730        public static final Uri CONTENT_URI =
7731                Uri.withAppendedPath(AUTHORITY_URI, "aggregation_exceptions");
7732
7733        /**
7734         * The MIME type of {@link #CONTENT_URI} providing a directory of data.
7735         */
7736        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/aggregation_exception";
7737
7738        /**
7739         * The MIME type of a {@link #CONTENT_URI} subdirectory of an aggregation exception
7740         */
7741        public static final String CONTENT_ITEM_TYPE =
7742                "vnd.android.cursor.item/aggregation_exception";
7743
7744        /**
7745         * The type of exception: {@link #TYPE_KEEP_TOGETHER}, {@link #TYPE_KEEP_SEPARATE} or
7746         * {@link #TYPE_AUTOMATIC}.
7747         *
7748         * <P>Type: INTEGER</P>
7749         */
7750        public static final String TYPE = "type";
7751
7752        /**
7753         * Allows the provider to automatically decide whether the specified raw contacts should
7754         * be included in the same aggregate contact or not.
7755         */
7756        public static final int TYPE_AUTOMATIC = 0;
7757
7758        /**
7759         * Makes sure that the specified raw contacts are included in the same
7760         * aggregate contact.
7761         */
7762        public static final int TYPE_KEEP_TOGETHER = 1;
7763
7764        /**
7765         * Makes sure that the specified raw contacts are NOT included in the same
7766         * aggregate contact.
7767         */
7768        public static final int TYPE_KEEP_SEPARATE = 2;
7769
7770        /**
7771         * A reference to the {@link RawContacts#_ID} of the raw contact that the rule applies to.
7772         */
7773        public static final String RAW_CONTACT_ID1 = "raw_contact_id1";
7774
7775        /**
7776         * A reference to the other {@link RawContacts#_ID} of the raw contact that the rule
7777         * applies to.
7778         */
7779        public static final String RAW_CONTACT_ID2 = "raw_contact_id2";
7780    }
7781
7782    /**
7783     * @see Settings
7784     */
7785    protected interface SettingsColumns {
7786        /**
7787         * The name of the account instance to which this row belongs.
7788         * <P>Type: TEXT</P>
7789         */
7790        public static final String ACCOUNT_NAME = "account_name";
7791
7792        /**
7793         * The type of account to which this row belongs, which when paired with
7794         * {@link #ACCOUNT_NAME} identifies a specific account.
7795         * <P>Type: TEXT</P>
7796         */
7797        public static final String ACCOUNT_TYPE = "account_type";
7798
7799        /**
7800         * The data set within the account that this row belongs to.  This allows
7801         * multiple sync adapters for the same account type to distinguish between
7802         * each others' data.
7803         *
7804         * This is empty by default, and is completely optional.  It only needs to
7805         * be populated if multiple sync adapters are entering distinct data for
7806         * the same account type and account name.
7807         * <P>Type: TEXT</P>
7808         */
7809        public static final String DATA_SET = "data_set";
7810
7811        /**
7812         * Depending on the mode defined by the sync-adapter, this flag controls
7813         * the top-level sync behavior for this data source.
7814         * <p>
7815         * Type: INTEGER (boolean)
7816         */
7817        public static final String SHOULD_SYNC = "should_sync";
7818
7819        /**
7820         * Flag indicating if contacts without any {@link CommonDataKinds.GroupMembership}
7821         * entries should be visible in any user interface.
7822         * <p>
7823         * Type: INTEGER (boolean)
7824         */
7825        public static final String UNGROUPED_VISIBLE = "ungrouped_visible";
7826
7827        /**
7828         * Read-only flag indicating if this {@link #SHOULD_SYNC} or any
7829         * {@link Groups#SHOULD_SYNC} under this account have been marked as
7830         * unsynced.
7831         */
7832        public static final String ANY_UNSYNCED = "any_unsynced";
7833
7834        /**
7835         * Read-only count of {@link Contacts} from a specific source that have
7836         * no {@link CommonDataKinds.GroupMembership} entries.
7837         * <p>
7838         * Type: INTEGER
7839         */
7840        public static final String UNGROUPED_COUNT = "summ_count";
7841
7842        /**
7843         * Read-only count of {@link Contacts} from a specific source that have
7844         * no {@link CommonDataKinds.GroupMembership} entries, and also have phone numbers.
7845         * <p>
7846         * Type: INTEGER
7847         */
7848        public static final String UNGROUPED_WITH_PHONES = "summ_phones";
7849    }
7850
7851    /**
7852     * <p>
7853     * Contacts-specific settings for various {@link Account}'s.
7854     * </p>
7855     * <h2>Columns</h2>
7856     * <table class="jd-sumtable">
7857     * <tr>
7858     * <th colspan='4'>Settings</th>
7859     * </tr>
7860     * <tr>
7861     * <td>String</td>
7862     * <td>{@link #ACCOUNT_NAME}</td>
7863     * <td>read/write-once</td>
7864     * <td>The name of the account instance to which this row belongs.</td>
7865     * </tr>
7866     * <tr>
7867     * <td>String</td>
7868     * <td>{@link #ACCOUNT_TYPE}</td>
7869     * <td>read/write-once</td>
7870     * <td>The type of account to which this row belongs, which when paired with
7871     * {@link #ACCOUNT_NAME} identifies a specific account.</td>
7872     * </tr>
7873     * <tr>
7874     * <td>int</td>
7875     * <td>{@link #SHOULD_SYNC}</td>
7876     * <td>read/write</td>
7877     * <td>Depending on the mode defined by the sync-adapter, this flag controls
7878     * the top-level sync behavior for this data source.</td>
7879     * </tr>
7880     * <tr>
7881     * <td>int</td>
7882     * <td>{@link #UNGROUPED_VISIBLE}</td>
7883     * <td>read/write</td>
7884     * <td>Flag indicating if contacts without any
7885     * {@link CommonDataKinds.GroupMembership} entries should be visible in any
7886     * user interface.</td>
7887     * </tr>
7888     * <tr>
7889     * <td>int</td>
7890     * <td>{@link #ANY_UNSYNCED}</td>
7891     * <td>read-only</td>
7892     * <td>Read-only flag indicating if this {@link #SHOULD_SYNC} or any
7893     * {@link Groups#SHOULD_SYNC} under this account have been marked as
7894     * unsynced.</td>
7895     * </tr>
7896     * <tr>
7897     * <td>int</td>
7898     * <td>{@link #UNGROUPED_COUNT}</td>
7899     * <td>read-only</td>
7900     * <td>Read-only count of {@link Contacts} from a specific source that have
7901     * no {@link CommonDataKinds.GroupMembership} entries.</td>
7902     * </tr>
7903     * <tr>
7904     * <td>int</td>
7905     * <td>{@link #UNGROUPED_WITH_PHONES}</td>
7906     * <td>read-only</td>
7907     * <td>Read-only count of {@link Contacts} from a specific source that have
7908     * no {@link CommonDataKinds.GroupMembership} entries, and also have phone
7909     * numbers.</td>
7910     * </tr>
7911     * </table>
7912     */
7913    public static final class Settings implements SettingsColumns {
7914        /**
7915         * This utility class cannot be instantiated
7916         */
7917        private Settings() {
7918        }
7919
7920        /**
7921         * The content:// style URI for this table
7922         */
7923        public static final Uri CONTENT_URI =
7924                Uri.withAppendedPath(AUTHORITY_URI, "settings");
7925
7926        /**
7927         * The MIME-type of {@link #CONTENT_URI} providing a directory of
7928         * settings.
7929         */
7930        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/setting";
7931
7932        /**
7933         * The MIME-type of {@link #CONTENT_URI} providing a single setting.
7934         */
7935        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/setting";
7936    }
7937
7938    /**
7939     * API for inquiring about the general status of the provider.
7940     *
7941     * @hide
7942     */
7943    public static final class ProviderStatus {
7944
7945        /**
7946         * Not instantiable.
7947         */
7948        private ProviderStatus() {
7949        }
7950
7951        /**
7952         * The content:// style URI for this table.  Requests to this URI can be
7953         * performed on the UI thread because they are always unblocking.
7954         */
7955        public static final Uri CONTENT_URI =
7956                Uri.withAppendedPath(AUTHORITY_URI, "provider_status");
7957
7958        /**
7959         * The MIME-type of {@link #CONTENT_URI} providing a directory of
7960         * settings.
7961         */
7962        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/provider_status";
7963
7964        /**
7965         * An integer representing the current status of the provider.
7966         */
7967        public static final String STATUS = "status";
7968
7969        /**
7970         * Default status of the provider.
7971         */
7972        public static final int STATUS_NORMAL = 0;
7973
7974        /**
7975         * The status used when the provider is in the process of upgrading.  Contacts
7976         * are temporarily unaccessible.
7977         */
7978        public static final int STATUS_UPGRADING = 1;
7979
7980        /**
7981         * The status used during a locale change.
7982         */
7983        public static final int STATUS_CHANGING_LOCALE = 3;
7984
7985        /**
7986         * The status that indicates that there are no accounts and no contacts
7987         * on the device.
7988         */
7989        public static final int STATUS_NO_ACCOUNTS_NO_CONTACTS = 4;
7990    }
7991
7992    /**
7993     * <p>
7994     * API allowing applications to send usage information for each {@link Data} row to the
7995     * Contacts Provider.  Applications can also clear all usage information.
7996     * </p>
7997     * <p>
7998     * With the feedback, Contacts Provider may return more contextually appropriate results for
7999     * Data listing, typically supplied with
8000     * {@link ContactsContract.Contacts#CONTENT_FILTER_URI},
8001     * {@link ContactsContract.CommonDataKinds.Email#CONTENT_FILTER_URI},
8002     * {@link ContactsContract.CommonDataKinds.Phone#CONTENT_FILTER_URI}, and users can benefit
8003     * from better ranked (sorted) lists in applications that show auto-complete list.
8004     * </p>
8005     * <p>
8006     * There is no guarantee for how this feedback is used, or even whether it is used at all.
8007     * The ranking algorithm will make best efforts to use the feedback data, but the exact
8008     * implementation, the storage data structures as well as the resulting sort order is device
8009     * and version specific and can change over time.
8010     * </p>
8011     * <p>
8012     * When updating usage information, users of this API need to use
8013     * {@link ContentResolver#update(Uri, ContentValues, String, String[])} with a Uri constructed
8014     * from {@link DataUsageFeedback#FEEDBACK_URI}. The Uri must contain one or more data id(s) as
8015     * its last path. They also need to append a query parameter to the Uri, to specify the type of
8016     * the communication, which enables the Contacts Provider to differentiate between kinds of
8017     * interactions using the same contact data field (for example a phone number can be used to
8018     * make phone calls or send SMS).
8019     * </p>
8020     * <p>
8021     * Selection and selectionArgs are ignored and must be set to null. To get data ids,
8022     * you may need to call {@link ContentResolver#query(Uri, String[], String, String[], String)}
8023     * toward {@link Data#CONTENT_URI}.
8024     * </p>
8025     * <p>
8026     * {@link ContentResolver#update(Uri, ContentValues, String, String[])} returns a positive
8027     * integer when successful, and returns 0 if no contact with that id was found.
8028     * </p>
8029     * <p>
8030     * Example:
8031     * <pre>
8032     * Uri uri = DataUsageFeedback.FEEDBACK_URI.buildUpon()
8033     *         .appendPath(TextUtils.join(",", dataIds))
8034     *         .appendQueryParameter(DataUsageFeedback.USAGE_TYPE,
8035     *                 DataUsageFeedback.USAGE_TYPE_CALL)
8036     *         .build();
8037     * boolean successful = resolver.update(uri, new ContentValues(), null, null) > 0;
8038     * </pre>
8039     * </p>
8040     * <p>
8041     * Applications can also clear all usage information with:
8042     * <pre>
8043     * boolean successful = resolver.delete(DataUsageFeedback.DELETE_USAGE_URI, null, null) > 0;
8044     * </pre>
8045     * </p>
8046     */
8047    public static final class DataUsageFeedback {
8048
8049        /**
8050         * The content:// style URI for sending usage feedback.
8051         * Must be used with {@link ContentResolver#update(Uri, ContentValues, String, String[])}.
8052         */
8053        public static final Uri FEEDBACK_URI =
8054                Uri.withAppendedPath(Data.CONTENT_URI, "usagefeedback");
8055
8056        /**
8057         * The content:// style URI for deleting all usage information.
8058         * Must be used with {@link ContentResolver#delete(Uri, String, String[])}.
8059         * The {@code where} and {@code selectionArgs} parameters are ignored.
8060         */
8061        public static final Uri DELETE_USAGE_URI =
8062                Uri.withAppendedPath(Contacts.CONTENT_URI, "delete_usage");
8063
8064        /**
8065         * <p>
8066         * Name for query parameter specifying the type of data usage.
8067         * </p>
8068         */
8069        public static final String USAGE_TYPE = "type";
8070
8071        /**
8072         * <p>
8073         * Type of usage for voice interaction, which includes phone call, voice chat, and
8074         * video chat.
8075         * </p>
8076         */
8077        public static final String USAGE_TYPE_CALL = "call";
8078
8079        /**
8080         * <p>
8081         * Type of usage for text interaction involving longer messages, which includes email.
8082         * </p>
8083         */
8084        public static final String USAGE_TYPE_LONG_TEXT = "long_text";
8085
8086        /**
8087         * <p>
8088         * Type of usage for text interaction involving shorter messages, which includes SMS,
8089         * text chat with email addresses.
8090         * </p>
8091         */
8092        public static final String USAGE_TYPE_SHORT_TEXT = "short_text";
8093    }
8094
8095    /**
8096     * <p>
8097     * Contact-specific information about whether or not a contact has been pinned by the user
8098     * at a particular position within the system contact application's user interface.
8099     * </p>
8100     *
8101     * <p>
8102     * This pinning information can be used by individual applications to customize how
8103     * they order particular pinned contacts. For example, a Dialer application could
8104     * use pinned information to order user-pinned contacts in a top row of favorites.
8105     * </p>
8106     *
8107     * <p>
8108     * It is possible for two or more contacts to occupy the same pinned position (due
8109     * to aggregation and sync), so this pinning information should be used on a best-effort
8110     * basis to order contacts in-application rather than an absolute guide on where a contact
8111     * should be positioned. Contacts returned by the ContactsProvider will not be ordered based
8112     * on this information, so it is up to the client application to reorder these contacts within
8113     * their own UI adhering to (or ignoring as appropriate) information stored in the pinned
8114     * column.
8115     * </p>
8116     *
8117     * <p>
8118     * By default, unpinned contacts will have a pinned position of
8119     * {@link PinnedPositions#UNPINNED}. Client-provided pinned positions can be positive
8120     * integers that are greater than 1.
8121     * </p>
8122     */
8123    public static final class PinnedPositions {
8124        /**
8125         * The method to invoke in order to undemote a formerly demoted contact. The contact id of
8126         * the contact must be provided as an argument. If the contact was not previously demoted,
8127         * nothing will be done.
8128         * @hide
8129         */
8130        public static final String UNDEMOTE_METHOD = "undemote";
8131
8132        /**
8133         * Undemotes a formerly demoted contact. If the contact was not previously demoted, nothing
8134         * will be done.
8135         *
8136         * @param contentResolver to perform the undemote operation on.
8137         * @param contactId the id of the contact to undemote.
8138         */
8139        public static void undemote(ContentResolver contentResolver, long contactId) {
8140            contentResolver.call(ContactsContract.AUTHORITY_URI, PinnedPositions.UNDEMOTE_METHOD,
8141                    String.valueOf(contactId), null);
8142        }
8143
8144        /**
8145         * Pins a contact at a provided position, or unpins a contact.
8146         *
8147         * @param contentResolver to perform the pinning operation on.
8148         * @param pinnedPosition the position to pin the contact at. To unpin a contact, use
8149         *         {@link PinnedPositions#UNPINNED}.
8150         */
8151        public static void pin(
8152                ContentResolver contentResolver, long contactId, int pinnedPosition) {
8153            final Uri uri = Uri.withAppendedPath(Contacts.CONTENT_URI, String.valueOf(contactId));
8154            final ContentValues values = new ContentValues();
8155            values.put(Contacts.PINNED, pinnedPosition);
8156            contentResolver.update(uri, values, null, null);
8157        }
8158
8159        /**
8160         * Default value for the pinned position of an unpinned contact.
8161         */
8162        public static final int UNPINNED = 0;
8163
8164        /**
8165         * Value of pinned position for a contact that a user has indicated should be considered
8166         * of the lowest priority. It is up to the client application to determine how to present
8167         * such a contact - for example all the way at the bottom of a contact list, or simply
8168         * just hidden from view.
8169         */
8170        public static final int DEMOTED = -1;
8171    }
8172
8173    /**
8174     * Helper methods to display QuickContact dialogs that display all the information belonging to
8175     * a specific {@link Contacts} entry.
8176     */
8177    public static final class QuickContact {
8178        /**
8179         * Action used to launch the system contacts application and bring up a QuickContact dialog
8180         * for the provided {@link Contacts} entry.
8181         */
8182        public static final String ACTION_QUICK_CONTACT =
8183                "android.provider.action.QUICK_CONTACT";
8184
8185        /**
8186         * Extra used to specify pivot dialog location in screen coordinates.
8187         * @deprecated Use {@link Intent#setSourceBounds(Rect)} instead.
8188         * @hide
8189         */
8190        @Deprecated
8191        public static final String EXTRA_TARGET_RECT = "android.provider.extra.TARGET_RECT";
8192
8193        /**
8194         * Extra used to specify size of QuickContacts. Not all implementations of QuickContacts
8195         * will respect this extra's value.
8196         *
8197         * One of {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or {@link #MODE_LARGE}.
8198         */
8199        public static final String EXTRA_MODE = "android.provider.extra.MODE";
8200
8201        /**
8202         * Extra used to specify which mimetype should be prioritized in the QuickContacts UI.
8203         * For example, passing the value {@link CommonDataKinds.Phone#CONTENT_ITEM_TYPE} can
8204         * cause phone numbers to be displayed more prominently in QuickContacts.
8205         */
8206        public static final String EXTRA_PRIORITIZED_MIMETYPE
8207                = "android.provider.extra.PRIORITIZED_MIMETYPE";
8208
8209        /**
8210         * Extra used to indicate a list of specific MIME-types to exclude and not display in the
8211         * QuickContacts dialog. Stored as a {@link String} array.
8212         */
8213        public static final String EXTRA_EXCLUDE_MIMES = "android.provider.extra.EXCLUDE_MIMES";
8214
8215        /**
8216         * Small QuickContact mode, usually presented with minimal actions.
8217         */
8218        public static final int MODE_SMALL = 1;
8219
8220        /**
8221         * Medium QuickContact mode, includes actions and light summary describing
8222         * the {@link Contacts} entry being shown. This may include social
8223         * status and presence details.
8224         */
8225        public static final int MODE_MEDIUM = 2;
8226
8227        /**
8228         * Large QuickContact mode, includes actions and larger, card-like summary
8229         * of the {@link Contacts} entry being shown. This may include detailed
8230         * information, such as a photo.
8231         */
8232        public static final int MODE_LARGE = 3;
8233
8234        /** @hide */
8235        public static final int MODE_DEFAULT = MODE_LARGE;
8236
8237        /**
8238         * Constructs the QuickContacts intent with a view's rect.
8239         * @hide
8240         */
8241        public static Intent composeQuickContactsIntent(Context context, View target, Uri lookupUri,
8242                int mode, String[] excludeMimes) {
8243            // Find location and bounds of target view, adjusting based on the
8244            // assumed local density.
8245            final float appScale = context.getResources().getCompatibilityInfo().applicationScale;
8246            final int[] pos = new int[2];
8247            target.getLocationOnScreen(pos);
8248
8249            final Rect rect = new Rect();
8250            rect.left = (int) (pos[0] * appScale + 0.5f);
8251            rect.top = (int) (pos[1] * appScale + 0.5f);
8252            rect.right = (int) ((pos[0] + target.getWidth()) * appScale + 0.5f);
8253            rect.bottom = (int) ((pos[1] + target.getHeight()) * appScale + 0.5f);
8254
8255            return composeQuickContactsIntent(context, rect, lookupUri, mode, excludeMimes);
8256        }
8257
8258        /**
8259         * Constructs the QuickContacts intent.
8260         * @hide
8261         */
8262        public static Intent composeQuickContactsIntent(Context context, Rect target,
8263                Uri lookupUri, int mode, String[] excludeMimes) {
8264            // When launching from an Activiy, we don't want to start a new task, but otherwise
8265            // we *must* start a new task.  (Otherwise startActivity() would crash.)
8266            Context actualContext = context;
8267            while ((actualContext instanceof ContextWrapper)
8268                    && !(actualContext instanceof Activity)) {
8269                actualContext = ((ContextWrapper) actualContext).getBaseContext();
8270            }
8271            final int intentFlags = ((actualContext instanceof Activity)
8272                    ? 0 : Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK)
8273                    // Workaround for b/16898764. Declaring singleTop in manifest doesn't work.
8274                    | Intent.FLAG_ACTIVITY_SINGLE_TOP;
8275
8276            // Launch pivot dialog through intent for now
8277            final Intent intent = new Intent(ACTION_QUICK_CONTACT).addFlags(intentFlags);
8278
8279            // NOTE: This logic and rebuildManagedQuickContactsIntent() must be in sync.
8280            intent.setData(lookupUri);
8281            intent.setSourceBounds(target);
8282            intent.putExtra(EXTRA_MODE, mode);
8283            intent.putExtra(EXTRA_EXCLUDE_MIMES, excludeMimes);
8284            return intent;
8285        }
8286
8287        /**
8288         * Constructs a QuickContacts intent based on an incoming intent for DevicePolicyManager
8289         * to strip off anything not necessary.
8290         *
8291         * @hide
8292         */
8293        public static Intent rebuildManagedQuickContactsIntent(String lookupKey, long contactId,
8294                Intent originalIntent) {
8295            final Intent intent = new Intent(ACTION_QUICK_CONTACT);
8296            // Rebuild the URI from a lookup key and a contact ID.
8297            intent.setData(Contacts.getLookupUri(contactId, lookupKey));
8298
8299            // Copy flags and always set NEW_TASK because it won't have a parent activity.
8300            intent.setFlags(originalIntent.getFlags() | Intent.FLAG_ACTIVITY_NEW_TASK);
8301
8302            // Copy extras.
8303            intent.setSourceBounds(originalIntent.getSourceBounds());
8304            intent.putExtra(EXTRA_MODE, originalIntent.getIntExtra(EXTRA_MODE, MODE_DEFAULT));
8305            intent.putExtra(EXTRA_EXCLUDE_MIMES,
8306                    originalIntent.getStringArrayExtra(EXTRA_EXCLUDE_MIMES));
8307            return intent;
8308        }
8309
8310
8311        /**
8312         * Trigger a dialog that lists the various methods of interacting with
8313         * the requested {@link Contacts} entry. This may be based on available
8314         * {@link ContactsContract.Data} rows under that contact, and may also
8315         * include social status and presence details.
8316         *
8317         * @param context The parent {@link Context} that may be used as the
8318         *            parent for this dialog.
8319         * @param target Specific {@link View} from your layout that this dialog
8320         *            should be centered around. In particular, if the dialog
8321         *            has a "callout" arrow, it will be pointed and centered
8322         *            around this {@link View}.
8323         * @param lookupUri A {@link ContactsContract.Contacts#CONTENT_LOOKUP_URI} style
8324         *            {@link Uri} that describes a specific contact to feature
8325         *            in this dialog.
8326         * @param mode Any of {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or
8327         *            {@link #MODE_LARGE}, indicating the desired dialog size,
8328         *            when supported.
8329         * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types
8330         *            to exclude when showing this dialog. For example, when
8331         *            already viewing the contact details card, this can be used
8332         *            to omit the details entry from the dialog.
8333         */
8334        public static void showQuickContact(Context context, View target, Uri lookupUri, int mode,
8335                String[] excludeMimes) {
8336            // Trigger with obtained rectangle
8337            Intent intent = composeQuickContactsIntent(context, target, lookupUri, mode,
8338                    excludeMimes);
8339            ContactsInternal.startQuickContactWithErrorToast(context, intent);
8340        }
8341
8342        /**
8343         * Trigger a dialog that lists the various methods of interacting with
8344         * the requested {@link Contacts} entry. This may be based on available
8345         * {@link ContactsContract.Data} rows under that contact, and may also
8346         * include social status and presence details.
8347         *
8348         * @param context The parent {@link Context} that may be used as the
8349         *            parent for this dialog.
8350         * @param target Specific {@link Rect} that this dialog should be
8351         *            centered around, in screen coordinates. In particular, if
8352         *            the dialog has a "callout" arrow, it will be pointed and
8353         *            centered around this {@link Rect}. If you are running at a
8354         *            non-native density, you need to manually adjust using
8355         *            {@link DisplayMetrics#density} before calling.
8356         * @param lookupUri A
8357         *            {@link ContactsContract.Contacts#CONTENT_LOOKUP_URI} style
8358         *            {@link Uri} that describes a specific contact to feature
8359         *            in this dialog.
8360         * @param mode Any of {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or
8361         *            {@link #MODE_LARGE}, indicating the desired dialog size,
8362         *            when supported.
8363         * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types
8364         *            to exclude when showing this dialog. For example, when
8365         *            already viewing the contact details card, this can be used
8366         *            to omit the details entry from the dialog.
8367         */
8368        public static void showQuickContact(Context context, Rect target, Uri lookupUri, int mode,
8369                String[] excludeMimes) {
8370            Intent intent = composeQuickContactsIntent(context, target, lookupUri, mode,
8371                    excludeMimes);
8372            ContactsInternal.startQuickContactWithErrorToast(context, intent);
8373        }
8374
8375        /**
8376         * Trigger a dialog that lists the various methods of interacting with
8377         * the requested {@link Contacts} entry. This may be based on available
8378         * {@link ContactsContract.Data} rows under that contact, and may also
8379         * include social status and presence details.
8380         *
8381         * @param context The parent {@link Context} that may be used as the
8382         *            parent for this dialog.
8383         * @param target Specific {@link View} from your layout that this dialog
8384         *            should be centered around. In particular, if the dialog
8385         *            has a "callout" arrow, it will be pointed and centered
8386         *            around this {@link View}.
8387         * @param lookupUri A
8388         *            {@link ContactsContract.Contacts#CONTENT_LOOKUP_URI} style
8389         *            {@link Uri} that describes a specific contact to feature
8390         *            in this dialog.
8391         * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types
8392         *            to exclude when showing this dialog. For example, when
8393         *            already viewing the contact details card, this can be used
8394         *            to omit the details entry from the dialog.
8395         * @param prioritizedMimeType This mimetype should be prioritized in the QuickContacts UI.
8396         *             For example, passing the value
8397         *             {@link CommonDataKinds.Phone#CONTENT_ITEM_TYPE} can cause phone numbers to be
8398         *             displayed more prominently in QuickContacts.
8399         */
8400        public static void showQuickContact(Context context, View target, Uri lookupUri,
8401                String[] excludeMimes, String prioritizedMimeType) {
8402            // Use MODE_LARGE instead of accepting mode as a parameter. The different mode
8403            // values defined in ContactsContract only affect very old implementations
8404            // of QuickContacts.
8405            Intent intent = composeQuickContactsIntent(context, target, lookupUri, MODE_DEFAULT,
8406                    excludeMimes);
8407            intent.putExtra(EXTRA_PRIORITIZED_MIMETYPE, prioritizedMimeType);
8408            ContactsInternal.startQuickContactWithErrorToast(context, intent);
8409        }
8410
8411        /**
8412         * Trigger a dialog that lists the various methods of interacting with
8413         * the requested {@link Contacts} entry. This may be based on available
8414         * {@link ContactsContract.Data} rows under that contact, and may also
8415         * include social status and presence details.
8416         *
8417         * @param context The parent {@link Context} that may be used as the
8418         *            parent for this dialog.
8419         * @param target Specific {@link Rect} that this dialog should be
8420         *            centered around, in screen coordinates. In particular, if
8421         *            the dialog has a "callout" arrow, it will be pointed and
8422         *            centered around this {@link Rect}. If you are running at a
8423         *            non-native density, you need to manually adjust using
8424         *            {@link DisplayMetrics#density} before calling.
8425         * @param lookupUri A
8426         *            {@link ContactsContract.Contacts#CONTENT_LOOKUP_URI} style
8427         *            {@link Uri} that describes a specific contact to feature
8428         *            in this dialog.
8429         * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types
8430         *            to exclude when showing this dialog. For example, when
8431         *            already viewing the contact details card, this can be used
8432         *            to omit the details entry from the dialog.
8433         * @param prioritizedMimeType This mimetype should be prioritized in the QuickContacts UI.
8434         *             For example, passing the value
8435         *             {@link CommonDataKinds.Phone#CONTENT_ITEM_TYPE} can cause phone numbers to be
8436         *             displayed more prominently in QuickContacts.
8437         */
8438        public static void showQuickContact(Context context, Rect target, Uri lookupUri,
8439                String[] excludeMimes, String prioritizedMimeType) {
8440            // Use MODE_LARGE instead of accepting mode as a parameter. The different mode
8441            // values defined in ContactsContract only affect very old implementations
8442            // of QuickContacts.
8443            Intent intent = composeQuickContactsIntent(context, target, lookupUri, MODE_DEFAULT,
8444                    excludeMimes);
8445            intent.putExtra(EXTRA_PRIORITIZED_MIMETYPE, prioritizedMimeType);
8446            ContactsInternal.startQuickContactWithErrorToast(context, intent);
8447        }
8448    }
8449
8450    /**
8451     * Helper class for accessing full-size photos by photo file ID.
8452     * <p>
8453     * Usage example:
8454     * <dl>
8455     * <dt>Retrieving a full-size photo by photo file ID (see
8456     * {@link ContactsContract.ContactsColumns#PHOTO_FILE_ID})
8457     * </dt>
8458     * <dd>
8459     * <pre>
8460     * public InputStream openDisplayPhoto(long photoFileId) {
8461     *     Uri displayPhotoUri = ContentUris.withAppendedId(DisplayPhoto.CONTENT_URI, photoKey);
8462     *     try {
8463     *         AssetFileDescriptor fd = getContentResolver().openAssetFileDescriptor(
8464     *             displayPhotoUri, "r");
8465     *         return fd.createInputStream();
8466     *     } catch (IOException e) {
8467     *         return null;
8468     *     }
8469     * }
8470     * </pre>
8471     * </dd>
8472     * </dl>
8473     * </p>
8474     */
8475    public static final class DisplayPhoto {
8476        /**
8477         * no public constructor since this is a utility class
8478         */
8479        private DisplayPhoto() {}
8480
8481        /**
8482         * The content:// style URI for this class, which allows access to full-size photos,
8483         * given a key.
8484         */
8485        public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "display_photo");
8486
8487        /**
8488         * This URI allows the caller to query for the maximum dimensions of a display photo
8489         * or thumbnail.  Requests to this URI can be performed on the UI thread because
8490         * they are always unblocking.
8491         */
8492        public static final Uri CONTENT_MAX_DIMENSIONS_URI =
8493                Uri.withAppendedPath(AUTHORITY_URI, "photo_dimensions");
8494
8495        /**
8496         * Queries to {@link ContactsContract.DisplayPhoto#CONTENT_MAX_DIMENSIONS_URI} will
8497         * contain this column, populated with the maximum height and width (in pixels)
8498         * that will be stored for a display photo.  Larger photos will be down-sized to
8499         * fit within a square of this many pixels.
8500         */
8501        public static final String DISPLAY_MAX_DIM = "display_max_dim";
8502
8503        /**
8504         * Queries to {@link ContactsContract.DisplayPhoto#CONTENT_MAX_DIMENSIONS_URI} will
8505         * contain this column, populated with the height and width (in pixels) for photo
8506         * thumbnails.
8507         */
8508        public static final String THUMBNAIL_MAX_DIM = "thumbnail_max_dim";
8509    }
8510
8511    /**
8512     * Contains helper classes used to create or manage {@link android.content.Intent Intents}
8513     * that involve contacts.
8514     */
8515    public static final class Intents {
8516        /**
8517         * This is the intent that is fired when a search suggestion is clicked on.
8518         */
8519        public static final String SEARCH_SUGGESTION_CLICKED =
8520                "android.provider.Contacts.SEARCH_SUGGESTION_CLICKED";
8521
8522        /**
8523         * This is the intent that is fired when a search suggestion for dialing a number
8524         * is clicked on.
8525         */
8526        public static final String SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED =
8527                "android.provider.Contacts.SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED";
8528
8529        /**
8530         * This is the intent that is fired when a search suggestion for creating a contact
8531         * is clicked on.
8532         */
8533        public static final String SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED =
8534                "android.provider.Contacts.SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED";
8535
8536        /**
8537         * This is the intent that is fired when the contacts database is created. <p> The
8538         * READ_CONTACT permission is required to receive these broadcasts.
8539         */
8540        public static final String CONTACTS_DATABASE_CREATED =
8541                "android.provider.Contacts.DATABASE_CREATED";
8542
8543        /**
8544         * Starts an Activity that lets the user pick a contact to attach an image to.
8545         * After picking the contact it launches the image cropper in face detection mode.
8546         */
8547        public static final String ATTACH_IMAGE =
8548                "com.android.contacts.action.ATTACH_IMAGE";
8549
8550        /**
8551         * This is the intent that is fired when the user clicks the "invite to the network" button
8552         * on a contact.  Only sent to an activity which is explicitly registered by a contact
8553         * provider which supports the "invite to the network" feature.
8554         * <p>
8555         * {@link Intent#getData()} contains the lookup URI for the contact.
8556         */
8557        public static final String INVITE_CONTACT =
8558                "com.android.contacts.action.INVITE_CONTACT";
8559
8560        /**
8561         * Takes as input a data URI with a mailto: or tel: scheme. If a single
8562         * contact exists with the given data it will be shown. If no contact
8563         * exists, a dialog will ask the user if they want to create a new
8564         * contact with the provided details filled in. If multiple contacts
8565         * share the data the user will be prompted to pick which contact they
8566         * want to view.
8567         * <p>
8568         * For <code>mailto:</code> URIs, the scheme specific portion must be a
8569         * raw email address, such as one built using
8570         * {@link Uri#fromParts(String, String, String)}.
8571         * <p>
8572         * For <code>tel:</code> URIs, the scheme specific portion is compared
8573         * to existing numbers using the standard caller ID lookup algorithm.
8574         * The number must be properly encoded, for example using
8575         * {@link Uri#fromParts(String, String, String)}.
8576         * <p>
8577         * Any extras from the {@link Insert} class will be passed along to the
8578         * create activity if there are no contacts to show.
8579         * <p>
8580         * Passing true for the {@link #EXTRA_FORCE_CREATE} extra will skip
8581         * prompting the user when the contact doesn't exist.
8582         */
8583        public static final String SHOW_OR_CREATE_CONTACT =
8584                "com.android.contacts.action.SHOW_OR_CREATE_CONTACT";
8585
8586        /**
8587         * Starts an Activity that lets the user select the multiple phones from a
8588         * list of phone numbers which come from the contacts or
8589         * {@link #EXTRA_PHONE_URIS}.
8590         * <p>
8591         * The phone numbers being passed in through {@link #EXTRA_PHONE_URIS}
8592         * could belong to the contacts or not, and will be selected by default.
8593         * <p>
8594         * The user's selection will be returned from
8595         * {@link android.app.Activity#onActivityResult(int, int, android.content.Intent)}
8596         * if the resultCode is
8597         * {@link android.app.Activity#RESULT_OK}, the array of picked phone
8598         * numbers are in the Intent's
8599         * {@link #EXTRA_PHONE_URIS}; otherwise, the
8600         * {@link android.app.Activity#RESULT_CANCELED} is returned if the user
8601         * left the Activity without changing the selection.
8602         *
8603         * @hide
8604         */
8605        public static final String ACTION_GET_MULTIPLE_PHONES =
8606                "com.android.contacts.action.GET_MULTIPLE_PHONES";
8607
8608        /**
8609         * A broadcast action which is sent when any change has been made to the profile, such
8610         * as the profile name or the picture.  A receiver must have
8611         * the android.permission.READ_PROFILE permission.
8612         *
8613         * @hide
8614         */
8615        public static final String ACTION_PROFILE_CHANGED =
8616                "android.provider.Contacts.PROFILE_CHANGED";
8617
8618        /**
8619         * Used with {@link #SHOW_OR_CREATE_CONTACT} to force creating a new
8620         * contact if no matching contact found. Otherwise, default behavior is
8621         * to prompt user with dialog before creating.
8622         * <p>
8623         * Type: BOOLEAN
8624         */
8625        public static final String EXTRA_FORCE_CREATE =
8626                "com.android.contacts.action.FORCE_CREATE";
8627
8628        /**
8629         * Used with {@link #SHOW_OR_CREATE_CONTACT} to specify an exact
8630         * description to be shown when prompting user about creating a new
8631         * contact.
8632         * <p>
8633         * Type: STRING
8634         */
8635        public static final String EXTRA_CREATE_DESCRIPTION =
8636            "com.android.contacts.action.CREATE_DESCRIPTION";
8637
8638        /**
8639         * Used with {@link #ACTION_GET_MULTIPLE_PHONES} as the input or output value.
8640         * <p>
8641         * The phone numbers want to be picked by default should be passed in as
8642         * input value. These phone numbers could belong to the contacts or not.
8643         * <p>
8644         * The phone numbers which were picked by the user are returned as output
8645         * value.
8646         * <p>
8647         * Type: array of URIs, the tel URI is used for the phone numbers which don't
8648         * belong to any contact, the content URI is used for phone id in contacts.
8649         *
8650         * @hide
8651         */
8652        public static final String EXTRA_PHONE_URIS =
8653            "com.android.contacts.extra.PHONE_URIS";
8654
8655        /**
8656         * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to specify a
8657         * dialog location using screen coordinates. When not specified, the
8658         * dialog will be centered.
8659         *
8660         * @hide
8661         */
8662        @Deprecated
8663        public static final String EXTRA_TARGET_RECT = "target_rect";
8664
8665        /**
8666         * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to specify a
8667         * desired dialog style, usually a variation on size. One of
8668         * {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or {@link #MODE_LARGE}.
8669         *
8670         * @hide
8671         */
8672        @Deprecated
8673        public static final String EXTRA_MODE = "mode";
8674
8675        /**
8676         * Value for {@link #EXTRA_MODE} to show a small-sized dialog.
8677         *
8678         * @hide
8679         */
8680        @Deprecated
8681        public static final int MODE_SMALL = 1;
8682
8683        /**
8684         * Value for {@link #EXTRA_MODE} to show a medium-sized dialog.
8685         *
8686         * @hide
8687         */
8688        @Deprecated
8689        public static final int MODE_MEDIUM = 2;
8690
8691        /**
8692         * Value for {@link #EXTRA_MODE} to show a large-sized dialog.
8693         *
8694         * @hide
8695         */
8696        @Deprecated
8697        public static final int MODE_LARGE = 3;
8698
8699        /**
8700         * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to indicate
8701         * a list of specific MIME-types to exclude and not display. Stored as a
8702         * {@link String} array.
8703         *
8704         * @hide
8705         */
8706        @Deprecated
8707        public static final String EXTRA_EXCLUDE_MIMES = "exclude_mimes";
8708
8709        /**
8710         * Convenience class that contains string constants used
8711         * to create contact {@link android.content.Intent Intents}.
8712         */
8713        public static final class Insert {
8714            /** The action code to use when adding a contact */
8715            public static final String ACTION = Intent.ACTION_INSERT;
8716
8717            /**
8718             * If present, forces a bypass of quick insert mode.
8719             */
8720            public static final String FULL_MODE = "full_mode";
8721
8722            /**
8723             * The extra field for the contact name.
8724             * <P>Type: String</P>
8725             */
8726            public static final String NAME = "name";
8727
8728            // TODO add structured name values here.
8729
8730            /**
8731             * The extra field for the contact phonetic name.
8732             * <P>Type: String</P>
8733             */
8734            public static final String PHONETIC_NAME = "phonetic_name";
8735
8736            /**
8737             * The extra field for the contact company.
8738             * <P>Type: String</P>
8739             */
8740            public static final String COMPANY = "company";
8741
8742            /**
8743             * The extra field for the contact job title.
8744             * <P>Type: String</P>
8745             */
8746            public static final String JOB_TITLE = "job_title";
8747
8748            /**
8749             * The extra field for the contact notes.
8750             * <P>Type: String</P>
8751             */
8752            public static final String NOTES = "notes";
8753
8754            /**
8755             * The extra field for the contact phone number.
8756             * <P>Type: String</P>
8757             */
8758            public static final String PHONE = "phone";
8759
8760            /**
8761             * The extra field for the contact phone number type.
8762             * <P>Type: Either an integer value from
8763             * {@link CommonDataKinds.Phone},
8764             *  or a string specifying a custom label.</P>
8765             */
8766            public static final String PHONE_TYPE = "phone_type";
8767
8768            /**
8769             * The extra field for the phone isprimary flag.
8770             * <P>Type: boolean</P>
8771             */
8772            public static final String PHONE_ISPRIMARY = "phone_isprimary";
8773
8774            /**
8775             * The extra field for an optional second contact phone number.
8776             * <P>Type: String</P>
8777             */
8778            public static final String SECONDARY_PHONE = "secondary_phone";
8779
8780            /**
8781             * The extra field for an optional second contact phone number type.
8782             * <P>Type: Either an integer value from
8783             * {@link CommonDataKinds.Phone},
8784             *  or a string specifying a custom label.</P>
8785             */
8786            public static final String SECONDARY_PHONE_TYPE = "secondary_phone_type";
8787
8788            /**
8789             * The extra field for an optional third contact phone number.
8790             * <P>Type: String</P>
8791             */
8792            public static final String TERTIARY_PHONE = "tertiary_phone";
8793
8794            /**
8795             * The extra field for an optional third contact phone number type.
8796             * <P>Type: Either an integer value from
8797             * {@link CommonDataKinds.Phone},
8798             *  or a string specifying a custom label.</P>
8799             */
8800            public static final String TERTIARY_PHONE_TYPE = "tertiary_phone_type";
8801
8802            /**
8803             * The extra field for the contact email address.
8804             * <P>Type: String</P>
8805             */
8806            public static final String EMAIL = "email";
8807
8808            /**
8809             * The extra field for the contact email type.
8810             * <P>Type: Either an integer value from
8811             * {@link CommonDataKinds.Email}
8812             *  or a string specifying a custom label.</P>
8813             */
8814            public static final String EMAIL_TYPE = "email_type";
8815
8816            /**
8817             * The extra field for the email isprimary flag.
8818             * <P>Type: boolean</P>
8819             */
8820            public static final String EMAIL_ISPRIMARY = "email_isprimary";
8821
8822            /**
8823             * The extra field for an optional second contact email address.
8824             * <P>Type: String</P>
8825             */
8826            public static final String SECONDARY_EMAIL = "secondary_email";
8827
8828            /**
8829             * The extra field for an optional second contact email type.
8830             * <P>Type: Either an integer value from
8831             * {@link CommonDataKinds.Email}
8832             *  or a string specifying a custom label.</P>
8833             */
8834            public static final String SECONDARY_EMAIL_TYPE = "secondary_email_type";
8835
8836            /**
8837             * The extra field for an optional third contact email address.
8838             * <P>Type: String</P>
8839             */
8840            public static final String TERTIARY_EMAIL = "tertiary_email";
8841
8842            /**
8843             * The extra field for an optional third contact email type.
8844             * <P>Type: Either an integer value from
8845             * {@link CommonDataKinds.Email}
8846             *  or a string specifying a custom label.</P>
8847             */
8848            public static final String TERTIARY_EMAIL_TYPE = "tertiary_email_type";
8849
8850            /**
8851             * The extra field for the contact postal address.
8852             * <P>Type: String</P>
8853             */
8854            public static final String POSTAL = "postal";
8855
8856            /**
8857             * The extra field for the contact postal address type.
8858             * <P>Type: Either an integer value from
8859             * {@link CommonDataKinds.StructuredPostal}
8860             *  or a string specifying a custom label.</P>
8861             */
8862            public static final String POSTAL_TYPE = "postal_type";
8863
8864            /**
8865             * The extra field for the postal isprimary flag.
8866             * <P>Type: boolean</P>
8867             */
8868            public static final String POSTAL_ISPRIMARY = "postal_isprimary";
8869
8870            /**
8871             * The extra field for an IM handle.
8872             * <P>Type: String</P>
8873             */
8874            public static final String IM_HANDLE = "im_handle";
8875
8876            /**
8877             * The extra field for the IM protocol
8878             */
8879            public static final String IM_PROTOCOL = "im_protocol";
8880
8881            /**
8882             * The extra field for the IM isprimary flag.
8883             * <P>Type: boolean</P>
8884             */
8885            public static final String IM_ISPRIMARY = "im_isprimary";
8886
8887            /**
8888             * The extra field that allows the client to supply multiple rows of
8889             * arbitrary data for a single contact created using the {@link Intent#ACTION_INSERT}
8890             * or edited using {@link Intent#ACTION_EDIT}. It is an ArrayList of
8891             * {@link ContentValues}, one per data row. Supplying this extra is
8892             * similar to inserting multiple rows into the {@link Data} table,
8893             * except the user gets a chance to see and edit them before saving.
8894             * Each ContentValues object must have a value for {@link Data#MIMETYPE}.
8895             * If supplied values are not visible in the editor UI, they will be
8896             * dropped.  Duplicate data will dropped.  Some fields
8897             * like {@link CommonDataKinds.Email#TYPE Email.TYPE} may be automatically
8898             * adjusted to comply with the constraints of the specific account type.
8899             * For example, an Exchange contact can only have one phone numbers of type Home,
8900             * so the contact editor may choose a different type for this phone number to
8901             * avoid dropping the valueable part of the row, which is the phone number.
8902             * <p>
8903             * Example:
8904             * <pre>
8905             *  ArrayList&lt;ContentValues&gt; data = new ArrayList&lt;ContentValues&gt;();
8906             *
8907             *  ContentValues row1 = new ContentValues();
8908             *  row1.put(Data.MIMETYPE, Organization.CONTENT_ITEM_TYPE);
8909             *  row1.put(Organization.COMPANY, "Android");
8910             *  data.add(row1);
8911             *
8912             *  ContentValues row2 = new ContentValues();
8913             *  row2.put(Data.MIMETYPE, Email.CONTENT_ITEM_TYPE);
8914             *  row2.put(Email.TYPE, Email.TYPE_CUSTOM);
8915             *  row2.put(Email.LABEL, "Green Bot");
8916             *  row2.put(Email.ADDRESS, "android@android.com");
8917             *  data.add(row2);
8918             *
8919             *  Intent intent = new Intent(Intent.ACTION_INSERT, Contacts.CONTENT_URI);
8920             *  intent.putParcelableArrayListExtra(Insert.DATA, data);
8921             *
8922             *  startActivity(intent);
8923             * </pre>
8924             */
8925            public static final String DATA = "data";
8926
8927            /**
8928             * Used to specify the account in which to create the new contact.
8929             * <p>
8930             * If this value is not provided, the user is presented with a disambiguation
8931             * dialog to chose an account
8932             * <p>
8933             * Type: {@link Account}
8934             */
8935            public static final String EXTRA_ACCOUNT = "android.provider.extra.ACCOUNT";
8936
8937            /**
8938             * Used to specify the data set within the account in which to create the
8939             * new contact.
8940             * <p>
8941             * This value is optional - if it is not specified, the contact will be
8942             * created in the base account, with no data set.
8943             * <p>
8944             * Type: String
8945             */
8946            public static final String EXTRA_DATA_SET = "android.provider.extra.DATA_SET";
8947        }
8948    }
8949
8950    /**
8951     * @hide
8952     */
8953    protected interface MetadataSyncColumns {
8954
8955        /**
8956         * The raw contact backup id.
8957         * A reference to the {@link ContactsContract.RawContacts#BACKUP_ID} that save the
8958         * persistent unique id for each raw contact within its source system.
8959         *
8960         * @hide
8961         */
8962        public static final String RAW_CONTACT_BACKUP_ID = "raw_contact_backup_id";
8963
8964        /**
8965         * The account type to which the raw_contact of this item is associated. See
8966         * {@link RawContacts#ACCOUNT_TYPE}
8967         *
8968         * @hide
8969         */
8970        public static final String ACCOUNT_TYPE = "account_type";
8971
8972        /**
8973         * The account name to which the raw_contact of this item is associated. See
8974         * {@link RawContacts#ACCOUNT_NAME}
8975         *
8976         * @hide
8977         */
8978        public static final String ACCOUNT_NAME = "account_name";
8979
8980        /**
8981         * The data set within the account that the raw_contact of this row belongs to. This allows
8982         * multiple sync adapters for the same account type to distinguish between
8983         * each others' data.
8984         * {@link RawContacts#DATA_SET}
8985         *
8986         * @hide
8987         */
8988        public static final String DATA_SET = "data_set";
8989
8990        /**
8991         * A text column contains the Json string got from People API. The Json string contains
8992         * all the metadata related to the raw contact, i.e., all the data fields and
8993         * aggregation exceptions.
8994         *
8995         * Here is an example of the Json string got from the actual schema.
8996         * <pre>
8997         *     {
8998         *       "unique_contact_id": {
8999         *         "account_type": "CUSTOM_ACCOUNT",
9000         *         "custom_account_type": "facebook",
9001         *         "account_name": "android-test",
9002         *         "contact_id": "1111111",
9003         *         "data_set": "FOCUS"
9004         *       },
9005         *       "contact_prefs": {
9006         *         "send_to_voicemail": true,
9007         *         "starred": false,
9008         *         "pinned": 2
9009         *       },
9010         *       "aggregation_data": [
9011         *         {
9012         *           "type": "TOGETHER",
9013         *           "contact_ids": [
9014         *             {
9015         *               "account_type": "GOOGLE_ACCOUNT",
9016         *               "account_name": "android-test2",
9017         *               "contact_id": "2222222",
9018         *               "data_set": "GOOGLE_PLUS"
9019         *             },
9020         *             {
9021         *               "account_type": "GOOGLE_ACCOUNT",
9022         *               "account_name": "android-test3",
9023         *               "contact_id": "3333333",
9024         *               "data_set": "CUSTOM",
9025         *               "custom_data_set": "custom type"
9026         *             }
9027         *           ]
9028         *         }
9029         *       ],
9030         *       "field_data": [
9031         *         {
9032         *           "field_data_id": "1001",
9033         *           "field_data_prefs": {
9034         *             "is_primary": true,
9035         *             "is_super_primary": true
9036         *           },
9037         *           "usage_stats": [
9038         *             {
9039         *               "usage_type": "CALL",
9040         *               "last_time_used": 10000001,
9041         *               "usage_count": 10
9042         *             }
9043         *           ]
9044         *         }
9045         *       ]
9046         *     }
9047         * </pre>
9048         *
9049         * @hide
9050         */
9051        public static final String DATA = "data";
9052
9053        /**
9054         * The "deleted" flag: "0" by default, "1" if the row has been marked
9055         * for deletion. When {@link android.content.ContentResolver#delete} is
9056         * called on a raw contact, updating MetadataSync table to set the flag of the raw contact
9057         * as "1", then metadata sync adapter deletes the raw contact metadata on the server.
9058         * <P>Type: INTEGER</P>
9059         *
9060         * @hide
9061         */
9062        public static final String DELETED = "deleted";
9063    }
9064
9065    /**
9066     * Constants for the metadata sync table. This table is used to cache the metadata_sync data
9067     * from server before it is merged into other CP2 tables.
9068     *
9069     * @hide
9070     */
9071    public static final class MetadataSync implements BaseColumns, MetadataSyncColumns {
9072
9073        /** The authority for the contacts metadata */
9074        public static final String METADATA_AUTHORITY = "com.android.contacts.metadata";
9075
9076        /** A content:// style uri to the authority for the contacts metadata */
9077        public static final Uri METADATA_AUTHORITY_URI = Uri.parse(
9078                "content://" + METADATA_AUTHORITY);
9079
9080        /**
9081         * This utility class cannot be instantiated
9082         */
9083        private MetadataSync() {
9084        }
9085
9086        /**
9087         * The content:// style URI for this table.
9088         */
9089        public static final Uri CONTENT_URI = Uri.withAppendedPath(METADATA_AUTHORITY_URI,
9090                "metadata_sync");
9091
9092        /**
9093         * The MIME type of {@link #CONTENT_URI} providing a directory of contact metadata
9094         */
9095        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/contact_metadata";
9096
9097        /**
9098         * The MIME type of a {@link #CONTENT_URI} subdirectory of a single contact metadata.
9099         */
9100        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contact_metadata";
9101    }
9102}
9103