ContactsContract.java revision f3960b1271c65d64f9836894af600948bd804e7c
1/* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License 15 */ 16 17package android.provider; 18 19import android.accounts.Account; 20import android.content.ContentProviderClient; 21import android.content.ContentProviderOperation; 22import android.content.ContentResolver; 23import android.content.ContentUris; 24import android.content.ContentValues; 25import android.content.Context; 26import android.content.Intent; 27import android.content.CursorEntityIterator; 28import android.content.EntityIterator; 29import android.content.Entity; 30import android.content.res.Resources; 31import android.database.Cursor; 32import android.database.DatabaseUtils; 33import android.database.sqlite.SQLiteException; 34import android.graphics.Rect; 35import android.net.Uri; 36import android.os.RemoteException; 37import android.text.TextUtils; 38import android.util.Pair; 39import android.view.View; 40 41import java.io.ByteArrayInputStream; 42import java.io.InputStream; 43 44/** 45 * <p> 46 * The contract between the contacts provider and applications. Contains 47 * definitions for the supported URIs and columns. These APIs supersede 48 * {@link Contacts}. 49 * </p> 50 * <h3>Overview</h3> 51 * <p> 52 * ContactsContract defines an extensible database of contact-related 53 * information. Contact information is stored in a three-tier data model: 54 * </p> 55 * <blockquote> 56 * <p> 57 * The {@link Data} table contains all kinds of personal data: phone numbers, 58 * email addresses etc. The list of data kinds that can be stored in this table 59 * is open-ended. There is a predefined set of common kinds, but any application 60 * can add its own data kinds. 61 * </p> 62 * <p> 63 * A row in the {@link RawContacts} table represents a set of Data describing a 64 * person and associated with a single account. 65 * </p> 66 * <p> 67 * A row in the {@link Contacts} table represents an aggregate of one or more 68 * RawContacts presumably describing the same person. 69 * </p> 70 * </blockquote> 71 * <p> 72 * Other tables include: 73 * </p> 74 * <blockquote> 75 * <p> 76 * {@link Groups}, which contains information about raw contact groups - the 77 * current API does not support the notion of groups spanning multiple accounts. 78 * </p> 79 * <p> 80 * {@link StatusUpdates}, which contains social status updates including IM 81 * availability. 82 * </p> 83 * <p> 84 * {@link AggregationExceptions}, which is used for manual aggregation and 85 * disaggregation of raw contacts 86 * </p> 87 * <p> 88 * {@link Settings}, which contains visibility and sync settings for accounts 89 * and groups. 90 * </p> 91 * <p> 92 * {@link SyncState}, which contains free-form data maintained on behalf of sync 93 * adapters 94 * </p> 95 * <p> 96 * {@link PhoneLookup}, which is used for quick caller-ID lookup</id> 97 * </blockquote> 98 */ 99@SuppressWarnings("unused") 100public final class ContactsContract { 101 /** The authority for the contacts provider */ 102 public static final String AUTHORITY = "com.android.contacts"; 103 /** A content:// style uri to the authority for the contacts provider */ 104 public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY); 105 106 /** 107 * An optional insert, update or delete URI parameter that allows the caller 108 * to specify that it is a sync adapter. The default value is false. If true 109 * the dirty flag is not automatically set and the "syncToNetwork" parameter 110 * is set to false when calling 111 * {@link ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver, boolean)}. 112 */ 113 public static final String CALLER_IS_SYNCADAPTER = "caller_is_syncadapter"; 114 115 /** 116 * A query parameter key used to specify the package that is requesting a query. 117 * This is used for restricting data based on package name. 118 * 119 * @hide 120 */ 121 public static final String REQUESTING_PACKAGE_PARAM_KEY = "requesting_package"; 122 123 /** 124 * @hide should be removed when users are updated to refer to SyncState 125 * @deprecated use SyncState instead 126 */ 127 @Deprecated 128 public interface SyncStateColumns extends SyncStateContract.Columns { 129 } 130 131 /** 132 * A table provided for sync adapters to use for storing private sync state data. 133 * 134 * @see SyncStateContract 135 */ 136 public static final class SyncState implements SyncStateContract.Columns { 137 /** 138 * This utility class cannot be instantiated 139 */ 140 private SyncState() {} 141 142 public static final String CONTENT_DIRECTORY = 143 SyncStateContract.Constants.CONTENT_DIRECTORY; 144 145 /** 146 * The content:// style URI for this table 147 */ 148 public static final Uri CONTENT_URI = 149 Uri.withAppendedPath(AUTHORITY_URI, CONTENT_DIRECTORY); 150 151 /** 152 * @see android.provider.SyncStateContract.Helpers#get 153 */ 154 public static byte[] get(ContentProviderClient provider, Account account) 155 throws RemoteException { 156 return SyncStateContract.Helpers.get(provider, CONTENT_URI, account); 157 } 158 159 /** 160 * @see android.provider.SyncStateContract.Helpers#get 161 */ 162 public static Pair<Uri, byte[]> getWithUri(ContentProviderClient provider, Account account) 163 throws RemoteException { 164 return SyncStateContract.Helpers.getWithUri(provider, CONTENT_URI, account); 165 } 166 167 /** 168 * @see android.provider.SyncStateContract.Helpers#set 169 */ 170 public static void set(ContentProviderClient provider, Account account, byte[] data) 171 throws RemoteException { 172 SyncStateContract.Helpers.set(provider, CONTENT_URI, account, data); 173 } 174 175 /** 176 * @see android.provider.SyncStateContract.Helpers#newSetOperation 177 */ 178 public static ContentProviderOperation newSetOperation(Account account, byte[] data) { 179 return SyncStateContract.Helpers.newSetOperation(CONTENT_URI, account, data); 180 } 181 } 182 183 /** 184 * Generic columns for use by sync adapters. The specific functions of 185 * these columns are private to the sync adapter. Other clients of the API 186 * should not attempt to either read or write this column. 187 * 188 * @see RawContacts 189 * @see Groups 190 */ 191 protected interface BaseSyncColumns { 192 193 /** Generic column for use by sync adapters. */ 194 public static final String SYNC1 = "sync1"; 195 /** Generic column for use by sync adapters. */ 196 public static final String SYNC2 = "sync2"; 197 /** Generic column for use by sync adapters. */ 198 public static final String SYNC3 = "sync3"; 199 /** Generic column for use by sync adapters. */ 200 public static final String SYNC4 = "sync4"; 201 } 202 203 /** 204 * Columns that appear when each row of a table belongs to a specific 205 * account, including sync information that an account may need. 206 * 207 * @see RawContacts 208 * @see Groups 209 */ 210 protected interface SyncColumns extends BaseSyncColumns { 211 /** 212 * The name of the account instance to which this row belongs, which when paired with 213 * {@link #ACCOUNT_TYPE} identifies a specific account. 214 * <P>Type: TEXT</P> 215 */ 216 public static final String ACCOUNT_NAME = "account_name"; 217 218 /** 219 * The type of account to which this row belongs, which when paired with 220 * {@link #ACCOUNT_NAME} identifies a specific account. 221 * <P>Type: TEXT</P> 222 */ 223 public static final String ACCOUNT_TYPE = "account_type"; 224 225 /** 226 * String that uniquely identifies this row to its source account. 227 * <P>Type: TEXT</P> 228 */ 229 public static final String SOURCE_ID = "sourceid"; 230 231 /** 232 * Version number that is updated whenever this row or its related data 233 * changes. 234 * <P>Type: INTEGER</P> 235 */ 236 public static final String VERSION = "version"; 237 238 /** 239 * Flag indicating that {@link #VERSION} has changed, and this row needs 240 * to be synchronized by its owning account. 241 * <P>Type: INTEGER (boolean)</P> 242 */ 243 public static final String DIRTY = "dirty"; 244 } 245 246 /** 247 * @see Contacts 248 * @see RawContacts 249 * @see ContactsContract.Data 250 * @see PhoneLookup 251 * @see ContactsContract.Contacts.AggregationSuggestions 252 */ 253 protected interface ContactOptionsColumns { 254 /** 255 * The number of times a contact has been contacted 256 * <P>Type: INTEGER</P> 257 */ 258 public static final String TIMES_CONTACTED = "times_contacted"; 259 260 /** 261 * The last time a contact was contacted. 262 * <P>Type: INTEGER</P> 263 */ 264 public static final String LAST_TIME_CONTACTED = "last_time_contacted"; 265 266 /** 267 * Is the contact starred? 268 * <P>Type: INTEGER (boolean)</P> 269 */ 270 public static final String STARRED = "starred"; 271 272 /** 273 * A custom ringtone associated with a contact. Not always present. 274 * <P>Type: TEXT (URI to the ringtone)</P> 275 */ 276 public static final String CUSTOM_RINGTONE = "custom_ringtone"; 277 278 /** 279 * Whether the contact should always be sent to voicemail. Not always 280 * present. 281 * <P>Type: INTEGER (0 for false, 1 for true)</P> 282 */ 283 public static final String SEND_TO_VOICEMAIL = "send_to_voicemail"; 284 } 285 286 /** 287 * @see Contacts 288 * @see ContactsContract.Data 289 * @see PhoneLookup 290 * @see ContactsContract.Contacts.AggregationSuggestions 291 */ 292 protected interface ContactsColumns { 293 /** 294 * The display name for the contact. 295 * <P>Type: TEXT</P> 296 */ 297 public static final String DISPLAY_NAME = "display_name"; 298 299 /** 300 * Reference to the row in the RawContacts table holding the contact name. 301 * <P>Type: INTEGER REFERENCES raw_contacts(_id)</P> 302 * @hide 303 */ 304 public static final String NAME_RAW_CONTACT_ID = "name_raw_contact_id"; 305 306 /** 307 * Reference to the row in the data table holding the photo. 308 * <P>Type: INTEGER REFERENCES data(_id)</P> 309 */ 310 public static final String PHOTO_ID = "photo_id"; 311 312 /** 313 * Lookup value that reflects the {@link Groups#GROUP_VISIBLE} state of 314 * any {@link CommonDataKinds.GroupMembership} for this contact. 315 */ 316 public static final String IN_VISIBLE_GROUP = "in_visible_group"; 317 318 /** 319 * An indicator of whether this contact has at least one phone number. "1" if there is 320 * at least one phone number, "0" otherwise. 321 * <P>Type: INTEGER</P> 322 */ 323 public static final String HAS_PHONE_NUMBER = "has_phone_number"; 324 325 /** 326 * An opaque value that contains hints on how to find the contact if 327 * its row id changed as a result of a sync or aggregation. 328 */ 329 public static final String LOOKUP_KEY = "lookup"; 330 } 331 332 /** 333 * @see Contacts 334 */ 335 protected interface ContactStatusColumns { 336 /** 337 * Contact presence status. See {@link StatusUpdates} for individual status 338 * definitions. 339 * <p>Type: NUMBER</p> 340 */ 341 public static final String CONTACT_PRESENCE = "contact_presence"; 342 343 /** 344 * Contact's latest status update. 345 * <p>Type: TEXT</p> 346 */ 347 public static final String CONTACT_STATUS = "contact_status"; 348 349 /** 350 * The absolute time in milliseconds when the latest status was 351 * inserted/updated. 352 * <p>Type: NUMBER</p> 353 */ 354 public static final String CONTACT_STATUS_TIMESTAMP = "contact_status_ts"; 355 356 /** 357 * The package containing resources for this status: label and icon. 358 * <p>Type: TEXT</p> 359 */ 360 public static final String CONTACT_STATUS_RES_PACKAGE = "contact_status_res_package"; 361 362 /** 363 * The resource ID of the label describing the source of contact 364 * status, e.g. "Google Talk". This resource is scoped by the 365 * {@link #CONTACT_STATUS_RES_PACKAGE}. 366 * <p>Type: NUMBER</p> 367 */ 368 public static final String CONTACT_STATUS_LABEL = "contact_status_label"; 369 370 /** 371 * The resource ID of the icon for the source of contact status. This 372 * resource is scoped by the {@link #CONTACT_STATUS_RES_PACKAGE}. 373 * <p>Type: NUMBER</p> 374 */ 375 public static final String CONTACT_STATUS_ICON = "contact_status_icon"; 376 } 377 378 /** 379 * Constants for various styles of combining given name, family name etc into 380 * a full name. For example, the western tradition follows the pattern 381 * 'given name' 'middle name' 'family name' with the alternative pattern being 382 * 'family name', 'given name' 'middle name'. The CJK tradition is 383 * 'family name' 'middle name' 'given name', with Japanese favoring a space between 384 * the names and Chinese omitting the space. 385 * @hide 386 */ 387 public interface FullNameStyle { 388 public static final int UNDEFINED = 0; 389 public static final int WESTERN = 1; 390 391 /** 392 * Used if the name is written in Hanzi/Kanji/Hanja and we could not determine 393 * which specific language it belongs to: Chinese, Japanese or Korean. 394 */ 395 public static final int CJK = 2; 396 397 public static final int CHINESE = 3; 398 public static final int JAPANESE = 4; 399 public static final int KOREAN = 5; 400 } 401 402 /** 403 * Constants for various styles of capturing the pronunciation of a person's name. 404 * @hide 405 */ 406 public interface PhoneticNameStyle { 407 public static final int UNDEFINED = 0; 408 409 /** 410 * Pinyin is a phonetic method of entering Chinese characters. Typically not explicitly 411 * shown in UIs, but used for searches and sorting. 412 */ 413 public static final int PINYIN = 3; 414 415 /** 416 * Hiragana and Katakana are two common styles of writing out the pronunciation 417 * of a Japanese names. 418 */ 419 public static final int JAPANESE = 4; 420 421 /** 422 * Hangul is the Korean phonetic alphabet. 423 */ 424 public static final int KOREAN = 5; 425 } 426 427 /** 428 * Types of data used to produce the display name for a contact. Listed in the order 429 * of increasing priority. 430 * 431 * @hide 432 */ 433 public interface DisplayNameSources { 434 public static final int UNDEFINED = 0; 435 public static final int EMAIL = 10; 436 public static final int PHONE = 20; 437 public static final int ORGANIZATION = 30; 438 public static final int NICKNAME = 35; 439 public static final int STRUCTURED_NAME = 40; 440 } 441 442 /** 443 * @see Contacts 444 * @see RawContacts 445 * @hide 446 */ 447 protected interface ContactNameColumns { 448 449 /** 450 * The kind of data that is used as the display name for the contact, see 451 * DisplayNameSources. 452 */ 453 public static final String DISPLAY_NAME_SOURCE = "display_name_source"; 454 455 /** 456 * The default text shown as the contact's display name. It is based on 457 * available data, see {@link #DISPLAY_NAME_SOURCE}. 458 */ 459 public static final String DISPLAY_NAME = "display_name"; 460 461 /** 462 * Alternative representation of the display name. If display name is 463 * based on the structured name and the structured name follows 464 * the Western full name style, then this field contains the "family name first" 465 * version of the full name. Otherwise, it is the same as {@link #DISPLAY_NAME}. 466 */ 467 public static final String DISPLAY_NAME_ALTERNATIVE = "display_name_alt"; 468 469 /** 470 * The type of alphabet used to capture the phonetic name. See 471 * PhoneticNameStyle. 472 */ 473 public static final String PHONETIC_NAME_STYLE = "phonetic_name_style"; 474 475 /** 476 * Pronunciation of the full name. See PhoneticNameStyle. 477 */ 478 public static final String PHONETIC_NAME = "phonetic_name"; 479 480 /** 481 * Sort key that takes into account locale-based traditions for sorting 482 * names in address books. More specifically, for Chinese names 483 * the sort key is the name's Pinyin spelling; for Japanese names 484 * it is the Hiragana version of the phonetic name. 485 */ 486 public static final String SORT_KEY = "sort_key"; 487 488 /** 489 * Sort key based on the alternative representation of the full name, 490 * specifically the one using the 'family name first' format for 491 * Western names. 492 */ 493 public static final String SORT_KEY_ALTERNATIVE = "sort_key_alt"; 494 } 495 496 /** 497 * Constants for the contacts table, which contains a record per aggregate 498 * of raw contacts representing the same person. 499 * <h3>Operations</h3> 500 * <dl> 501 * <dt><b>Insert</b></dt> 502 * <dd>A Contact cannot be created explicitly. When a raw contact is 503 * inserted, the provider will first try to find a Contact representing the 504 * same person. If one is found, the raw contact's 505 * {@link RawContacts#CONTACT_ID} column gets the _ID of the aggregate 506 * Contact. If no match is found, the provider automatically inserts a new 507 * Contact and puts its _ID into the {@link RawContacts#CONTACT_ID} column 508 * of the newly inserted raw contact.</dd> 509 * <dt><b>Update</b></dt> 510 * <dd>Only certain columns of Contact are modifiable: 511 * {@link #TIMES_CONTACTED}, {@link #LAST_TIME_CONTACTED}, {@link #STARRED}, 512 * {@link #CUSTOM_RINGTONE}, {@link #SEND_TO_VOICEMAIL}. Changing any of 513 * these columns on the Contact also changes them on all constituent raw 514 * contacts.</dd> 515 * <dt><b>Delete</b></dt> 516 * <dd>Be careful with deleting Contacts! Deleting an aggregate contact 517 * deletes all constituent raw contacts. The corresponding sync adapters 518 * will notice the deletions of their respective raw contacts and remove 519 * them from their back end storage.</dd> 520 * <dt><b>Query</b></dt> 521 * <dd> 522 * <ul> 523 * <li>If you need to read an individual contact, consider using 524 * {@link #CONTENT_LOOKUP_URI} instead of {@link #CONTENT_URI}.</li> 525 * <li>If you need to look up a contact by the phone number, use 526 * {@link PhoneLookup#CONTENT_FILTER_URI PhoneLookup.CONTENT_FILTER_URI}, 527 * which is optimized for this purpose.</li> 528 * <li>If you need to look up a contact by partial name, e.g. to produce 529 * filter-as-you-type suggestions, use the {@link #CONTENT_FILTER_URI} URI. 530 * <li>If you need to look up a contact by some data element like email 531 * address, nickname, etc, use a query against the {@link ContactsContract.Data} table. 532 * The result will contain contact ID, name etc. 533 * </ul> 534 * </dd> 535 * </dl> 536 * <h2>Columns</h2> 537 * <table class="jd-sumtable"> 538 * <tr> 539 * <th colspan='4'>Contacts</th> 540 * </tr> 541 * <tr> 542 * <td>long</td> 543 * <td>{@link #_ID}</td> 544 * <td>read-only</td> 545 * <td>Row ID. Consider using {@link #LOOKUP_KEY} instead.</td> 546 * </tr> 547 * <tr> 548 * <td>String</td> 549 * <td>{@link #LOOKUP_KEY}</td> 550 * <td>read-only</td> 551 * <td>An opaque value that contains hints on how to find the contact if its 552 * row id changed as a result of a sync or aggregation.</td> 553 * </tr> 554 * <tr> 555 * <td>long</td> 556 * <td>NAME_RAW_CONTACT_ID</td> 557 * <td>read-only</td> 558 * <td>The ID of the raw contact that contributes the display name 559 * to the aggregate contact. During aggregation one of the constituent 560 * raw contacts is chosen using a heuristic: a longer name or a name 561 * with more diacritic marks or more upper case characters is chosen.</td> 562 * </tr> 563 * <tr> 564 * <td>String</td> 565 * <td>{@link #DISPLAY_NAME}</td> 566 * <td>read-only</td> 567 * <td>The display name for the contact. It is the display name 568 * contributed by the raw contact referred to by the NAME_RAW_CONTACT_ID 569 * column.</td> 570 * </tr> 571 * <tr> 572 * <td>long</td> 573 * <td>{@link #PHOTO_ID}</td> 574 * <td>read-only</td> 575 * <td>Reference to the row in the {@link ContactsContract.Data} table holding the photo. 576 * That row has the mime type 577 * {@link CommonDataKinds.Photo#CONTENT_ITEM_TYPE}. The value of this field 578 * is computed automatically based on the 579 * {@link CommonDataKinds.Photo#IS_SUPER_PRIMARY} field of the data rows of 580 * that mime type.</td> 581 * </tr> 582 * <tr> 583 * <td>int</td> 584 * <td>{@link #IN_VISIBLE_GROUP}</td> 585 * <td>read-only</td> 586 * <td>An indicator of whether this contact is supposed to be visible in the 587 * UI. "1" if the contact has at least one raw contact that belongs to a 588 * visible group; "0" otherwise.</td> 589 * </tr> 590 * <tr> 591 * <td>int</td> 592 * <td>{@link #HAS_PHONE_NUMBER}</td> 593 * <td>read-only</td> 594 * <td>An indicator of whether this contact has at least one phone number. 595 * "1" if there is at least one phone number, "0" otherwise.</td> 596 * </tr> 597 * <tr> 598 * <td>int</td> 599 * <td>{@link #TIMES_CONTACTED}</td> 600 * <td>read/write</td> 601 * <td>The number of times the contact has been contacted. See 602 * {@link #markAsContacted}. When raw contacts are aggregated, this field is 603 * computed automatically as the maximum number of times contacted among all 604 * constituent raw contacts. Setting this field automatically changes the 605 * corresponding field on all constituent raw contacts.</td> 606 * </tr> 607 * <tr> 608 * <td>long</td> 609 * <td>{@link #LAST_TIME_CONTACTED}</td> 610 * <td>read/write</td> 611 * <td>The timestamp of the last time the contact was contacted. See 612 * {@link #markAsContacted}. Setting this field also automatically 613 * increments {@link #TIMES_CONTACTED}. When raw contacts are aggregated, 614 * this field is computed automatically as the latest time contacted of all 615 * constituent raw contacts. Setting this field automatically changes the 616 * corresponding field on all constituent raw contacts.</td> 617 * </tr> 618 * <tr> 619 * <td>int</td> 620 * <td>{@link #STARRED}</td> 621 * <td>read/write</td> 622 * <td>An indicator for favorite contacts: '1' if favorite, '0' otherwise. 623 * When raw contacts are aggregated, this field is automatically computed: 624 * if any constituent raw contacts are starred, then this field is set to 625 * '1'. Setting this field automatically changes the corresponding field on 626 * all constituent raw contacts.</td> 627 * </tr> 628 * <tr> 629 * <td>String</td> 630 * <td>{@link #CUSTOM_RINGTONE}</td> 631 * <td>read/write</td> 632 * <td>A custom ringtone associated with a contact. Typically this is the 633 * URI returned by an activity launched with the 634 * {@link android.media.RingtoneManager#ACTION_RINGTONE_PICKER} intent.</td> 635 * </tr> 636 * <tr> 637 * <td>int</td> 638 * <td>{@link #SEND_TO_VOICEMAIL}</td> 639 * <td>read/write</td> 640 * <td>An indicator of whether calls from this contact should be forwarded 641 * directly to voice mail ('1') or not ('0'). When raw contacts are 642 * aggregated, this field is automatically computed: if <i>all</i> 643 * constituent raw contacts have SEND_TO_VOICEMAIL=1, then this field is set 644 * to '1'. Setting this field automatically changes the corresponding field 645 * on all constituent raw contacts.</td> 646 * </tr> 647 * <tr> 648 * <td>int</td> 649 * <td>{@link #CONTACT_PRESENCE}</td> 650 * <td>read-only</td> 651 * <td>Contact IM presence status. See {@link StatusUpdates} for individual 652 * status definitions. Automatically computed as the highest presence of all 653 * constituent raw contacts. The provider may choose not to store this value 654 * in persistent storage. The expectation is that presence status will be 655 * updated on a regular basic.</td> 656 * </tr> 657 * <tr> 658 * <td>String</td> 659 * <td>{@link #CONTACT_STATUS}</td> 660 * <td>read-only</td> 661 * <td>Contact's latest status update. Automatically computed as the latest 662 * of all constituent raw contacts' status updates.</td> 663 * </tr> 664 * <tr> 665 * <td>long</td> 666 * <td>{@link #CONTACT_STATUS_TIMESTAMP}</td> 667 * <td>read-only</td> 668 * <td>The absolute time in milliseconds when the latest status was 669 * inserted/updated.</td> 670 * </tr> 671 * <tr> 672 * <td>String</td> 673 * <td>{@link #CONTACT_STATUS_RES_PACKAGE}</td> 674 * <td>read-only</td> 675 * <td> The package containing resources for this status: label and icon.</td> 676 * </tr> 677 * <tr> 678 * <td>long</td> 679 * <td>{@link #CONTACT_STATUS_LABEL}</td> 680 * <td>read-only</td> 681 * <td>The resource ID of the label describing the source of contact status, 682 * e.g. "Google Talk". This resource is scoped by the 683 * {@link #CONTACT_STATUS_RES_PACKAGE}.</td> 684 * </tr> 685 * <tr> 686 * <td>long</td> 687 * <td>{@link #CONTACT_STATUS_ICON}</td> 688 * <td>read-only</td> 689 * <td>The resource ID of the icon for the source of contact status. This 690 * resource is scoped by the {@link #CONTACT_STATUS_RES_PACKAGE}.</td> 691 * </tr> 692 * </table> 693 */ 694 public static class Contacts implements BaseColumns, ContactsColumns, 695 ContactOptionsColumns, ContactStatusColumns { 696 /** 697 * This utility class cannot be instantiated 698 */ 699 private Contacts() {} 700 701 /** 702 * The content:// style URI for this table 703 */ 704 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "contacts"); 705 706 /** 707 * A content:// style URI for this table that should be used to create 708 * shortcuts or otherwise create long-term links to contacts. This URI 709 * should always be followed by a "/" and the contact's {@link #LOOKUP_KEY}. 710 * It can optionally also have a "/" and last known contact ID appended after 711 * that. This "complete" format is an important optimization and is highly recommended. 712 * <p> 713 * As long as the contact's row ID remains the same, this URI is 714 * equivalent to {@link #CONTENT_URI}. If the contact's row ID changes 715 * as a result of a sync or aggregation, this URI will look up the 716 * contact using indirect information (sync IDs or constituent raw 717 * contacts). 718 * <p> 719 * Lookup key should be appended unencoded - it is stored in the encoded 720 * form, ready for use in a URI. 721 */ 722 public static final Uri CONTENT_LOOKUP_URI = Uri.withAppendedPath(CONTENT_URI, 723 "lookup"); 724 725 /** 726 * Base {@link Uri} for referencing a single {@link Contacts} entry, 727 * created by appending {@link #LOOKUP_KEY} using 728 * {@link Uri#withAppendedPath(Uri, String)}. Provides 729 * {@link OpenableColumns} columns when queried, or returns the 730 * referenced contact formatted as a vCard when opened through 731 * {@link ContentResolver#openAssetFileDescriptor(Uri, String)}. 732 */ 733 public static final Uri CONTENT_VCARD_URI = Uri.withAppendedPath(CONTENT_URI, 734 "as_vcard"); 735 736 /** 737 * Builds a {@link #CONTENT_LOOKUP_URI} style {@link Uri} describing the 738 * requested {@link Contacts} entry. 739 * 740 * @param contactUri A {@link #CONTENT_URI} row, or an existing 741 * {@link #CONTENT_LOOKUP_URI} to attempt refreshing. 742 */ 743 public static Uri getLookupUri(ContentResolver resolver, Uri contactUri) { 744 final Cursor c = resolver.query(contactUri, new String[] { 745 Contacts.LOOKUP_KEY, Contacts._ID 746 }, null, null, null); 747 if (c == null) { 748 return null; 749 } 750 751 try { 752 if (c.moveToFirst()) { 753 final String lookupKey = c.getString(0); 754 final long contactId = c.getLong(1); 755 return getLookupUri(contactId, lookupKey); 756 } 757 } finally { 758 c.close(); 759 } 760 return null; 761 } 762 763 /** 764 * Build a {@link #CONTENT_LOOKUP_URI} lookup {@link Uri} using the 765 * given {@link ContactsContract.Contacts#_ID} and {@link #LOOKUP_KEY}. 766 */ 767 public static Uri getLookupUri(long contactId, String lookupKey) { 768 return ContentUris.withAppendedId(Uri.withAppendedPath(Contacts.CONTENT_LOOKUP_URI, 769 lookupKey), contactId); 770 } 771 772 /** 773 * Computes a content URI (see {@link #CONTENT_URI}) given a lookup URI. 774 * <p> 775 * Returns null if the contact cannot be found. 776 */ 777 public static Uri lookupContact(ContentResolver resolver, Uri lookupUri) { 778 if (lookupUri == null) { 779 return null; 780 } 781 782 Cursor c = resolver.query(lookupUri, new String[]{Contacts._ID}, null, null, null); 783 if (c == null) { 784 return null; 785 } 786 787 try { 788 if (c.moveToFirst()) { 789 long contactId = c.getLong(0); 790 return ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId); 791 } 792 } finally { 793 c.close(); 794 } 795 return null; 796 } 797 798 /** 799 * Mark a contact as having been contacted. 800 * 801 * @param resolver the ContentResolver to use 802 * @param contactId the person who was contacted 803 */ 804 public static void markAsContacted(ContentResolver resolver, long contactId) { 805 Uri uri = ContentUris.withAppendedId(CONTENT_URI, contactId); 806 ContentValues values = new ContentValues(); 807 // TIMES_CONTACTED will be incremented when LAST_TIME_CONTACTED is modified. 808 values.put(LAST_TIME_CONTACTED, System.currentTimeMillis()); 809 resolver.update(uri, values, null, null); 810 } 811 812 /** 813 * The content:// style URI used for "type-to-filter" functionality on the 814 * {@link #CONTENT_URI} URI. The filter string will be used to match 815 * various parts of the contact name. The filter argument should be passed 816 * as an additional path segment after this URI. 817 */ 818 public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath( 819 CONTENT_URI, "filter"); 820 821 /** 822 * The content:// style URI for this table joined with useful data from 823 * {@link ContactsContract.Data}, filtered to include only starred contacts 824 * and the most frequently contacted contacts. 825 */ 826 public static final Uri CONTENT_STREQUENT_URI = Uri.withAppendedPath( 827 CONTENT_URI, "strequent"); 828 829 /** 830 * The content:// style URI used for "type-to-filter" functionality on the 831 * {@link #CONTENT_STREQUENT_URI} URI. The filter string will be used to match 832 * various parts of the contact name. The filter argument should be passed 833 * as an additional path segment after this URI. 834 */ 835 public static final Uri CONTENT_STREQUENT_FILTER_URI = Uri.withAppendedPath( 836 CONTENT_STREQUENT_URI, "filter"); 837 838 public static final Uri CONTENT_GROUP_URI = Uri.withAppendedPath( 839 CONTENT_URI, "group"); 840 841 /** 842 * The MIME type of {@link #CONTENT_URI} providing a directory of 843 * people. 844 */ 845 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/contact"; 846 847 /** 848 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 849 * person. 850 */ 851 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contact"; 852 853 /** 854 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 855 * person. 856 */ 857 public static final String CONTENT_VCARD_TYPE = "text/x-vcard"; 858 859 /** 860 * A sub-directory of a single contact that contains all of the constituent raw contact 861 * {@link ContactsContract.Data} rows. 862 */ 863 public static final class Data implements BaseColumns, DataColumns { 864 /** 865 * no public constructor since this is a utility class 866 */ 867 private Data() {} 868 869 /** 870 * The directory twig for this sub-table 871 */ 872 public static final String CONTENT_DIRECTORY = "data"; 873 } 874 875 /** 876 * <p> 877 * A <i>read-only</i> sub-directory of a single contact aggregate that 878 * contains all aggregation suggestions (other contacts). The 879 * aggregation suggestions are computed based on approximate data 880 * matches with this contact. 881 * </p> 882 * <p> 883 * <i>Note: this query may be expensive! If you need to use it in bulk, 884 * make sure the user experience is acceptable when the query runs for a 885 * long time.</i> 886 * <p> 887 * Usage example: 888 * 889 * <pre> 890 * Uri uri = Contacts.CONTENT_URI.buildUpon() 891 * .appendEncodedPath(String.valueOf(contactId)) 892 * .appendPath(Contacts.AggregationSuggestions.CONTENT_DIRECTORY) 893 * .appendQueryParameter("limit", "3") 894 * .build() 895 * Cursor cursor = getContentResolver().query(suggestionsUri, 896 * new String[] {Contacts.DISPLAY_NAME, Contacts._ID, Contacts.LOOKUP_KEY}, 897 * null, null, null); 898 * </pre> 899 * 900 * </p> 901 */ 902 // TODO: add ContactOptionsColumns, ContactStatusColumns 903 public static final class AggregationSuggestions implements BaseColumns, ContactsColumns { 904 /** 905 * No public constructor since this is a utility class 906 */ 907 private AggregationSuggestions() {} 908 909 /** 910 * The directory twig for this sub-table. The URI can be followed by an optional 911 * type-to-filter, similar to 912 * {@link android.provider.ContactsContract.Contacts#CONTENT_FILTER_URI}. 913 */ 914 public static final String CONTENT_DIRECTORY = "suggestions"; 915 } 916 917 /** 918 * A <i>read-only</i> sub-directory of a single contact that contains 919 * the contact's primary photo. 920 * <p> 921 * Usage example: 922 * 923 * <pre> 924 * public InputStream openPhoto(long contactId) { 925 * Uri contactUri = ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId); 926 * Uri photoUri = Uri.withAppendedPath(contactUri, Contacts.Photo.CONTENT_DIRECTORY); 927 * Cursor cursor = getContentResolver().query(photoUri, 928 * new String[] {Contacts.Photo.PHOTO}, null, null, null); 929 * if (cursor == null) { 930 * return null; 931 * } 932 * try { 933 * if (cursor.moveToFirst()) { 934 * byte[] data = cursor.getBlob(0); 935 * if (data != null) { 936 * return new ByteArrayInputStream(data); 937 * } 938 * } 939 * } finally { 940 * cursor.close(); 941 * } 942 * return null; 943 * } 944 * </pre> 945 * 946 * </p> 947 * <p>You should also consider using the convenience method 948 * {@link ContactsContract.Contacts#openContactPhotoInputStream(ContentResolver, Uri)} 949 * </p> 950 */ 951 // TODO: change DataColumns to DataColumnsWithJoins 952 public static final class Photo implements BaseColumns, DataColumns { 953 /** 954 * no public constructor since this is a utility class 955 */ 956 private Photo() {} 957 958 /** 959 * The directory twig for this sub-table 960 */ 961 public static final String CONTENT_DIRECTORY = "photo"; 962 963 /** 964 * Thumbnail photo of the raw contact. This is the raw bytes of an image 965 * that could be inflated using {@link android.graphics.BitmapFactory}. 966 * <p> 967 * Type: BLOB 968 * @hide TODO: Unhide in a separate CL 969 */ 970 public static final String PHOTO = DATA15; 971 } 972 973 /** 974 * Opens an InputStream for the contacts's default photo and returns the 975 * photo as a byte stream. If there is not photo null will be returned. 976 * 977 * @param contactUri the contact whose photo should be used 978 * @return an InputStream of the photo, or null if no photo is present 979 */ 980 public static InputStream openContactPhotoInputStream(ContentResolver cr, Uri contactUri) { 981 Uri photoUri = Uri.withAppendedPath(contactUri, Photo.CONTENT_DIRECTORY); 982 if (photoUri == null) { 983 return null; 984 } 985 Cursor cursor = cr.query(photoUri, 986 new String[]{ContactsContract.CommonDataKinds.Photo.PHOTO}, null, null, null); 987 try { 988 if (cursor == null || !cursor.moveToNext()) { 989 return null; 990 } 991 byte[] data = cursor.getBlob(0); 992 if (data == null) { 993 return null; 994 } 995 return new ByteArrayInputStream(data); 996 } finally { 997 if (cursor != null) { 998 cursor.close(); 999 } 1000 } 1001 } 1002 } 1003 1004 protected interface RawContactsColumns { 1005 /** 1006 * A reference to the {@link ContactsContract.Contacts#_ID} that this 1007 * data belongs to. 1008 * <P>Type: INTEGER</P> 1009 */ 1010 public static final String CONTACT_ID = "contact_id"; 1011 1012 /** 1013 * Flag indicating that this {@link RawContacts} entry and its children have 1014 * been restricted to specific platform apps. 1015 * <P>Type: INTEGER (boolean)</P> 1016 * 1017 * @hide until finalized in future platform release 1018 */ 1019 public static final String IS_RESTRICTED = "is_restricted"; 1020 1021 /** 1022 * The aggregation mode for this contact. 1023 * <P>Type: INTEGER</P> 1024 */ 1025 public static final String AGGREGATION_MODE = "aggregation_mode"; 1026 1027 /** 1028 * The "deleted" flag: "0" by default, "1" if the row has been marked 1029 * for deletion. When {@link android.content.ContentResolver#delete} is 1030 * called on a raw contact, it is marked for deletion and removed from its 1031 * aggregate contact. The sync adaptor deletes the raw contact on the server and 1032 * then calls ContactResolver.delete once more, this time passing the 1033 * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to finalize 1034 * the data removal. 1035 * <P>Type: INTEGER</P> 1036 */ 1037 public static final String DELETED = "deleted"; 1038 } 1039 1040 /** 1041 * Constants for the raw contacts table, which contains the base contact 1042 * information per sync source. Sync adapters and contact management apps 1043 * are the primary consumers of this API. 1044 * <h3>Operations</h3> 1045 * <dl> 1046 * <dt><b>Insert</b></dt> 1047 * <dd>There are two mechanisms that can be used to insert a raw contact: incremental and 1048 * batch. The incremental method is more traditional but less efficient. It should be used 1049 * only if the constituent data rows are unavailable at the time the raw contact is created: 1050 * <pre> 1051 * ContentValues values = new ContentValues(); 1052 * values.put(RawContacts.ACCOUNT_TYPE, accountType); 1053 * values.put(RawContacts.ACCOUNT_NAME, accountName); 1054 * Uri rawContactUri = getContentResolver().insert(RawContacts.CONTENT_URI, values); 1055 * long rawContactId = ContentUris.parseId(rawContactUri); 1056 * </pre> 1057 * <p> 1058 * Once data rows are available, insert those. For example, here's how you would insert 1059 * a name: 1060 * 1061 * <pre> 1062 * values.clear(); 1063 * values.put(Data.RAW_CONTACT_ID, rawContactId); 1064 * values.put(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE); 1065 * values.put(StructuredName.DISPLAY_NAME, "Mike Sullivan"); 1066 * getContentResolver().insert(Data.CONTENT_URI, values); 1067 * </pre> 1068 * </p> 1069 * <p> 1070 * The batch method is by far preferred. It inserts the raw contact and its 1071 * constituent data rows in a single database transaction 1072 * and causes at most one aggregation pass. 1073 * <pre> 1074 * ArrayList<ContentProviderOperation> ops = Lists.newArrayList(); 1075 * int rawContactInsertIndex = ops.size(); 1076 * ops.add(ContentProviderOperation.newInsert(RawContacts.CONTENT_URI) 1077 * .withValue(RawContacts.ACCOUNT_TYPE, accountType) 1078 * .withValue(RawContacts.ACCOUNT_NAME, accountName) 1079 * .build()); 1080 * 1081 * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI) 1082 * .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex) 1083 * .withValue(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE) 1084 * .withValue(StructuredName.DISPLAY_NAME, "Mike Sullivan") 1085 * .build()); 1086 * 1087 * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); 1088 * </pre> 1089 * </p> 1090 * <p> 1091 * Please note the use of back reference in the construction of the 1092 * {@link ContentProviderOperation}. It allows an operation to use the result of 1093 * a previous operation by referring to it by its index in the batch. 1094 * </p> 1095 * <dt><b>Update</b></dt> 1096 * <dd><p>Just as with insert, the update can be done incrementally or as a batch, the 1097 * batch mode being the preferred method.</p></dd> 1098 * <dt><b>Delete</b></dt> 1099 * <dd><p>When a raw contact is deleted, all of its Data rows as well as StatusUpdates, 1100 * AggregationExceptions, PhoneLookup rows are deleted automatically. When all raw 1101 * contacts in a Contact are deleted, the Contact itself is also deleted automatically. 1102 * </p> 1103 * <p> 1104 * The invocation of {@code resolver.delete(...)}, does not physically delete 1105 * a raw contacts row. It sets the {@link #DELETED} flag on the raw contact and 1106 * removes the raw contact from its aggregate contact. 1107 * The sync adapter then deletes the raw contact from the server and 1108 * finalizes phone-side deletion by calling {@code resolver.delete(...)} 1109 * again and passing the {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter.<p> 1110 * <p>Some sync adapters are read-only, meaning that they only sync server-side 1111 * changes to the phone, but not the reverse. If one of those raw contacts 1112 * is marked for deletion, it will remain on the phone. However it will be 1113 * effectively invisible, because it will not be part of any aggregate contact. 1114 * </dd> 1115 * <dt><b>Query</b></dt> 1116 * <dd> 1117 * <p> 1118 * Finding all raw contacts in a Contact is easy: 1119 * <pre> 1120 * Cursor c = getContentResolver().query(RawContacts.CONTENT_URI, 1121 * new String[]{RawContacts._ID}, 1122 * RawContacts.CONTACT_ID + "=?", 1123 * new String[]{String.valueOf(contactId)}, null); 1124 * </pre> 1125 * </p> 1126 * <p> 1127 * There are two ways to find raw contacts within a specific account, 1128 * you can either put the account name and type in the selection or pass them as query 1129 * parameters. The latter approach is preferable, especially when you can reuse the 1130 * URI: 1131 * <pre> 1132 * Uri rawContactUri = RawContacts.URI.buildUpon() 1133 * .appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName) 1134 * .appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType) 1135 * .build(); 1136 * Cursor c1 = getContentResolver().query(rawContactUri, 1137 * RawContacts.STARRED + "<>0", null, null, null); 1138 * ... 1139 * Cursor c2 = getContentResolver().query(rawContactUri, 1140 * RawContacts.DELETED + "<>0", null, null, null); 1141 * </pre> 1142 * </p> 1143 * <p>The best way to read a raw contact along with all the data associated with it is 1144 * by using the {@link Entity} directory. If the raw contact has data rows, 1145 * the Entity cursor will contain a row for each data row. If the raw contact has no 1146 * data rows, the cursor will still contain one row with the raw contact-level information. 1147 * <pre> 1148 * Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactId); 1149 * Uri entityUri = Uri.withAppendedPath(rawContactUri, Entity.CONTENT_DIRECTORY); 1150 * Cursor c = getContentResolver().query(entityUri, 1151 * new String[]{RawContacts.SOURCE_ID, Entity.DATA_ID, Entity.MIMETYPE, Entity.DATA1}, 1152 * null, null, null); 1153 * try { 1154 * while (c.moveToNext()) { 1155 * String sourceId = c.getString(0); 1156 * if (!c.isNull(1)) { 1157 * String mimeType = c.getString(2); 1158 * String data = c.getString(3); 1159 * ... 1160 * } 1161 * } 1162 * } finally { 1163 * c.close(); 1164 * } 1165 * </pre> 1166 * </p> 1167 * </dd> 1168 * </dl> 1169 * <h3>Aggregation</h3> 1170 * <p> 1171 * As soon as a raw contact is inserted or whenever its constituent data 1172 * changes, the provider will check if the raw contact matches other 1173 * existing raw contacts and if so will aggregate it with those. From the 1174 * data standpoint, aggregation is reflected in the change of the 1175 * {@link #CONTACT_ID} field, which is the reference to the aggregate contact. 1176 * </p> 1177 * <p> 1178 * See also {@link AggregationExceptions} for a mechanism to control 1179 * aggregation programmatically. 1180 * </p> 1181 * <h2>Columns</h2> 1182 * <table class="jd-sumtable"> 1183 * <tr> 1184 * <th colspan='4'>RawContacts</th> 1185 * </tr> 1186 * <tr> 1187 * <td>long</td> 1188 * <td>{@link #_ID}</td> 1189 * <td>read-only</td> 1190 * <td>Row ID. Sync adapter should try to preserve row IDs during updates. In other words, 1191 * it would be a really bad idea to delete and reinsert a raw contact. A sync adapter should 1192 * always do an update instead.</td> 1193 * </tr> 1194 * <tr> 1195 * <td>long</td> 1196 * <td>{@link #CONTACT_ID}</td> 1197 * <td>read-only</td> 1198 * <td>A reference to the {@link ContactsContract.Contacts#_ID} that this raw contact belongs 1199 * to. Raw contacts are linked to contacts by the aggregation process, which can be controlled 1200 * by the {@link #AGGREGATION_MODE} field and {@link AggregationExceptions}.</td> 1201 * </tr> 1202 * <tr> 1203 * <td>int</td> 1204 * <td>{@link #AGGREGATION_MODE}</td> 1205 * <td>read/write</td> 1206 * <td>A mechanism that allows programmatic control of the aggregation process. The allowed 1207 * values are {@link #AGGREGATION_MODE_DEFAULT}, {@link #AGGREGATION_MODE_DISABLED} 1208 * and {@link #AGGREGATION_MODE_SUSPENDED}. See also {@link AggregationExceptions}.</td> 1209 * </tr> 1210 * <tr> 1211 * <td>int</td> 1212 * <td>{@link #DELETED}</td> 1213 * <td>read/write</td> 1214 * <td>The "deleted" flag: "0" by default, "1" if the row has been marked 1215 * for deletion. When {@link android.content.ContentResolver#delete} is 1216 * called on a raw contact, it is marked for deletion and removed from its 1217 * aggregate contact. The sync adaptor deletes the raw contact on the server and 1218 * then calls ContactResolver.delete once more, this time passing the 1219 * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to finalize 1220 * the data removal.</td> 1221 * </tr> 1222 * <tr> 1223 * <td>int</td> 1224 * <td>{@link #TIMES_CONTACTED}</td> 1225 * <td>read/write</td> 1226 * <td>The number of times the contact has been contacted. To have an effect 1227 * on the corresponding value of the aggregate contact, this field 1228 * should be set at the time the raw contact is inserted. 1229 * See {@link ContactsContract.Contacts#markAsContacted}.</td> 1230 * </tr> 1231 * <tr> 1232 * <td>long</td> 1233 * <td>{@link #LAST_TIME_CONTACTED}</td> 1234 * <td>read/write</td> 1235 * <td>The timestamp of the last time the contact was contacted. To have an effect 1236 * on the corresponding value of the aggregate contact, this field 1237 * should be set at the time the raw contact is inserted. 1238 * See {@link ContactsContract.Contacts#markAsContacted}.</td> 1239 * </tr> 1240 * <tr> 1241 * <td>int</td> 1242 * <td>{@link #STARRED}</td> 1243 * <td>read/write</td> 1244 * <td>An indicator for favorite contacts: '1' if favorite, '0' otherwise. 1245 * Changing this field immediately effects the corresponding aggregate contact: 1246 * if any raw contacts in that aggregate contact are starred, then the contact 1247 * itself is marked as starred.</td> 1248 * </tr> 1249 * <tr> 1250 * <td>String</td> 1251 * <td>{@link #CUSTOM_RINGTONE}</td> 1252 * <td>read/write</td> 1253 * <td>A custom ringtone associated with a raw contact. Typically this is the 1254 * URI returned by an activity launched with the 1255 * {@link android.media.RingtoneManager#ACTION_RINGTONE_PICKER} intent. 1256 * To have an effect on the corresponding value of the aggregate contact, this field 1257 * should be set at the time the raw contact is inserted. To set a custom 1258 * ringtone on a contact, use the field {@link ContactsContract.Contacts#CUSTOM_RINGTONE} 1259 * instead.</td> 1260 * </tr> 1261 * <tr> 1262 * <td>int</td> 1263 * <td>{@link #SEND_TO_VOICEMAIL}</td> 1264 * <td>read/write</td> 1265 * <td>An indicator of whether calls from this raw contact should be forwarded 1266 * directly to voice mail ('1') or not ('0'). To have an effect 1267 * on the corresponding value of the aggregate contact, this field 1268 * should be set at the time the raw contact is inserted.</td> 1269 * </tr> 1270 * <tr> 1271 * <td>String</td> 1272 * <td>{@link #ACCOUNT_NAME}</td> 1273 * <td>read/write-once</td> 1274 * <td>The name of the account instance to which this row belongs, which when paired with 1275 * {@link #ACCOUNT_TYPE} identifies a specific account. It should be set at the time 1276 * the raw contact is inserted and never changed afterwards.</td> 1277 * </tr> 1278 * <tr> 1279 * <td>String</td> 1280 * <td>{@link #ACCOUNT_TYPE}</td> 1281 * <td>read/write-once</td> 1282 * <td>The type of account to which this row belongs, which when paired with 1283 * {@link #ACCOUNT_NAME} identifies a specific account. It should be set at the time 1284 * the raw contact is inserted and never changed afterwards.</td> 1285 * </tr> 1286 * <tr> 1287 * <td>String</td> 1288 * <td>{@link #SOURCE_ID}</td> 1289 * <td>read/write</td> 1290 * <td>String that uniquely identifies this row to its source account. 1291 * Typically it is set at the time the raw contact is inserted and never 1292 * changed afterwards. The one notable exception is a new raw contact: it 1293 * will have an account name and type, but no source id. This should 1294 * indicated to the sync adapter that a new contact needs to be created 1295 * server-side and its ID stored in the corresponding SOURCE_ID field on 1296 * the phone. 1297 * </td> 1298 * </tr> 1299 * <tr> 1300 * <td>int</td> 1301 * <td>{@link #VERSION}</td> 1302 * <td>read-only</td> 1303 * <td>Version number that is updated whenever this row or its related data 1304 * changes. This field can be used for optimistic locking of a raw contact. 1305 * </td> 1306 * </tr> 1307 * <tr> 1308 * <td>int</td> 1309 * <td>{@link #DIRTY}</td> 1310 * <td>read/write</td> 1311 * <td>Flag indicating that {@link #VERSION} has changed, and this row needs 1312 * to be synchronized by its owning account. The value is set to "1" automatically 1313 * whenever the raw contact changes, unless the URI has the 1314 * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter specified. 1315 * The sync adapter should always supply this query parameter to prevent 1316 * unnecessary synchronization: user changes some data on the server, 1317 * the sync adapter updates the contact on the phone (without the 1318 * CALLER_IS_SYNCADAPTER flag) flag, which sets the DIRTY flag, 1319 * which triggers a sync to bring the changes to the server. 1320 * </td> 1321 * </tr> 1322 * <tr> 1323 * <td>String</td> 1324 * <td>{@link #SYNC1}</td> 1325 * <td>read/write</td> 1326 * <td>Generic column for use by sync adapters. Content provider 1327 * stores this information on behalf of the sync adapter but does not 1328 * interpret it in any way. 1329 * </td> 1330 * </tr> 1331 * <tr> 1332 * <td>String</td> 1333 * <td>{@link #SYNC2}</td> 1334 * <td>read/write</td> 1335 * <td>Generic column for use by sync adapters. 1336 * </td> 1337 * </tr> 1338 * <tr> 1339 * <td>String</td> 1340 * <td>{@link #SYNC3}</td> 1341 * <td>read/write</td> 1342 * <td>Generic column for use by sync adapters. 1343 * </td> 1344 * </tr> 1345 * <tr> 1346 * <td>String</td> 1347 * <td>{@link #SYNC4}</td> 1348 * <td>read/write</td> 1349 * <td>Generic column for use by sync adapters. 1350 * </td> 1351 * </tr> 1352 * </table> 1353 */ 1354 public static final class RawContacts implements BaseColumns, RawContactsColumns, 1355 ContactOptionsColumns, ContactNameColumns, SyncColumns { 1356 /** 1357 * This utility class cannot be instantiated 1358 */ 1359 private RawContacts() { 1360 } 1361 1362 /** 1363 * The content:// style URI for this table 1364 */ 1365 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "raw_contacts"); 1366 1367 /** 1368 * The MIME type of {@link #CONTENT_URI} providing a directory of 1369 * people. 1370 */ 1371 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/raw_contact"; 1372 1373 /** 1374 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 1375 * person. 1376 */ 1377 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/raw_contact"; 1378 1379 /** 1380 * Aggregation mode: aggregate asynchronously. 1381 */ 1382 public static final int AGGREGATION_MODE_DEFAULT = 0; 1383 1384 /** 1385 * Aggregation mode: aggregate at the time the raw contact is inserted/updated. 1386 * TODO: deprecate. Aggregation is now synchronous, this value is a no-op 1387 */ 1388 public static final int AGGREGATION_MODE_IMMEDIATE = 1; 1389 1390 /** 1391 * If {@link #AGGREGATION_MODE} is {@link #AGGREGATION_MODE_SUSPENDED}, changes 1392 * to the raw contact do not cause its aggregation to be revisited. Note that changing 1393 * {@link #AGGREGATION_MODE} from {@link #AGGREGATION_MODE_SUSPENDED} to 1394 * {@link #AGGREGATION_MODE_DEFAULT} does not trigger an aggregation pass. Any subsequent 1395 * change to the raw contact's data will. 1396 */ 1397 public static final int AGGREGATION_MODE_SUSPENDED = 2; 1398 1399 /** 1400 * Aggregation mode: never aggregate this raw contact (note that the raw contact will not 1401 * have a corresponding Aggregate and therefore will not be included in Aggregates 1402 * query results.) 1403 */ 1404 public static final int AGGREGATION_MODE_DISABLED = 3; 1405 1406 /** 1407 * Build a {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} 1408 * style {@link Uri} for the parent {@link android.provider.ContactsContract.Contacts} 1409 * entry of the given {@link RawContacts} entry. 1410 */ 1411 public static Uri getContactLookupUri(ContentResolver resolver, Uri rawContactUri) { 1412 // TODO: use a lighter query by joining rawcontacts with contacts in provider 1413 final Uri dataUri = Uri.withAppendedPath(rawContactUri, Data.CONTENT_DIRECTORY); 1414 final Cursor cursor = resolver.query(dataUri, new String[] { 1415 RawContacts.CONTACT_ID, Contacts.LOOKUP_KEY 1416 }, null, null, null); 1417 1418 Uri lookupUri = null; 1419 try { 1420 if (cursor != null && cursor.moveToFirst()) { 1421 final long contactId = cursor.getLong(0); 1422 final String lookupKey = cursor.getString(1); 1423 return Contacts.getLookupUri(contactId, lookupKey); 1424 } 1425 } finally { 1426 if (cursor != null) cursor.close(); 1427 } 1428 return lookupUri; 1429 } 1430 1431 /** 1432 * A sub-directory of a single raw contact that contains all of their 1433 * {@link ContactsContract.Data} rows. To access this directory 1434 * append {@link Data#CONTENT_DIRECTORY} to the contact URI. 1435 */ 1436 public static final class Data implements BaseColumns, DataColumns { 1437 /** 1438 * no public constructor since this is a utility class 1439 */ 1440 private Data() { 1441 } 1442 1443 /** 1444 * The directory twig for this sub-table 1445 */ 1446 public static final String CONTENT_DIRECTORY = "data"; 1447 } 1448 1449 /** 1450 * <p> 1451 * A sub-directory of a single raw contact that contains all of their 1452 * {@link ContactsContract.Data} rows. To access this directory append 1453 * {@link #CONTENT_DIRECTORY} to the contact URI. See 1454 * {@link RawContactsEntity} for a stand-alone table containing the same 1455 * data. 1456 * </p> 1457 * <p> 1458 * The Entity directory is similar to the {@link RawContacts.Data} 1459 * directory but with two important differences: 1460 * <ul> 1461 * <li>Entity has different ID fields: {@link #_ID} for the raw contact 1462 * and {@link #DATA_ID} for the data rows.</li> 1463 * <li>Entity always contains at least one row, even if there are no 1464 * actual data rows. In this case the {@link #DATA_ID} field will be 1465 * null.</li> 1466 * </ul> 1467 * Using Entity should preferred to using two separate queries: 1468 * RawContacts followed by Data. The reason is that Entity reads all 1469 * data for a raw contact in one transaction, so there is no possibility 1470 * of the data changing between the two queries. 1471 */ 1472 public static final class Entity implements BaseColumns, DataColumns { 1473 /** 1474 * no public constructor since this is a utility class 1475 */ 1476 private Entity() { 1477 } 1478 1479 /** 1480 * The directory twig for this sub-table 1481 */ 1482 public static final String CONTENT_DIRECTORY = "entity"; 1483 1484 /** 1485 * The ID of the data column. The value will be null if this raw contact has no 1486 * data rows. 1487 * <P>Type: INTEGER</P> 1488 */ 1489 public static final String DATA_ID = "data_id"; 1490 } 1491 1492 public static EntityIterator newEntityIterator(Cursor cursor) { 1493 return new EntityIteratorImpl(cursor); 1494 } 1495 1496 private static class EntityIteratorImpl extends CursorEntityIterator { 1497 private static final String[] DATA_KEYS = new String[]{ 1498 Data.DATA1, 1499 Data.DATA2, 1500 Data.DATA3, 1501 Data.DATA4, 1502 Data.DATA5, 1503 Data.DATA6, 1504 Data.DATA7, 1505 Data.DATA8, 1506 Data.DATA9, 1507 Data.DATA10, 1508 Data.DATA11, 1509 Data.DATA12, 1510 Data.DATA13, 1511 Data.DATA14, 1512 Data.DATA15, 1513 Data.SYNC1, 1514 Data.SYNC2, 1515 Data.SYNC3, 1516 Data.SYNC4}; 1517 1518 public EntityIteratorImpl(Cursor cursor) { 1519 super(cursor); 1520 } 1521 1522 public android.content.Entity getEntityAndIncrementCursor(Cursor cursor) 1523 throws RemoteException { 1524 final int columnRawContactId = cursor.getColumnIndexOrThrow(RawContacts._ID); 1525 final long rawContactId = cursor.getLong(columnRawContactId); 1526 1527 // we expect the cursor is already at the row we need to read from 1528 ContentValues cv = new ContentValues(); 1529 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, ACCOUNT_NAME); 1530 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, ACCOUNT_TYPE); 1531 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, _ID); 1532 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, DIRTY); 1533 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, VERSION); 1534 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SOURCE_ID); 1535 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC1); 1536 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC2); 1537 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC3); 1538 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, SYNC4); 1539 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, DELETED); 1540 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, CONTACT_ID); 1541 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, STARRED); 1542 DatabaseUtils.cursorIntToContentValuesIfPresent(cursor, cv, IS_RESTRICTED); 1543 android.content.Entity contact = new android.content.Entity(cv); 1544 1545 // read data rows until the contact id changes 1546 do { 1547 if (rawContactId != cursor.getLong(columnRawContactId)) { 1548 break; 1549 } 1550 // add the data to to the contact 1551 cv = new ContentValues(); 1552 cv.put(Data._ID, cursor.getLong(cursor.getColumnIndexOrThrow(Entity.DATA_ID))); 1553 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, 1554 Data.RES_PACKAGE); 1555 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, Data.MIMETYPE); 1556 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, Data.IS_PRIMARY); 1557 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, 1558 Data.IS_SUPER_PRIMARY); 1559 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, cv, Data.DATA_VERSION); 1560 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, 1561 CommonDataKinds.GroupMembership.GROUP_SOURCE_ID); 1562 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, cv, 1563 Data.DATA_VERSION); 1564 for (String key : DATA_KEYS) { 1565 final int columnIndex = cursor.getColumnIndexOrThrow(key); 1566 if (cursor.isNull(columnIndex)) { 1567 // don't put anything 1568 } else { 1569 try { 1570 cv.put(key, cursor.getString(columnIndex)); 1571 } catch (SQLiteException e) { 1572 cv.put(key, cursor.getBlob(columnIndex)); 1573 } 1574 } 1575 // TODO: go back to this version of the code when bug 1576 // http://b/issue?id=2306370 is fixed. 1577// if (cursor.isNull(columnIndex)) { 1578// // don't put anything 1579// } else if (cursor.isLong(columnIndex)) { 1580// values.put(key, cursor.getLong(columnIndex)); 1581// } else if (cursor.isFloat(columnIndex)) { 1582// values.put(key, cursor.getFloat(columnIndex)); 1583// } else if (cursor.isString(columnIndex)) { 1584// values.put(key, cursor.getString(columnIndex)); 1585// } else if (cursor.isBlob(columnIndex)) { 1586// values.put(key, cursor.getBlob(columnIndex)); 1587// } 1588 } 1589 contact.addSubValue(ContactsContract.Data.CONTENT_URI, cv); 1590 } while (cursor.moveToNext()); 1591 1592 return contact; 1593 } 1594 1595 } 1596 } 1597 1598 /** 1599 * Social status update columns. 1600 * 1601 * @see StatusUpdates 1602 * @see ContactsContract.Data 1603 */ 1604 protected interface StatusColumns { 1605 /** 1606 * Contact's latest presence level. 1607 * <P>Type: INTEGER (one of the values below)</P> 1608 */ 1609 public static final String PRESENCE = "mode"; 1610 1611 /** 1612 * @deprecated use {@link #PRESENCE} 1613 */ 1614 @Deprecated 1615 public static final String PRESENCE_STATUS = PRESENCE; 1616 1617 /* 1618 * Presence Status definition 1619 */ 1620 int OFFLINE = 0; 1621 int INVISIBLE = 1; 1622 int AWAY = 2; 1623 int IDLE = 3; 1624 int DO_NOT_DISTURB = 4; 1625 int AVAILABLE = 5; 1626 1627 /** 1628 * Contact latest status update. 1629 * <p>Type: TEXT</p> 1630 */ 1631 public static final String STATUS = "status"; 1632 1633 /** 1634 * @deprecated use {@link #STATUS} 1635 */ 1636 public static final String PRESENCE_CUSTOM_STATUS = STATUS; 1637 1638 /** 1639 * The absolute time in milliseconds when the latest status was inserted/updated. 1640 * <p>Type: NUMBER</p> 1641 */ 1642 public static final String STATUS_TIMESTAMP = "status_ts"; 1643 1644 /** 1645 * The package containing resources for this status: label and icon. 1646 * <p>Type: NUMBER</p> 1647 */ 1648 public static final String STATUS_RES_PACKAGE = "status_res_package"; 1649 1650 /** 1651 * The resource ID of the label describing the source of the status update, e.g. "Google 1652 * Talk". This resource should be scoped by the {@link #STATUS_RES_PACKAGE}. 1653 * <p>Type: NUMBER</p> 1654 */ 1655 public static final String STATUS_LABEL = "status_label"; 1656 1657 /** 1658 * The resource ID of the icon for the source of the status update. 1659 * This resource should be scoped by the {@link #STATUS_RES_PACKAGE}. 1660 * <p>Type: NUMBER</p> 1661 */ 1662 public static final String STATUS_ICON = "status_icon"; 1663 } 1664 1665 /** 1666 * Columns in the Data table. 1667 * 1668 * @see ContactsContract.Data 1669 */ 1670 protected interface DataColumns { 1671 /** 1672 * The package name to use when creating {@link Resources} objects for 1673 * this data row. This value is only designed for use when building user 1674 * interfaces, and should not be used to infer the owner. 1675 * 1676 * @hide 1677 */ 1678 public static final String RES_PACKAGE = "res_package"; 1679 1680 /** 1681 * The MIME type of the item represented by this row. 1682 */ 1683 public static final String MIMETYPE = "mimetype"; 1684 1685 /** 1686 * A reference to the {@link RawContacts#_ID} 1687 * that this data belongs to. 1688 */ 1689 public static final String RAW_CONTACT_ID = "raw_contact_id"; 1690 1691 /** 1692 * Whether this is the primary entry of its kind for the raw contact it belongs to 1693 * <P>Type: INTEGER (if set, non-0 means true)</P> 1694 */ 1695 public static final String IS_PRIMARY = "is_primary"; 1696 1697 /** 1698 * Whether this is the primary entry of its kind for the aggregate 1699 * contact it belongs to. Any data record that is "super primary" must 1700 * also be "primary". 1701 * <P>Type: INTEGER (if set, non-0 means true)</P> 1702 */ 1703 public static final String IS_SUPER_PRIMARY = "is_super_primary"; 1704 1705 /** 1706 * The version of this data record. This is a read-only value. The data column is 1707 * guaranteed to not change without the version going up. This value is monotonically 1708 * increasing. 1709 * <P>Type: INTEGER</P> 1710 */ 1711 public static final String DATA_VERSION = "data_version"; 1712 1713 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1714 public static final String DATA1 = "data1"; 1715 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1716 public static final String DATA2 = "data2"; 1717 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1718 public static final String DATA3 = "data3"; 1719 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1720 public static final String DATA4 = "data4"; 1721 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1722 public static final String DATA5 = "data5"; 1723 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1724 public static final String DATA6 = "data6"; 1725 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1726 public static final String DATA7 = "data7"; 1727 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1728 public static final String DATA8 = "data8"; 1729 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1730 public static final String DATA9 = "data9"; 1731 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1732 public static final String DATA10 = "data10"; 1733 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1734 public static final String DATA11 = "data11"; 1735 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1736 public static final String DATA12 = "data12"; 1737 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1738 public static final String DATA13 = "data13"; 1739 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1740 public static final String DATA14 = "data14"; 1741 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 1742 public static final String DATA15 = "data15"; 1743 1744 /** Generic column for use by sync adapters. */ 1745 public static final String SYNC1 = "data_sync1"; 1746 /** Generic column for use by sync adapters. */ 1747 public static final String SYNC2 = "data_sync2"; 1748 /** Generic column for use by sync adapters. */ 1749 public static final String SYNC3 = "data_sync3"; 1750 /** Generic column for use by sync adapters. */ 1751 public static final String SYNC4 = "data_sync4"; 1752 } 1753 1754 /** 1755 * Combines all columns returned by {@link ContactsContract.Data} table queries. 1756 * 1757 * @see ContactsContract.Data 1758 */ 1759 protected interface DataColumnsWithJoins extends BaseColumns, DataColumns, StatusColumns, 1760 RawContactsColumns, ContactsColumns, ContactOptionsColumns, ContactStatusColumns { 1761 1762 } 1763 1764 /** 1765 * <p> 1766 * Constants for the data table, which contains data points tied to a raw 1767 * contact. For example, a phone number or email address. 1768 * </p> 1769 * <h3>Data kinds</h3> 1770 * <p> 1771 * Data is a generic table that can hold all kinds of data. Sync adapters 1772 * and applications can introduce their own data kinds. The kind of data 1773 * stored in a particular row is determined by the mime type in the row. 1774 * Fields from {@link #DATA1} through {@link #DATA15} are generic columns 1775 * whose specific use is determined by the kind of data stored in the row. 1776 * For example, if the data kind is 1777 * {@link CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE}, then DATA1 stores the 1778 * phone number, but if the data kind is 1779 * {@link CommonDataKinds.Email Email.CONTENT_ITEM_TYPE}, then DATA1 stores the 1780 * email address. 1781 * </p> 1782 * <p> 1783 * ContactsContract defines a small number of common data kinds, e.g. 1784 * {@link CommonDataKinds.Phone}, {@link CommonDataKinds.Email} etc. As a 1785 * convenience, these classes define data kind specific aliases for DATA1 etc. 1786 * For example, {@link CommonDataKinds.Phone Phone.NUMBER} is the same as 1787 * {@link ContactsContract.Data Data.DATA1}. 1788 * </p> 1789 * <p> 1790 * {@link #DATA1} is an indexed column and should be used for the data element that is 1791 * expected to be most frequently used in query selections. For example, in the 1792 * case of a row representing email addresses {@link #DATA1} should probably 1793 * be used for the email address itself, while {@link #DATA2} etc can be 1794 * used for auxiliary information like type of email address. 1795 * <p> 1796 * <p> 1797 * By convention, {@link #DATA15} is used for storing BLOBs (binary data). 1798 * </p> 1799 * <p> 1800 * Typically you should refrain from introducing new kinds of data for 3rd 1801 * party account types. For example, if you add a data row for 1802 * "favorite song" to a raw contact owned by a Google account, it will not 1803 * get synced to the server, because the Google sync adapter does not know 1804 * how to handle this data kind. Thus new data kinds are typically 1805 * introduced along with new account types, i.e. new sync adapters. 1806 * </p> 1807 * <h3>Batch operations</h3> 1808 * <p> 1809 * Data rows can be inserted/updated/deleted using the traditional 1810 * {@link ContentResolver#insert}, {@link ContentResolver#update} and 1811 * {@link ContentResolver#delete} methods, however the newer mechanism based 1812 * on a batch of {@link ContentProviderOperation} will prove to be a better 1813 * choice in almost all cases. All operations in a batch are executed in a 1814 * single transaction, which ensures that the phone-side and server-side 1815 * state of a raw contact are always consistent. Also, the batch-based 1816 * approach is far more efficient: not only are the database operations 1817 * faster when executed in a single transaction, but also sending a batch of 1818 * commands to the content provider saves a lot of time on context switching 1819 * between your process and the process in which the content provider runs. 1820 * </p> 1821 * <p> 1822 * The flip side of using batched operations is that a large batch may lock 1823 * up the database for a long time preventing other applications from 1824 * accessing data and potentially causing ANRs ("Application Not Responding" 1825 * dialogs.) 1826 * </p> 1827 * <p> 1828 * To avoid such lockups of the database, make sure to insert "yield points" 1829 * in the batch. A yield point indicates to the content provider that before 1830 * executing the next operation it can commit the changes that have already 1831 * been made, yield to other requests, open another transaction and continue 1832 * processing operations. A yield point will not automatically commit the 1833 * transaction, but only if there is another request waiting on the 1834 * database. Normally a sync adapter should insert a yield point at the 1835 * beginning of each raw contact operation sequence in the batch. See 1836 * {@link ContentProviderOperation.Builder#withYieldAllowed(boolean)}. 1837 * </p> 1838 * <h3>Operations</h3> 1839 * <dl> 1840 * <dt><b>Insert</b></dt> 1841 * <dd> 1842 * <p> 1843 * An individual data row can be inserted using the traditional 1844 * {@link ContentResolver#insert(Uri, ContentValues)} method. Multiple rows 1845 * should always be inserted as a batch. 1846 * </p> 1847 * <p> 1848 * An example of a traditional insert: 1849 * <pre> 1850 * ContentValues values = new ContentValues(); 1851 * values.put(Data.RAW_CONTACT_ID, rawContactId); 1852 * values.put(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE); 1853 * values.put(Phone.NUMBER, "1-800-GOOG-411"); 1854 * values.put(Phone.TYPE, Phone.TYPE_CUSTOM); 1855 * values.put(Phone.LABEL, "free directory assistance"); 1856 * Uri dataUri = getContentResolver().insert(Data.CONTENT_URI, values); 1857 * </pre> 1858 * <p> 1859 * The same done using ContentProviderOperations: 1860 * <pre> 1861 * ArrayList<ContentProviderOperation> ops = Lists.newArrayList(); 1862 * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI) 1863 * .withValue(Data.RAW_CONTACT_ID, rawContactId) 1864 * .withValue(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE) 1865 * .withValue(Phone.NUMBER, "1-800-GOOG-411") 1866 * .withValue(Phone.TYPE, Phone.TYPE_CUSTOM) 1867 * .withValue(Phone.LABEL, "free directory assistance") 1868 * .build()); 1869 * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); 1870 * </pre> 1871 * </p> 1872 * <dt><b>Update</b></dt> 1873 * <dd> 1874 * <p> 1875 * Just as with insert, update can be done incrementally or as a batch, 1876 * the batch mode being the preferred method: 1877 * <pre> 1878 * ArrayList<ContentProviderOperation> ops = Lists.newArrayList(); 1879 * ops.add(ContentProviderOperation.newUpdate(Data.CONTENT_URI) 1880 * .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)}) 1881 * .withValue(Email.DATA, "somebody@android.com") 1882 * .build()); 1883 * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); 1884 * </pre> 1885 * </p> 1886 * </dd> 1887 * <dt><b>Delete</b></dt> 1888 * <dd> 1889 * <p> 1890 * Just as with insert and update, deletion can be done either using the 1891 * {@link ContentResolver#delete} method or using a ContentProviderOperation: 1892 * <pre> 1893 * ArrayList<ContentProviderOperation> ops = Lists.newArrayList(); 1894 * ops.add(ContentProviderOperation.newDelete(Data.CONTENT_URI) 1895 * .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)}) 1896 * .build()); 1897 * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); 1898 * </pre> 1899 * </p> 1900 * </dd> 1901 * <dt><b>Query</b></dt> 1902 * <dd> 1903 * <p> 1904 * <dl> 1905 * <dt>Finding all Data of a given type for a given contact</dt> 1906 * <dd> 1907 * <pre> 1908 * Cursor c = getContentResolver().query(Data.CONTENT_URI, 1909 * new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL}, 1910 * Data.CONTACT_ID + "=?" + " AND " 1911 * + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'", 1912 * new String[] {String.valueOf(contactId)}, null); 1913 * </pre> 1914 * </p> 1915 * <p> 1916 * </dd> 1917 * <dt>Finding all Data of a given type for a given raw contact</dt> 1918 * <dd> 1919 * <pre> 1920 * Cursor c = getContentResolver().query(Data.CONTENT_URI, 1921 * new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL}, 1922 * Data.RAW_CONTACT_ID + "=?" + " AND " 1923 * + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'", 1924 * new String[] {String.valueOf(rawContactId)}, null); 1925 * </pre> 1926 * </dd> 1927 * <dt>Finding all Data for a given raw contact</dt> 1928 * <dd> 1929 * Most sync adapters will want to read all data rows for a raw contact 1930 * along with the raw contact itself. For that you should use the 1931 * {@link RawContactsEntity}. See also {@link RawContacts}. 1932 * </dd> 1933 * </dl> 1934 * </p> 1935 * </dd> 1936 * </dl> 1937 * <h2>Columns</h2> 1938 * <table class="jd-sumtable"> 1939 * <tr> 1940 * <th colspan='4'>Data</th> 1941 * </tr> 1942 * <tr> 1943 * <td style="width: 7em;">long</td> 1944 * <td style="width: 20em;">{@link #_ID}</td> 1945 * <td style="width: 5em;">read-only</td> 1946 * <td>Row ID. Sync adapter should try to preserve row IDs during updates. In other words, 1947 * it would be a bad idea to delete and reinsert a data rows. A sync adapter should 1948 * always do an update instead.</td> 1949 * </tr> 1950 * <tr> 1951 * <td>String</td> 1952 * <td>{@link #MIMETYPE}</td> 1953 * <td>read/write-once</td> 1954 * <td> 1955 * <p>The MIME type of the item represented by this row. Examples of common 1956 * MIME types are: 1957 * <ul> 1958 * <li>{@link CommonDataKinds.StructuredName StructuredName.CONTENT_ITEM_TYPE}</li> 1959 * <li>{@link CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE}</li> 1960 * <li>{@link CommonDataKinds.Email Email.CONTENT_ITEM_TYPE}</li> 1961 * <li>{@link CommonDataKinds.Photo Photo.CONTENT_ITEM_TYPE}</li> 1962 * <li>{@link CommonDataKinds.Organization Organization.CONTENT_ITEM_TYPE}</li> 1963 * <li>{@link CommonDataKinds.Im Im.CONTENT_ITEM_TYPE}</li> 1964 * <li>{@link CommonDataKinds.Nickname Nickname.CONTENT_ITEM_TYPE}</li> 1965 * <li>{@link CommonDataKinds.Note Note.CONTENT_ITEM_TYPE}</li> 1966 * <li>{@link CommonDataKinds.StructuredPostal StructuredPostal.CONTENT_ITEM_TYPE}</li> 1967 * <li>{@link CommonDataKinds.GroupMembership GroupMembership.CONTENT_ITEM_TYPE}</li> 1968 * <li>{@link CommonDataKinds.Website Website.CONTENT_ITEM_TYPE}</li> 1969 * <li>{@link CommonDataKinds.Event Event.CONTENT_ITEM_TYPE}</li> 1970 * <li>{@link CommonDataKinds.Relation Relation.CONTENT_ITEM_TYPE}</li> 1971 * </ul> 1972 * </p> 1973 * </td> 1974 * </tr> 1975 * <tr> 1976 * <td>long</td> 1977 * <td>{@link #RAW_CONTACT_ID}</td> 1978 * <td>read/write-once</td> 1979 * <td>A reference to the {@link RawContacts#_ID} that this data belongs to.</td> 1980 * </tr> 1981 * <tr> 1982 * <td>long</td> 1983 * <td>{@link #CONTACT_ID}</td> 1984 * <td>read-only</td> 1985 * <td>A reference to the {@link ContactsContract.Contacts#_ID} that this data row belongs 1986 * to. It is obtained through a join with RawContacts.</td> 1987 * </tr> 1988 * <tr> 1989 * <td>int</td> 1990 * <td>{@link #IS_PRIMARY}</td> 1991 * <td>read/write</td> 1992 * <td>Whether this is the primary entry of its kind for the raw contact it belongs to. 1993 * "1" if true, "0" if false.</td> 1994 * </tr> 1995 * <tr> 1996 * <td>int</td> 1997 * <td>{@link #IS_SUPER_PRIMARY}</td> 1998 * <td>read/write</td> 1999 * <td>Whether this is the primary entry of its kind for the aggregate 2000 * contact it belongs to. Any data record that is "super primary" must 2001 * also be "primary".</td> 2002 * </tr> 2003 * <tr> 2004 * <td>int</td> 2005 * <td>{@link #DATA_VERSION}</td> 2006 * <td>read-only</td> 2007 * <td>The version of this data record. Whenever the data row changes 2008 * the version goes up. This value is monotonically increasing.</td> 2009 * </tr> 2010 * <tr> 2011 * <td>Any type</td> 2012 * <td> 2013 * {@link #DATA1}<br> 2014 * {@link #DATA2}<br> 2015 * {@link #DATA3}<br> 2016 * {@link #DATA4}<br> 2017 * {@link #DATA5}<br> 2018 * {@link #DATA6}<br> 2019 * {@link #DATA7}<br> 2020 * {@link #DATA8}<br> 2021 * {@link #DATA9}<br> 2022 * {@link #DATA10}<br> 2023 * {@link #DATA11}<br> 2024 * {@link #DATA12}<br> 2025 * {@link #DATA13}<br> 2026 * {@link #DATA14}<br> 2027 * {@link #DATA15} 2028 * </td> 2029 * <td>read/write</td> 2030 * <td>Generic data columns, the meaning is {@link #MIMETYPE} specific.</td> 2031 * </tr> 2032 * <tr> 2033 * <td>Any type</td> 2034 * <td> 2035 * {@link #SYNC1}<br> 2036 * {@link #SYNC2}<br> 2037 * {@link #SYNC3}<br> 2038 * {@link #SYNC4} 2039 * </td> 2040 * <td>read/write</td> 2041 * <td>Generic columns for use by sync adapters. For example, a Photo row 2042 * may store the image URL in SYNC1, a status (not loaded, loading, loaded, error) 2043 * in SYNC2, server-side version number in SYNC3 and error code in SYNC4.</td> 2044 * </tr> 2045 * </table> 2046 * 2047 * <table class="jd-sumtable"> 2048 * <tr> 2049 * <th colspan='4'>Join with {@link StatusUpdates}</th> 2050 * </tr> 2051 * <tr> 2052 * <td style="width: 7em;">int</td> 2053 * <td style="width: 20em;">{@link #PRESENCE}</td> 2054 * <td style="width: 5em;">read-only</td> 2055 * <td>IM presence status linked to this data row. Compare with 2056 * {@link #CONTACT_PRESENCE}, which contains the contact's presence across 2057 * all IM rows. See {@link StatusUpdates} for individual status definitions. 2058 * The provider may choose not to store this value 2059 * in persistent storage. The expectation is that presence status will be 2060 * updated on a regular basic. 2061 * </td> 2062 * </tr> 2063 * <tr> 2064 * <td>String</td> 2065 * <td>{@link #STATUS}</td> 2066 * <td>read-only</td> 2067 * <td>Latest status update linked with this data row.</td> 2068 * </tr> 2069 * <tr> 2070 * <td>long</td> 2071 * <td>{@link #STATUS_TIMESTAMP}</td> 2072 * <td>read-only</td> 2073 * <td>The absolute time in milliseconds when the latest status was 2074 * inserted/updated for this data row.</td> 2075 * </tr> 2076 * <tr> 2077 * <td>String</td> 2078 * <td>{@link #STATUS_RES_PACKAGE}</td> 2079 * <td>read-only</td> 2080 * <td>The package containing resources for this status: label and icon.</td> 2081 * </tr> 2082 * <tr> 2083 * <td>long</td> 2084 * <td>{@link #STATUS_LABEL}</td> 2085 * <td>read-only</td> 2086 * <td>The resource ID of the label describing the source of status update linked 2087 * to this data row. This resource is scoped by the {@link #STATUS_RES_PACKAGE}.</td> 2088 * </tr> 2089 * <tr> 2090 * <td>long</td> 2091 * <td>{@link #STATUS_ICON}</td> 2092 * <td>read-only</td> 2093 * <td>The resource ID of the icon for the source of the status update linked 2094 * to this data row. This resource is scoped by the {@link #STATUS_RES_PACKAGE}.</td> 2095 * </tr> 2096 * </table> 2097 * 2098 * <p> 2099 * Columns from the associated raw contact are also available through an 2100 * implicit join. 2101 * </p> 2102 * 2103 * <table class="jd-sumtable"> 2104 * <tr> 2105 * <th colspan='4'>Join with {@link RawContacts}</th> 2106 * </tr> 2107 * <tr> 2108 * <td style="width: 7em;">int</td> 2109 * <td style="width: 20em;">{@link #AGGREGATION_MODE}</td> 2110 * <td style="width: 5em;">read-only</td> 2111 * <td>See {@link RawContacts}.</td> 2112 * </tr> 2113 * <tr> 2114 * <td>int</td> 2115 * <td>{@link #DELETED}</td> 2116 * <td>read-only</td> 2117 * <td>See {@link RawContacts}.</td> 2118 * </tr> 2119 * </table> 2120 * 2121 * <p> 2122 * Columns from the associated aggregated contact are also available through an 2123 * implicit join. 2124 * </p> 2125 * 2126 * <table class="jd-sumtable"> 2127 * <tr> 2128 * <th colspan='4'>Join with {@link Contacts}</th> 2129 * </tr> 2130 * <tr> 2131 * <td style="width: 7em;">String</td> 2132 * <td style="width: 20em;">{@link #LOOKUP_KEY}</td> 2133 * <td style="width: 5em;">read-only</td> 2134 * <td>See {@link ContactsContract.Contacts}</td> 2135 * </tr> 2136 * <tr> 2137 * <td>String</td> 2138 * <td>{@link #DISPLAY_NAME}</td> 2139 * <td>read-only</td> 2140 * <td>See {@link ContactsContract.Contacts}</td> 2141 * </tr> 2142 * <tr> 2143 * <td>long</td> 2144 * <td>{@link #PHOTO_ID}</td> 2145 * <td>read-only</td> 2146 * <td>See {@link ContactsContract.Contacts}.</td> 2147 * </tr> 2148 * <tr> 2149 * <td>int</td> 2150 * <td>{@link #IN_VISIBLE_GROUP}</td> 2151 * <td>read-only</td> 2152 * <td>See {@link ContactsContract.Contacts}.</td> 2153 * </tr> 2154 * <tr> 2155 * <td>int</td> 2156 * <td>{@link #HAS_PHONE_NUMBER}</td> 2157 * <td>read-only</td> 2158 * <td>See {@link ContactsContract.Contacts}.</td> 2159 * </tr> 2160 * <tr> 2161 * <td>int</td> 2162 * <td>{@link #TIMES_CONTACTED}</td> 2163 * <td>read-only</td> 2164 * <td>See {@link ContactsContract.Contacts}.</td> 2165 * </tr> 2166 * <tr> 2167 * <td>long</td> 2168 * <td>{@link #LAST_TIME_CONTACTED}</td> 2169 * <td>read-only</td> 2170 * <td>See {@link ContactsContract.Contacts}.</td> 2171 * </tr> 2172 * <tr> 2173 * <td>int</td> 2174 * <td>{@link #STARRED}</td> 2175 * <td>read-only</td> 2176 * <td>See {@link ContactsContract.Contacts}.</td> 2177 * </tr> 2178 * <tr> 2179 * <td>String</td> 2180 * <td>{@link #CUSTOM_RINGTONE}</td> 2181 * <td>read-only</td> 2182 * <td>See {@link ContactsContract.Contacts}.</td> 2183 * </tr> 2184 * <tr> 2185 * <td>int</td> 2186 * <td>{@link #SEND_TO_VOICEMAIL}</td> 2187 * <td>read-only</td> 2188 * <td>See {@link ContactsContract.Contacts}.</td> 2189 * </tr> 2190 * <tr> 2191 * <td>int</td> 2192 * <td>{@link #CONTACT_PRESENCE}</td> 2193 * <td>read-only</td> 2194 * <td>See {@link ContactsContract.Contacts}.</td> 2195 * </tr> 2196 * <tr> 2197 * <td>String</td> 2198 * <td>{@link #CONTACT_STATUS}</td> 2199 * <td>read-only</td> 2200 * <td>See {@link ContactsContract.Contacts}.</td> 2201 * </tr> 2202 * <tr> 2203 * <td>long</td> 2204 * <td>{@link #CONTACT_STATUS_TIMESTAMP}</td> 2205 * <td>read-only</td> 2206 * <td>See {@link ContactsContract.Contacts}.</td> 2207 * </tr> 2208 * <tr> 2209 * <td>String</td> 2210 * <td>{@link #CONTACT_STATUS_RES_PACKAGE}</td> 2211 * <td>read-only</td> 2212 * <td>See {@link ContactsContract.Contacts}.</td> 2213 * </tr> 2214 * <tr> 2215 * <td>long</td> 2216 * <td>{@link #CONTACT_STATUS_LABEL}</td> 2217 * <td>read-only</td> 2218 * <td>See {@link ContactsContract.Contacts}.</td> 2219 * </tr> 2220 * <tr> 2221 * <td>long</td> 2222 * <td>{@link #CONTACT_STATUS_ICON}</td> 2223 * <td>read-only</td> 2224 * <td>See {@link ContactsContract.Contacts}.</td> 2225 * </tr> 2226 * </table> 2227 */ 2228 public final static class Data implements DataColumnsWithJoins { 2229 /** 2230 * This utility class cannot be instantiated 2231 */ 2232 private Data() {} 2233 2234 /** 2235 * The content:// style URI for this table 2236 */ 2237 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data"); 2238 2239 /** 2240 * The MIME type of {@link #CONTENT_URI} providing a directory of data. 2241 */ 2242 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data"; 2243 2244 /** 2245 * If {@link #FOR_EXPORT_ONLY} is explicitly set to "1", returned Cursor toward 2246 * Data.CONTENT_URI contains only exportable data. 2247 * 2248 * This flag is useful (currently) only for vCard exporter in Contacts app, which 2249 * needs to exclude "un-exportable" data from available data to export, while 2250 * Contacts app itself has priviledge to access all data including "un-exportable" 2251 * ones and providers return all of them regardless of the callers' intention. 2252 * <P>Type: INTEGER</p> 2253 * 2254 * @hide Maybe available only in Eclair and not really ready for public use. 2255 * TODO: remove, or implement this feature completely. As of now (Eclair), 2256 * we only use this flag in queryEntities(), not query(). 2257 */ 2258 public static final String FOR_EXPORT_ONLY = "for_export_only"; 2259 2260 /** 2261 * Build a {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} 2262 * style {@link Uri} for the parent {@link android.provider.ContactsContract.Contacts} 2263 * entry of the given {@link ContactsContract.Data} entry. 2264 */ 2265 public static Uri getContactLookupUri(ContentResolver resolver, Uri dataUri) { 2266 final Cursor cursor = resolver.query(dataUri, new String[] { 2267 RawContacts.CONTACT_ID, Contacts.LOOKUP_KEY 2268 }, null, null, null); 2269 2270 Uri lookupUri = null; 2271 try { 2272 if (cursor != null && cursor.moveToFirst()) { 2273 final long contactId = cursor.getLong(0); 2274 final String lookupKey = cursor.getString(1); 2275 return Contacts.getLookupUri(contactId, lookupKey); 2276 } 2277 } finally { 2278 if (cursor != null) cursor.close(); 2279 } 2280 return lookupUri; 2281 } 2282 } 2283 2284 /** 2285 * <p> 2286 * Constants for the raw contacts entities table, which can be though of as 2287 * an outer join of the raw_contacts table with the data table. It is a strictly 2288 * read-only table. 2289 * </p> 2290 * <p> 2291 * If a raw contact has data rows, the RawContactsEntity cursor will contain 2292 * a one row for each data row. If the raw contact has no data rows, the 2293 * cursor will still contain one row with the raw contact-level information 2294 * and nulls for data columns. 2295 * 2296 * <pre> 2297 * Uri entityUri = ContentUris.withAppendedId(RawContactsEntity.CONTENT_URI, rawContactId); 2298 * Cursor c = getContentResolver().query(entityUri, 2299 * new String[]{ 2300 * RawContactsEntity.SOURCE_ID, 2301 * RawContactsEntity.DATA_ID, 2302 * RawContactsEntity.MIMETYPE, 2303 * RawContactsEntity.DATA1 2304 * }, null, null, null); 2305 * try { 2306 * while (c.moveToNext()) { 2307 * String sourceId = c.getString(0); 2308 * if (!c.isNull(1)) { 2309 * String mimeType = c.getString(2); 2310 * String data = c.getString(3); 2311 * ... 2312 * } 2313 * } 2314 * } finally { 2315 * c.close(); 2316 * } 2317 * </pre> 2318 * 2319 * <h3>Columns</h3> 2320 * RawContactsEntity has a combination of RawContact and Data columns. 2321 * 2322 * <table class="jd-sumtable"> 2323 * <tr> 2324 * <th colspan='4'>RawContacts</th> 2325 * </tr> 2326 * <tr> 2327 * <td style="width: 7em;">long</td> 2328 * <td style="width: 20em;">{@link #_ID}</td> 2329 * <td style="width: 5em;">read-only</td> 2330 * <td>Raw contact row ID. See {@link RawContacts}.</td> 2331 * </tr> 2332 * <tr> 2333 * <td>long</td> 2334 * <td>{@link #CONTACT_ID}</td> 2335 * <td>read-only</td> 2336 * <td>See {@link RawContacts}.</td> 2337 * </tr> 2338 * <tr> 2339 * <td>int</td> 2340 * <td>{@link #AGGREGATION_MODE}</td> 2341 * <td>read-only</td> 2342 * <td>See {@link RawContacts}.</td> 2343 * </tr> 2344 * <tr> 2345 * <td>int</td> 2346 * <td>{@link #DELETED}</td> 2347 * <td>read-only</td> 2348 * <td>See {@link RawContacts}.</td> 2349 * </tr> 2350 * </table> 2351 * 2352 * <table class="jd-sumtable"> 2353 * <tr> 2354 * <th colspan='4'>Data</th> 2355 * </tr> 2356 * <tr> 2357 * <td style="width: 7em;">long</td> 2358 * <td style="width: 20em;">{@link #DATA_ID}</td> 2359 * <td style="width: 5em;">read-only</td> 2360 * <td>Data row ID. It will be null if the raw contact has no data rows.</td> 2361 * </tr> 2362 * <tr> 2363 * <td>String</td> 2364 * <td>{@link #MIMETYPE}</td> 2365 * <td>read-only</td> 2366 * <td>See {@link ContactsContract.Data}.</td> 2367 * </tr> 2368 * <tr> 2369 * <td>int</td> 2370 * <td>{@link #IS_PRIMARY}</td> 2371 * <td>read-only</td> 2372 * <td>See {@link ContactsContract.Data}.</td> 2373 * </tr> 2374 * <tr> 2375 * <td>int</td> 2376 * <td>{@link #IS_SUPER_PRIMARY}</td> 2377 * <td>read-only</td> 2378 * <td>See {@link ContactsContract.Data}.</td> 2379 * </tr> 2380 * <tr> 2381 * <td>int</td> 2382 * <td>{@link #DATA_VERSION}</td> 2383 * <td>read-only</td> 2384 * <td>See {@link ContactsContract.Data}.</td> 2385 * </tr> 2386 * <tr> 2387 * <td>Any type</td> 2388 * <td> 2389 * {@link #DATA1}<br> 2390 * {@link #DATA2}<br> 2391 * {@link #DATA3}<br> 2392 * {@link #DATA4}<br> 2393 * {@link #DATA5}<br> 2394 * {@link #DATA6}<br> 2395 * {@link #DATA7}<br> 2396 * {@link #DATA8}<br> 2397 * {@link #DATA9}<br> 2398 * {@link #DATA10}<br> 2399 * {@link #DATA11}<br> 2400 * {@link #DATA12}<br> 2401 * {@link #DATA13}<br> 2402 * {@link #DATA14}<br> 2403 * {@link #DATA15} 2404 * </td> 2405 * <td>read-only</td> 2406 * <td>See {@link ContactsContract.Data}.</td> 2407 * </tr> 2408 * <tr> 2409 * <td>Any type</td> 2410 * <td> 2411 * {@link #SYNC1}<br> 2412 * {@link #SYNC2}<br> 2413 * {@link #SYNC3}<br> 2414 * {@link #SYNC4} 2415 * </td> 2416 * <td>read-only</td> 2417 * <td>See {@link ContactsContract.Data}.</td> 2418 * </tr> 2419 * </table> 2420 */ 2421 public final static class RawContactsEntity 2422 implements BaseColumns, DataColumns, RawContactsColumns { 2423 /** 2424 * This utility class cannot be instantiated 2425 */ 2426 private RawContactsEntity() {} 2427 2428 /** 2429 * The content:// style URI for this table 2430 */ 2431 public static final Uri CONTENT_URI = 2432 Uri.withAppendedPath(AUTHORITY_URI, "raw_contact_entities"); 2433 2434 /** 2435 * The MIME type of {@link #CONTENT_URI} providing a directory of raw contact entities. 2436 */ 2437 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/raw_contact_entity"; 2438 2439 /** 2440 * If {@link #FOR_EXPORT_ONLY} is explicitly set to "1", returned Cursor toward 2441 * Data.CONTENT_URI contains only exportable data. 2442 * 2443 * This flag is useful (currently) only for vCard exporter in Contacts app, which 2444 * needs to exclude "un-exportable" data from available data to export, while 2445 * Contacts app itself has priviledge to access all data including "un-expotable" 2446 * ones and providers return all of them regardless of the callers' intention. 2447 * <P>Type: INTEGER</p> 2448 * 2449 * @hide Maybe available only in Eclair and not really ready for public use. 2450 * TODO: remove, or implement this feature completely. As of now (Eclair), 2451 * we only use this flag in queryEntities(), not query(). 2452 */ 2453 public static final String FOR_EXPORT_ONLY = "for_export_only"; 2454 2455 /** 2456 * The ID of the data column. The value will be null if this raw contact has no data rows. 2457 * <P>Type: INTEGER</P> 2458 */ 2459 public static final String DATA_ID = "data_id"; 2460 } 2461 2462 /** 2463 * @see PhoneLookup 2464 */ 2465 protected interface PhoneLookupColumns { 2466 /** 2467 * The phone number as the user entered it. 2468 * <P>Type: TEXT</P> 2469 */ 2470 public static final String NUMBER = "number"; 2471 2472 /** 2473 * The type of phone number, for example Home or Work. 2474 * <P>Type: INTEGER</P> 2475 */ 2476 public static final String TYPE = "type"; 2477 2478 /** 2479 * The user defined label for the phone number. 2480 * <P>Type: TEXT</P> 2481 */ 2482 public static final String LABEL = "label"; 2483 } 2484 2485 /** 2486 * A table that represents the result of looking up a phone number, for 2487 * example for caller ID. To perform a lookup you must append the number you 2488 * want to find to {@link #CONTENT_FILTER_URI}. This query is highly 2489 * optimized. 2490 * <pre> 2491 * Uri uri = Uri.withAppendedPath(PhoneLookup.CONTENT_FILTER_URI, Uri.encode(phoneNumber)); 2492 * resolver.query(uri, new String[]{PhoneLookup.DISPLAY_NAME,... 2493 * </pre> 2494 * 2495 * <h3>Columns</h3> 2496 * 2497 * <table class="jd-sumtable"> 2498 * <tr> 2499 * <th colspan='4'>PhoneLookup</th> 2500 * </tr> 2501 * <tr> 2502 * <td>long</td> 2503 * <td>{@link #_ID}</td> 2504 * <td>read-only</td> 2505 * <td>Data row ID.</td> 2506 * </tr> 2507 * <tr> 2508 * <td>String</td> 2509 * <td>{@link #NUMBER}</td> 2510 * <td>read-only</td> 2511 * <td>Phone number.</td> 2512 * </tr> 2513 * <tr> 2514 * <td>String</td> 2515 * <td>{@link #TYPE}</td> 2516 * <td>read-only</td> 2517 * <td>Phone number type. See {@link CommonDataKinds.Phone}.</td> 2518 * </tr> 2519 * <tr> 2520 * <td>String</td> 2521 * <td>{@link #LABEL}</td> 2522 * <td>read-only</td> 2523 * <td>Custom label for the phone number. See {@link CommonDataKinds.Phone}.</td> 2524 * </tr> 2525 * </table> 2526 * <p> 2527 * Columns from the Contacts table are also available through a join. 2528 * </p> 2529 * <table class="jd-sumtable"> 2530 * <tr> 2531 * <th colspan='4'>Join with {@link Contacts}</th> 2532 * </tr> 2533 * <tr> 2534 * <td>String</td> 2535 * <td>{@link #LOOKUP_KEY}</td> 2536 * <td>read-only</td> 2537 * <td>See {@link ContactsContract.Contacts}</td> 2538 * </tr> 2539 * <tr> 2540 * <td>String</td> 2541 * <td>{@link #DISPLAY_NAME}</td> 2542 * <td>read-only</td> 2543 * <td>See {@link ContactsContract.Contacts}</td> 2544 * </tr> 2545 * <tr> 2546 * <td>long</td> 2547 * <td>{@link #PHOTO_ID}</td> 2548 * <td>read-only</td> 2549 * <td>See {@link ContactsContract.Contacts}.</td> 2550 * </tr> 2551 * <tr> 2552 * <td>int</td> 2553 * <td>{@link #IN_VISIBLE_GROUP}</td> 2554 * <td>read-only</td> 2555 * <td>See {@link ContactsContract.Contacts}.</td> 2556 * </tr> 2557 * <tr> 2558 * <td>int</td> 2559 * <td>{@link #HAS_PHONE_NUMBER}</td> 2560 * <td>read-only</td> 2561 * <td>See {@link ContactsContract.Contacts}.</td> 2562 * </tr> 2563 * <tr> 2564 * <td>int</td> 2565 * <td>{@link #TIMES_CONTACTED}</td> 2566 * <td>read-only</td> 2567 * <td>See {@link ContactsContract.Contacts}.</td> 2568 * </tr> 2569 * <tr> 2570 * <td>long</td> 2571 * <td>{@link #LAST_TIME_CONTACTED}</td> 2572 * <td>read-only</td> 2573 * <td>See {@link ContactsContract.Contacts}.</td> 2574 * </tr> 2575 * <tr> 2576 * <td>int</td> 2577 * <td>{@link #STARRED}</td> 2578 * <td>read-only</td> 2579 * <td>See {@link ContactsContract.Contacts}.</td> 2580 * </tr> 2581 * <tr> 2582 * <td>String</td> 2583 * <td>{@link #CUSTOM_RINGTONE}</td> 2584 * <td>read-only</td> 2585 * <td>See {@link ContactsContract.Contacts}.</td> 2586 * </tr> 2587 * <tr> 2588 * <td>int</td> 2589 * <td>{@link #SEND_TO_VOICEMAIL}</td> 2590 * <td>read-only</td> 2591 * <td>See {@link ContactsContract.Contacts}.</td> 2592 * </tr> 2593 * </table> 2594 */ 2595 public static final class PhoneLookup implements BaseColumns, PhoneLookupColumns, 2596 ContactsColumns, ContactOptionsColumns { 2597 /** 2598 * This utility class cannot be instantiated 2599 */ 2600 private PhoneLookup() {} 2601 2602 /** 2603 * The content:// style URI for this table. Append the phone number you want to lookup 2604 * to this URI and query it to perform a lookup. For example: 2605 * <pre> 2606 * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_URI, Uri.encode(phoneNumber)); 2607 * </pre> 2608 */ 2609 public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(AUTHORITY_URI, 2610 "phone_lookup"); 2611 } 2612 2613 /** 2614 * Additional data mixed in with {@link StatusColumns} to link 2615 * back to specific {@link ContactsContract.Data#_ID} entries. 2616 * 2617 * @see StatusUpdates 2618 */ 2619 protected interface PresenceColumns { 2620 2621 /** 2622 * Reference to the {@link Data#_ID} entry that owns this presence. 2623 * <P>Type: INTEGER</P> 2624 */ 2625 public static final String DATA_ID = "presence_data_id"; 2626 2627 /** 2628 * See {@link CommonDataKinds.Im} for a list of defined protocol constants. 2629 * <p>Type: NUMBER</p> 2630 */ 2631 public static final String PROTOCOL = "protocol"; 2632 2633 /** 2634 * Name of the custom protocol. Should be supplied along with the {@link #PROTOCOL} value 2635 * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}. Should be null or 2636 * omitted if {@link #PROTOCOL} value is not 2637 * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}. 2638 * 2639 * <p>Type: NUMBER</p> 2640 */ 2641 public static final String CUSTOM_PROTOCOL = "custom_protocol"; 2642 2643 /** 2644 * The IM handle the presence item is for. The handle is scoped to 2645 * {@link #PROTOCOL}. 2646 * <P>Type: TEXT</P> 2647 */ 2648 public static final String IM_HANDLE = "im_handle"; 2649 2650 /** 2651 * The IM account for the local user that the presence data came from. 2652 * <P>Type: TEXT</P> 2653 */ 2654 public static final String IM_ACCOUNT = "im_account"; 2655 } 2656 2657 /** 2658 * <p> 2659 * A status update is linked to a {@link ContactsContract.Data} row and captures 2660 * the user's latest status update via the corresponding source, e.g. 2661 * "Having lunch" via "Google Talk". 2662 * </p> 2663 * <p> 2664 * There are two ways a status update can be inserted: by explicitly linking 2665 * it to a Data row using {@link #DATA_ID} or indirectly linking it to a data row 2666 * using a combination of {@link #PROTOCOL} (or {@link #CUSTOM_PROTOCOL}) and 2667 * {@link #IM_HANDLE}. There is no difference between insert and update, you can use 2668 * either. 2669 * </p> 2670 * <p> 2671 * You cannot use {@link ContentResolver#update} to change a status, but 2672 * {@link ContentResolver#insert} will replace the latests status if it already 2673 * exists. 2674 * </p> 2675 * <p> 2676 * Use {@link ContentResolver#bulkInsert(Uri, ContentValues[])} to insert/update statuses 2677 * for multiple contacts at once. 2678 * </p> 2679 * 2680 * <h3>Columns</h3> 2681 * <table class="jd-sumtable"> 2682 * <tr> 2683 * <th colspan='4'>StatusUpdates</th> 2684 * </tr> 2685 * <tr> 2686 * <td>long</td> 2687 * <td>{@link #DATA_ID}</td> 2688 * <td>read/write</td> 2689 * <td>Reference to the {@link Data#_ID} entry that owns this presence. If this 2690 * field is <i>not</i> specified, the provider will attempt to find a data row 2691 * that matches the {@link #PROTOCOL} (or {@link #CUSTOM_PROTOCOL}) and 2692 * {@link #IM_HANDLE} columns. 2693 * </td> 2694 * </tr> 2695 * <tr> 2696 * <td>long</td> 2697 * <td>{@link #PROTOCOL}</td> 2698 * <td>read/write</td> 2699 * <td>See {@link CommonDataKinds.Im} for a list of defined protocol constants.</td> 2700 * </tr> 2701 * <tr> 2702 * <td>String</td> 2703 * <td>{@link #CUSTOM_PROTOCOL}</td> 2704 * <td>read/write</td> 2705 * <td>Name of the custom protocol. Should be supplied along with the {@link #PROTOCOL} value 2706 * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}. Should be null or 2707 * omitted if {@link #PROTOCOL} value is not 2708 * {@link ContactsContract.CommonDataKinds.Im#PROTOCOL_CUSTOM}.</td> 2709 * </tr> 2710 * <tr> 2711 * <td>String</td> 2712 * <td>{@link #IM_HANDLE}</td> 2713 * <td>read/write</td> 2714 * <td> The IM handle the presence item is for. The handle is scoped to 2715 * {@link #PROTOCOL}.</td> 2716 * </tr> 2717 * <tr> 2718 * <td>String</td> 2719 * <td>{@link #IM_ACCOUNT}</td> 2720 * <td>read/write</td> 2721 * <td>The IM account for the local user that the presence data came from.</td> 2722 * </tr> 2723 * <tr> 2724 * <td>int</td> 2725 * <td>{@link #PRESENCE}</td> 2726 * <td>read/write</td> 2727 * <td>Contact IM presence status. The allowed values are: 2728 * <p> 2729 * <ul> 2730 * <li>{@link #OFFLINE}</li> 2731 * <li>{@link #INVISIBLE}</li> 2732 * <li>{@link #AWAY}</li> 2733 * <li>{@link #IDLE}</li> 2734 * <li>{@link #DO_NOT_DISTURB}</li> 2735 * <li>{@link #AVAILABLE}</li> 2736 * </ul> 2737 * </p> 2738 * <p> 2739 * Since presence status is inherently volatile, the content provider 2740 * may choose not to store this field in long-term storage. 2741 * </p> 2742 * </td> 2743 * </tr> 2744 * <tr> 2745 * <td>String</td> 2746 * <td>{@link #STATUS}</td> 2747 * <td>read/write</td> 2748 * <td>Contact's latest status update, e.g. "having toast for breakfast"</td> 2749 * </tr> 2750 * <tr> 2751 * <td>long</td> 2752 * <td>{@link #STATUS_TIMESTAMP}</td> 2753 * <td>read/write</td> 2754 * <td>The absolute time in milliseconds when the status was 2755 * entered by the user. If this value is not provided, the provider will follow 2756 * this logic: if there was no prior status update, the value will be left as null. 2757 * If there was a prior status update, the provider will default this field 2758 * to the current time.</td> 2759 * </tr> 2760 * <tr> 2761 * <td>String</td> 2762 * <td>{@link #STATUS_RES_PACKAGE}</td> 2763 * <td>read/write</td> 2764 * <td> The package containing resources for this status: label and icon.</td> 2765 * </tr> 2766 * <tr> 2767 * <td>long</td> 2768 * <td>{@link #STATUS_LABEL}</td> 2769 * <td>read/write</td> 2770 * <td>The resource ID of the label describing the source of contact status, 2771 * e.g. "Google Talk". This resource is scoped by the 2772 * {@link #STATUS_RES_PACKAGE}.</td> 2773 * </tr> 2774 * <tr> 2775 * <td>long</td> 2776 * <td>{@link #STATUS_ICON}</td> 2777 * <td>read/write</td> 2778 * <td>The resource ID of the icon for the source of contact status. This 2779 * resource is scoped by the {@link #STATUS_RES_PACKAGE}.</td> 2780 * </tr> 2781 * </table> 2782 */ 2783 public static class StatusUpdates implements StatusColumns, PresenceColumns { 2784 2785 /** 2786 * This utility class cannot be instantiated 2787 */ 2788 private StatusUpdates() {} 2789 2790 /** 2791 * The content:// style URI for this table 2792 */ 2793 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "status_updates"); 2794 2795 /** 2796 * Gets the resource ID for the proper presence icon. 2797 * 2798 * @param status the status to get the icon for 2799 * @return the resource ID for the proper presence icon 2800 */ 2801 public static final int getPresenceIconResourceId(int status) { 2802 switch (status) { 2803 case AVAILABLE: 2804 return android.R.drawable.presence_online; 2805 case IDLE: 2806 case AWAY: 2807 return android.R.drawable.presence_away; 2808 case DO_NOT_DISTURB: 2809 return android.R.drawable.presence_busy; 2810 case INVISIBLE: 2811 return android.R.drawable.presence_invisible; 2812 case OFFLINE: 2813 default: 2814 return android.R.drawable.presence_offline; 2815 } 2816 } 2817 2818 /** 2819 * Returns the precedence of the status code the higher number being the higher precedence. 2820 * 2821 * @param status The status code. 2822 * @return An integer representing the precedence, 0 being the lowest. 2823 */ 2824 public static final int getPresencePrecedence(int status) { 2825 // Keep this function here incase we want to enforce a different precedence than the 2826 // natural order of the status constants. 2827 return status; 2828 } 2829 2830 /** 2831 * The MIME type of {@link #CONTENT_URI} providing a directory of 2832 * status update details. 2833 */ 2834 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/status-update"; 2835 2836 /** 2837 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 2838 * status update detail. 2839 */ 2840 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/status-update"; 2841 } 2842 2843 /** 2844 * @deprecated This old name was never meant to be made public. Do not use. 2845 */ 2846 @Deprecated 2847 public static final class Presence extends StatusUpdates { 2848 2849 } 2850 2851 /** 2852 * Container for definitions of common data types stored in the {@link ContactsContract.Data} 2853 * table. 2854 */ 2855 public static final class CommonDataKinds { 2856 /** 2857 * This utility class cannot be instantiated 2858 */ 2859 private CommonDataKinds() {} 2860 2861 /** 2862 * The {@link Data#RES_PACKAGE} value for common data that should be 2863 * shown using a default style. 2864 * 2865 * @hide RES_PACKAGE is hidden 2866 */ 2867 public static final String PACKAGE_COMMON = "common"; 2868 2869 /** 2870 * The base types that all "Typed" data kinds support. 2871 */ 2872 public interface BaseTypes { 2873 /** 2874 * A custom type. The custom label should be supplied by user. 2875 */ 2876 public static int TYPE_CUSTOM = 0; 2877 } 2878 2879 /** 2880 * Columns common across the specific types. 2881 */ 2882 protected interface CommonColumns extends BaseTypes { 2883 /** 2884 * The data for the contact method. 2885 * <P>Type: TEXT</P> 2886 */ 2887 public static final String DATA = DataColumns.DATA1; 2888 2889 /** 2890 * The type of data, for example Home or Work. 2891 * <P>Type: INTEGER</P> 2892 */ 2893 public static final String TYPE = DataColumns.DATA2; 2894 2895 /** 2896 * The user defined label for the the contact method. 2897 * <P>Type: TEXT</P> 2898 */ 2899 public static final String LABEL = DataColumns.DATA3; 2900 } 2901 2902 /** 2903 * A data kind representing the contact's proper name. You can use all 2904 * columns defined for {@link ContactsContract.Data} as well as the following aliases. 2905 * 2906 * <h2>Column aliases</h2> 2907 * <table class="jd-sumtable"> 2908 * <tr> 2909 * <th>Type</th><th>Alias</th><th colspan='2'>Data column</th> 2910 * </tr> 2911 * <tr> 2912 * <td>String</td> 2913 * <td>{@link #DISPLAY_NAME}</td> 2914 * <td>{@link #DATA1}</td> 2915 * <td></td> 2916 * </tr> 2917 * <tr> 2918 * <td>String</td> 2919 * <td>{@link #GIVEN_NAME}</td> 2920 * <td>{@link #DATA2}</td> 2921 * <td></td> 2922 * </tr> 2923 * <tr> 2924 * <td>String</td> 2925 * <td>{@link #FAMILY_NAME}</td> 2926 * <td>{@link #DATA3}</td> 2927 * <td></td> 2928 * </tr> 2929 * <tr> 2930 * <td>String</td> 2931 * <td>{@link #PREFIX}</td> 2932 * <td>{@link #DATA4}</td> 2933 * <td>Common prefixes in English names are "Mr", "Ms", "Dr" etc.</td> 2934 * </tr> 2935 * <tr> 2936 * <td>String</td> 2937 * <td>{@link #MIDDLE_NAME}</td> 2938 * <td>{@link #DATA5}</td> 2939 * <td></td> 2940 * </tr> 2941 * <tr> 2942 * <td>String</td> 2943 * <td>{@link #SUFFIX}</td> 2944 * <td>{@link #DATA6}</td> 2945 * <td>Common suffixes in English names are "Sr", "Jr", "III" etc.</td> 2946 * </tr> 2947 * <tr> 2948 * <td>String</td> 2949 * <td>{@link #PHONETIC_GIVEN_NAME}</td> 2950 * <td>{@link #DATA7}</td> 2951 * <td>Used for phonetic spelling of the name, e.g. Pinyin, Katakana, Hiragana</td> 2952 * </tr> 2953 * <tr> 2954 * <td>String</td> 2955 * <td>{@link #PHONETIC_MIDDLE_NAME}</td> 2956 * <td>{@link #DATA8}</td> 2957 * <td></td> 2958 * </tr> 2959 * <tr> 2960 * <td>String</td> 2961 * <td>{@link #PHONETIC_FAMILY_NAME}</td> 2962 * <td>{@link #DATA9}</td> 2963 * <td></td> 2964 * </tr> 2965 * </table> 2966 */ 2967 public static final class StructuredName implements DataColumnsWithJoins { 2968 /** 2969 * This utility class cannot be instantiated 2970 */ 2971 private StructuredName() {} 2972 2973 /** MIME type used when storing this in data table. */ 2974 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/name"; 2975 2976 /** 2977 * The name that should be used to display the contact. 2978 * <i>Unstructured component of the name should be consistent with 2979 * its structured representation.</i> 2980 * <p> 2981 * Type: TEXT 2982 */ 2983 public static final String DISPLAY_NAME = DATA1; 2984 2985 /** 2986 * The given name for the contact. 2987 * <P>Type: TEXT</P> 2988 */ 2989 public static final String GIVEN_NAME = DATA2; 2990 2991 /** 2992 * The family name for the contact. 2993 * <P>Type: TEXT</P> 2994 */ 2995 public static final String FAMILY_NAME = DATA3; 2996 2997 /** 2998 * The contact's honorific prefix, e.g. "Sir" 2999 * <P>Type: TEXT</P> 3000 */ 3001 public static final String PREFIX = DATA4; 3002 3003 /** 3004 * The contact's middle name 3005 * <P>Type: TEXT</P> 3006 */ 3007 public static final String MIDDLE_NAME = DATA5; 3008 3009 /** 3010 * The contact's honorific suffix, e.g. "Jr" 3011 */ 3012 public static final String SUFFIX = DATA6; 3013 3014 /** 3015 * The phonetic version of the given name for the contact. 3016 * <P>Type: TEXT</P> 3017 */ 3018 public static final String PHONETIC_GIVEN_NAME = DATA7; 3019 3020 /** 3021 * The phonetic version of the additional name for the contact. 3022 * <P>Type: TEXT</P> 3023 */ 3024 public static final String PHONETIC_MIDDLE_NAME = DATA8; 3025 3026 /** 3027 * The phonetic version of the family name for the contact. 3028 * <P>Type: TEXT</P> 3029 */ 3030 public static final String PHONETIC_FAMILY_NAME = DATA9; 3031 3032 /** 3033 * The style used for combining given/middle/family name into a full name. 3034 * See {@link ContactsContract.FullNameStyle}. 3035 * 3036 * @hide 3037 */ 3038 public static final String FULL_NAME_STYLE = DATA10; 3039 3040 /** 3041 * The alphabet used for capturing the phonetic name. 3042 * See {@link ContactsContract.PhoneticNameStyle}. 3043 * @hide 3044 */ 3045 public static final String PHONETIC_NAME_STYLE = DATA11; 3046 } 3047 3048 /** 3049 * <p>A data kind representing the contact's nickname. For example, for 3050 * Bob Parr ("Mr. Incredible"): 3051 * <pre> 3052 * ArrayList<ContentProviderOperation> ops = Lists.newArrayList(); 3053 * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI) 3054 * .withValue(Data.RAW_CONTACT_ID, rawContactId) 3055 * .withValue(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE) 3056 * .withValue(StructuredName.DISPLAY_NAME, "Bob Parr") 3057 * .build()); 3058 * 3059 * ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI) 3060 * .withValue(Data.RAW_CONTACT_ID, rawContactId) 3061 * .withValue(Data.MIMETYPE, Nickname.CONTENT_ITEM_TYPE) 3062 * .withValue(Nickname.NAME, "Mr. Incredible") 3063 * .withValue(Nickname.TYPE, Nickname.TYPE_CUSTOM) 3064 * .withValue(Nickname.LABEL, "Superhero") 3065 * .build()); 3066 * 3067 * getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); 3068 * </pre> 3069 * </p> 3070 * <p> 3071 * You can use all columns defined for {@link ContactsContract.Data} as well as the 3072 * following aliases. 3073 * </p> 3074 * 3075 * <h2>Column aliases</h2> 3076 * <table class="jd-sumtable"> 3077 * <tr> 3078 * <th>Type</th><th>Alias</th><th colspan='2'>Data column</th> 3079 * </tr> 3080 * <tr> 3081 * <td>String</td> 3082 * <td>{@link #NAME}</td> 3083 * <td>{@link #DATA1}</td> 3084 * <td></td> 3085 * </tr> 3086 * <tr> 3087 * <td>int</td> 3088 * <td>{@link #TYPE}</td> 3089 * <td>{@link #DATA2}</td> 3090 * <td> 3091 * Allowed values are: 3092 * <p> 3093 * <ul> 3094 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 3095 * <li>{@link #TYPE_DEFAULT}</li> 3096 * <li>{@link #TYPE_OTHER_NAME}</li> 3097 * <li>{@link #TYPE_MAINDEN_NAME}</li> 3098 * <li>{@link #TYPE_SHORT_NAME}</li> 3099 * <li>{@link #TYPE_INITIALS}</li> 3100 * </ul> 3101 * </p> 3102 * </td> 3103 * </tr> 3104 * <tr> 3105 * <td>String</td> 3106 * <td>{@link #LABEL}</td> 3107 * <td>{@link #DATA3}</td> 3108 * <td></td> 3109 * </tr> 3110 * </table> 3111 */ 3112 public static final class Nickname implements DataColumnsWithJoins, CommonColumns { 3113 /** 3114 * This utility class cannot be instantiated 3115 */ 3116 private Nickname() {} 3117 3118 /** MIME type used when storing this in data table. */ 3119 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/nickname"; 3120 3121 public static final int TYPE_DEFAULT = 1; 3122 public static final int TYPE_OTHER_NAME = 2; 3123 public static final int TYPE_MAINDEN_NAME = 3; 3124 public static final int TYPE_SHORT_NAME = 4; 3125 public static final int TYPE_INITIALS = 5; 3126 3127 /** 3128 * The name itself 3129 */ 3130 public static final String NAME = DATA; 3131 } 3132 3133 /** 3134 * <p> 3135 * A data kind representing a telephone number. 3136 * </p> 3137 * <p> 3138 * You can use all columns defined for {@link ContactsContract.Data} as 3139 * well as the following aliases. 3140 * </p> 3141 * <h2>Column aliases</h2> 3142 * <table class="jd-sumtable"> 3143 * <tr> 3144 * <th>Type</th> 3145 * <th>Alias</th><th colspan='2'>Data column</th> 3146 * </tr> 3147 * <tr> 3148 * <td>String</td> 3149 * <td>{@link #NUMBER}</td> 3150 * <td>{@link #DATA1}</td> 3151 * <td></td> 3152 * </tr> 3153 * <tr> 3154 * <td>int</td> 3155 * <td>{@link #TYPE}</td> 3156 * <td>{@link #DATA2}</td> 3157 * <td>Allowed values are: 3158 * <p> 3159 * <ul> 3160 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 3161 * <li>{@link #TYPE_HOME}</li> 3162 * <li>{@link #TYPE_MOBILE}</li> 3163 * <li>{@link #TYPE_WORK}</li> 3164 * <li>{@link #TYPE_FAX_WORK}</li> 3165 * <li>{@link #TYPE_FAX_HOME}</li> 3166 * <li>{@link #TYPE_PAGER}</li> 3167 * <li>{@link #TYPE_OTHER}</li> 3168 * <li>{@link #TYPE_CALLBACK}</li> 3169 * <li>{@link #TYPE_CAR}</li> 3170 * <li>{@link #TYPE_COMPANY_MAIN}</li> 3171 * <li>{@link #TYPE_ISDN}</li> 3172 * <li>{@link #TYPE_MAIN}</li> 3173 * <li>{@link #TYPE_OTHER_FAX}</li> 3174 * <li>{@link #TYPE_RADIO}</li> 3175 * <li>{@link #TYPE_TELEX}</li> 3176 * <li>{@link #TYPE_TTY_TDD}</li> 3177 * <li>{@link #TYPE_WORK_MOBILE}</li> 3178 * <li>{@link #TYPE_WORK_PAGER}</li> 3179 * <li>{@link #TYPE_ASSISTANT}</li> 3180 * <li>{@link #TYPE_MMS}</li> 3181 * </ul> 3182 * </p> 3183 * </td> 3184 * </tr> 3185 * <tr> 3186 * <td>String</td> 3187 * <td>{@link #LABEL}</td> 3188 * <td>{@link #DATA3}</td> 3189 * <td></td> 3190 * </tr> 3191 * </table> 3192 */ 3193 public static final class Phone implements DataColumnsWithJoins, CommonColumns { 3194 /** 3195 * This utility class cannot be instantiated 3196 */ 3197 private Phone() {} 3198 3199 /** MIME type used when storing this in data table. */ 3200 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone_v2"; 3201 3202 /** 3203 * The MIME type of {@link #CONTENT_URI} providing a directory of 3204 * phones. 3205 */ 3206 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/phone_v2"; 3207 3208 /** 3209 * The content:// style URI for all data records of the 3210 * {@link #CONTENT_ITEM_TYPE} MIME type, combined with the 3211 * associated raw contact and aggregate contact data. 3212 */ 3213 public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI, 3214 "phones"); 3215 3216 /** 3217 * The content:// style URL for phone lookup using a filter. The filter returns 3218 * records of MIME type {@link #CONTENT_ITEM_TYPE}. The filter is applied 3219 * to display names as well as phone numbers. The filter argument should be passed 3220 * as an additional path segment after this URI. 3221 */ 3222 public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI, 3223 "filter"); 3224 3225 public static final int TYPE_HOME = 1; 3226 public static final int TYPE_MOBILE = 2; 3227 public static final int TYPE_WORK = 3; 3228 public static final int TYPE_FAX_WORK = 4; 3229 public static final int TYPE_FAX_HOME = 5; 3230 public static final int TYPE_PAGER = 6; 3231 public static final int TYPE_OTHER = 7; 3232 public static final int TYPE_CALLBACK = 8; 3233 public static final int TYPE_CAR = 9; 3234 public static final int TYPE_COMPANY_MAIN = 10; 3235 public static final int TYPE_ISDN = 11; 3236 public static final int TYPE_MAIN = 12; 3237 public static final int TYPE_OTHER_FAX = 13; 3238 public static final int TYPE_RADIO = 14; 3239 public static final int TYPE_TELEX = 15; 3240 public static final int TYPE_TTY_TDD = 16; 3241 public static final int TYPE_WORK_MOBILE = 17; 3242 public static final int TYPE_WORK_PAGER = 18; 3243 public static final int TYPE_ASSISTANT = 19; 3244 public static final int TYPE_MMS = 20; 3245 3246 /** 3247 * The phone number as the user entered it. 3248 * <P>Type: TEXT</P> 3249 */ 3250 public static final String NUMBER = DATA; 3251 3252 /** 3253 * @deprecated use {@link #getTypeLabel(Resources, int, CharSequence)} instead. 3254 * @hide 3255 */ 3256 @Deprecated 3257 public static final CharSequence getDisplayLabel(Context context, int type, 3258 CharSequence label, CharSequence[] labelArray) { 3259 return getTypeLabel(context.getResources(), type, label); 3260 } 3261 3262 /** 3263 * @deprecated use {@link #getTypeLabel(Resources, int, CharSequence)} instead. 3264 * @hide 3265 */ 3266 @Deprecated 3267 public static final CharSequence getDisplayLabel(Context context, int type, 3268 CharSequence label) { 3269 return getTypeLabel(context.getResources(), type, label); 3270 } 3271 3272 /** 3273 * Return the string resource that best describes the given 3274 * {@link #TYPE}. Will always return a valid resource. 3275 */ 3276 public static final int getTypeLabelResource(int type) { 3277 switch (type) { 3278 case TYPE_HOME: return com.android.internal.R.string.phoneTypeHome; 3279 case TYPE_MOBILE: return com.android.internal.R.string.phoneTypeMobile; 3280 case TYPE_WORK: return com.android.internal.R.string.phoneTypeWork; 3281 case TYPE_FAX_WORK: return com.android.internal.R.string.phoneTypeFaxWork; 3282 case TYPE_FAX_HOME: return com.android.internal.R.string.phoneTypeFaxHome; 3283 case TYPE_PAGER: return com.android.internal.R.string.phoneTypePager; 3284 case TYPE_OTHER: return com.android.internal.R.string.phoneTypeOther; 3285 case TYPE_CALLBACK: return com.android.internal.R.string.phoneTypeCallback; 3286 case TYPE_CAR: return com.android.internal.R.string.phoneTypeCar; 3287 case TYPE_COMPANY_MAIN: return com.android.internal.R.string.phoneTypeCompanyMain; 3288 case TYPE_ISDN: return com.android.internal.R.string.phoneTypeIsdn; 3289 case TYPE_MAIN: return com.android.internal.R.string.phoneTypeMain; 3290 case TYPE_OTHER_FAX: return com.android.internal.R.string.phoneTypeOtherFax; 3291 case TYPE_RADIO: return com.android.internal.R.string.phoneTypeRadio; 3292 case TYPE_TELEX: return com.android.internal.R.string.phoneTypeTelex; 3293 case TYPE_TTY_TDD: return com.android.internal.R.string.phoneTypeTtyTdd; 3294 case TYPE_WORK_MOBILE: return com.android.internal.R.string.phoneTypeWorkMobile; 3295 case TYPE_WORK_PAGER: return com.android.internal.R.string.phoneTypeWorkPager; 3296 case TYPE_ASSISTANT: return com.android.internal.R.string.phoneTypeAssistant; 3297 case TYPE_MMS: return com.android.internal.R.string.phoneTypeMms; 3298 default: return com.android.internal.R.string.phoneTypeCustom; 3299 } 3300 } 3301 3302 /** 3303 * Return a {@link CharSequence} that best describes the given type, 3304 * possibly substituting the given {@link #LABEL} value 3305 * for {@link #TYPE_CUSTOM}. 3306 */ 3307 public static final CharSequence getTypeLabel(Resources res, int type, 3308 CharSequence label) { 3309 if ((type == TYPE_CUSTOM || type == TYPE_ASSISTANT) && !TextUtils.isEmpty(label)) { 3310 return label; 3311 } else { 3312 final int labelRes = getTypeLabelResource(type); 3313 return res.getText(labelRes); 3314 } 3315 } 3316 } 3317 3318 /** 3319 * <p> 3320 * A data kind representing an email address. 3321 * </p> 3322 * <p> 3323 * You can use all columns defined for {@link ContactsContract.Data} as 3324 * well as the following aliases. 3325 * </p> 3326 * <h2>Column aliases</h2> 3327 * <table class="jd-sumtable"> 3328 * <tr> 3329 * <th>Type</th> 3330 * <th>Alias</th><th colspan='2'>Data column</th> 3331 * </tr> 3332 * <tr> 3333 * <td>String</td> 3334 * <td>{@link #DATA}</td> 3335 * <td>{@link #DATA1}</td> 3336 * <td>Email address itself.</td> 3337 * </tr> 3338 * <tr> 3339 * <td>int</td> 3340 * <td>{@link #TYPE}</td> 3341 * <td>{@link #DATA2}</td> 3342 * <td>Allowed values are: 3343 * <p> 3344 * <ul> 3345 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 3346 * <li>{@link #TYPE_HOME}</li> 3347 * <li>{@link #TYPE_WORK}</li> 3348 * <li>{@link #TYPE_OTHER}</li> 3349 * <li>{@link #TYPE_MOBILE}</li> 3350 * </ul> 3351 * </p> 3352 * </td> 3353 * </tr> 3354 * <tr> 3355 * <td>String</td> 3356 * <td>{@link #LABEL}</td> 3357 * <td>{@link #DATA3}</td> 3358 * <td></td> 3359 * </tr> 3360 * </table> 3361 */ 3362 public static final class Email implements DataColumnsWithJoins, CommonColumns { 3363 /** 3364 * This utility class cannot be instantiated 3365 */ 3366 private Email() {} 3367 3368 /** MIME type used when storing this in data table. */ 3369 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/email_v2"; 3370 3371 /** 3372 * The MIME type of {@link #CONTENT_URI} providing a directory of email addresses. 3373 */ 3374 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/email_v2"; 3375 3376 /** 3377 * The content:// style URI for all data records of the 3378 * {@link #CONTENT_ITEM_TYPE} MIME type, combined with the 3379 * associated raw contact and aggregate contact data. 3380 */ 3381 public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI, 3382 "emails"); 3383 3384 /** 3385 * <p> 3386 * The content:// style URL for looking up data rows by email address. The 3387 * lookup argument, an email address, should be passed as an additional path segment 3388 * after this URI. 3389 * </p> 3390 * <p>Example: 3391 * <pre> 3392 * Uri uri = Uri.withAppendedPath(Email.CONTENT_LOOKUP_URI, Uri.encode(email)); 3393 * Cursor c = getContentResolver().query(uri, 3394 * new String[]{Email.CONTACT_ID, Email.DISPLAY_NAME, Email.DATA}, 3395 * null, null, null); 3396 * </pre> 3397 * </p> 3398 */ 3399 public static final Uri CONTENT_LOOKUP_URI = Uri.withAppendedPath(CONTENT_URI, 3400 "lookup"); 3401 3402 /** 3403 * <p> 3404 * The content:// style URL for email lookup using a filter. The filter returns 3405 * records of MIME type {@link #CONTENT_ITEM_TYPE}. The filter is applied 3406 * to display names as well as email addresses. The filter argument should be passed 3407 * as an additional path segment after this URI. 3408 * </p> 3409 * <p>The query in the following example will return "Robert Parr (bob@incredibles.com)" 3410 * as well as "Bob Parr (incredible@android.com)". 3411 * <pre> 3412 * Uri uri = Uri.withAppendedPath(Email.CONTENT_LOOKUP_URI, Uri.encode("bob")); 3413 * Cursor c = getContentResolver().query(uri, 3414 * new String[]{Email.DISPLAY_NAME, Email.DATA}, 3415 * null, null, null); 3416 * </pre> 3417 * </p> 3418 */ 3419 public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI, 3420 "filter"); 3421 3422 /** 3423 * The email address. 3424 * <P>Type: TEXT</P> 3425 * @hide TODO: Unhide in a separate CL 3426 */ 3427 public static final String ADDRESS = DATA1; 3428 3429 public static final int TYPE_HOME = 1; 3430 public static final int TYPE_WORK = 2; 3431 public static final int TYPE_OTHER = 3; 3432 public static final int TYPE_MOBILE = 4; 3433 3434 /** 3435 * The display name for the email address 3436 * <P>Type: TEXT</P> 3437 */ 3438 public static final String DISPLAY_NAME = DATA4; 3439 3440 /** 3441 * Return the string resource that best describes the given 3442 * {@link #TYPE}. Will always return a valid resource. 3443 */ 3444 public static final int getTypeLabelResource(int type) { 3445 switch (type) { 3446 case TYPE_HOME: return com.android.internal.R.string.emailTypeHome; 3447 case TYPE_WORK: return com.android.internal.R.string.emailTypeWork; 3448 case TYPE_OTHER: return com.android.internal.R.string.emailTypeOther; 3449 case TYPE_MOBILE: return com.android.internal.R.string.emailTypeMobile; 3450 default: return com.android.internal.R.string.emailTypeCustom; 3451 } 3452 } 3453 3454 /** 3455 * Return a {@link CharSequence} that best describes the given type, 3456 * possibly substituting the given {@link #LABEL} value 3457 * for {@link #TYPE_CUSTOM}. 3458 */ 3459 public static final CharSequence getTypeLabel(Resources res, int type, 3460 CharSequence label) { 3461 if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) { 3462 return label; 3463 } else { 3464 final int labelRes = getTypeLabelResource(type); 3465 return res.getText(labelRes); 3466 } 3467 } 3468 } 3469 3470 /** 3471 * <p> 3472 * A data kind representing a postal addresses. 3473 * </p> 3474 * <p> 3475 * You can use all columns defined for {@link ContactsContract.Data} as 3476 * well as the following aliases. 3477 * </p> 3478 * <h2>Column aliases</h2> 3479 * <table class="jd-sumtable"> 3480 * <tr> 3481 * <th>Type</th> 3482 * <th>Alias</th><th colspan='2'>Data column</th> 3483 * </tr> 3484 * <tr> 3485 * <td>String</td> 3486 * <td>{@link #FORMATTED_ADDRESS}</td> 3487 * <td>{@link #DATA1}</td> 3488 * <td></td> 3489 * </tr> 3490 * <tr> 3491 * <td>int</td> 3492 * <td>{@link #TYPE}</td> 3493 * <td>{@link #DATA2}</td> 3494 * <td>Allowed values are: 3495 * <p> 3496 * <ul> 3497 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 3498 * <li>{@link #TYPE_HOME}</li> 3499 * <li>{@link #TYPE_WORK}</li> 3500 * <li>{@link #TYPE_OTHER}</li> 3501 * </ul> 3502 * </p> 3503 * </td> 3504 * </tr> 3505 * <tr> 3506 * <td>String</td> 3507 * <td>{@link #LABEL}</td> 3508 * <td>{@link #DATA3}</td> 3509 * <td></td> 3510 * </tr> 3511 * <tr> 3512 * <td>String</td> 3513 * <td>{@link #STREET}</td> 3514 * <td>{@link #DATA4}</td> 3515 * <td></td> 3516 * </tr> 3517 * <tr> 3518 * <td>String</td> 3519 * <td>{@link #POBOX}</td> 3520 * <td>{@link #DATA5}</td> 3521 * <td>Post Office Box number</td> 3522 * </tr> 3523 * <tr> 3524 * <td>String</td> 3525 * <td>{@link #NEIGHBORHOOD}</td> 3526 * <td>{@link #DATA6}</td> 3527 * <td></td> 3528 * </tr> 3529 * <tr> 3530 * <td>String</td> 3531 * <td>{@link #CITY}</td> 3532 * <td>{@link #DATA7}</td> 3533 * <td></td> 3534 * </tr> 3535 * <tr> 3536 * <td>String</td> 3537 * <td>{@link #REGION}</td> 3538 * <td>{@link #DATA8}</td> 3539 * <td></td> 3540 * </tr> 3541 * <tr> 3542 * <td>String</td> 3543 * <td>{@link #POSTCODE}</td> 3544 * <td>{@link #DATA9}</td> 3545 * <td></td> 3546 * </tr> 3547 * <tr> 3548 * <td>String</td> 3549 * <td>{@link #COUNTRY}</td> 3550 * <td>{@link #DATA10}</td> 3551 * <td></td> 3552 * </tr> 3553 * </table> 3554 */ 3555 public static final class StructuredPostal implements DataColumnsWithJoins, CommonColumns { 3556 /** 3557 * This utility class cannot be instantiated 3558 */ 3559 private StructuredPostal() { 3560 } 3561 3562 /** MIME type used when storing this in data table. */ 3563 public static final String CONTENT_ITEM_TYPE = 3564 "vnd.android.cursor.item/postal-address_v2"; 3565 3566 /** 3567 * The MIME type of {@link #CONTENT_URI} providing a directory of 3568 * postal addresses. 3569 */ 3570 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/postal-address_v2"; 3571 3572 /** 3573 * The content:// style URI for all data records of the 3574 * {@link StructuredPostal#CONTENT_ITEM_TYPE} MIME type. 3575 */ 3576 public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI, 3577 "postals"); 3578 3579 public static final int TYPE_HOME = 1; 3580 public static final int TYPE_WORK = 2; 3581 public static final int TYPE_OTHER = 3; 3582 3583 /** 3584 * The full, unstructured postal address. <i>This field must be 3585 * consistent with any structured data.</i> 3586 * <p> 3587 * Type: TEXT 3588 */ 3589 public static final String FORMATTED_ADDRESS = DATA; 3590 3591 /** 3592 * Can be street, avenue, road, etc. This element also includes the 3593 * house number and room/apartment/flat/floor number. 3594 * <p> 3595 * Type: TEXT 3596 */ 3597 public static final String STREET = DATA4; 3598 3599 /** 3600 * Covers actual P.O. boxes, drawers, locked bags, etc. This is 3601 * usually but not always mutually exclusive with street. 3602 * <p> 3603 * Type: TEXT 3604 */ 3605 public static final String POBOX = DATA5; 3606 3607 /** 3608 * This is used to disambiguate a street address when a city 3609 * contains more than one street with the same name, or to specify a 3610 * small place whose mail is routed through a larger postal town. In 3611 * China it could be a county or a minor city. 3612 * <p> 3613 * Type: TEXT 3614 */ 3615 public static final String NEIGHBORHOOD = DATA6; 3616 3617 /** 3618 * Can be city, village, town, borough, etc. This is the postal town 3619 * and not necessarily the place of residence or place of business. 3620 * <p> 3621 * Type: TEXT 3622 */ 3623 public static final String CITY = DATA7; 3624 3625 /** 3626 * A state, province, county (in Ireland), Land (in Germany), 3627 * departement (in France), etc. 3628 * <p> 3629 * Type: TEXT 3630 */ 3631 public static final String REGION = DATA8; 3632 3633 /** 3634 * Postal code. Usually country-wide, but sometimes specific to the 3635 * city (e.g. "2" in "Dublin 2, Ireland" addresses). 3636 * <p> 3637 * Type: TEXT 3638 */ 3639 public static final String POSTCODE = DATA9; 3640 3641 /** 3642 * The name or code of the country. 3643 * <p> 3644 * Type: TEXT 3645 */ 3646 public static final String COUNTRY = DATA10; 3647 3648 /** 3649 * Return the string resource that best describes the given 3650 * {@link #TYPE}. Will always return a valid resource. 3651 */ 3652 public static final int getTypeLabelResource(int type) { 3653 switch (type) { 3654 case TYPE_HOME: return com.android.internal.R.string.postalTypeHome; 3655 case TYPE_WORK: return com.android.internal.R.string.postalTypeWork; 3656 case TYPE_OTHER: return com.android.internal.R.string.postalTypeOther; 3657 default: return com.android.internal.R.string.postalTypeCustom; 3658 } 3659 } 3660 3661 /** 3662 * Return a {@link CharSequence} that best describes the given type, 3663 * possibly substituting the given {@link #LABEL} value 3664 * for {@link #TYPE_CUSTOM}. 3665 */ 3666 public static final CharSequence getTypeLabel(Resources res, int type, 3667 CharSequence label) { 3668 if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) { 3669 return label; 3670 } else { 3671 final int labelRes = getTypeLabelResource(type); 3672 return res.getText(labelRes); 3673 } 3674 } 3675 } 3676 3677 /** 3678 * <p> 3679 * A data kind representing an IM address 3680 * </p> 3681 * <p> 3682 * You can use all columns defined for {@link ContactsContract.Data} as 3683 * well as the following aliases. 3684 * </p> 3685 * <h2>Column aliases</h2> 3686 * <table class="jd-sumtable"> 3687 * <tr> 3688 * <th>Type</th> 3689 * <th>Alias</th><th colspan='2'>Data column</th> 3690 * </tr> 3691 * <tr> 3692 * <td>String</td> 3693 * <td>{@link #DATA}</td> 3694 * <td>{@link #DATA1}</td> 3695 * <td></td> 3696 * </tr> 3697 * <tr> 3698 * <td>int</td> 3699 * <td>{@link #TYPE}</td> 3700 * <td>{@link #DATA2}</td> 3701 * <td>Allowed values are: 3702 * <p> 3703 * <ul> 3704 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 3705 * <li>{@link #TYPE_HOME}</li> 3706 * <li>{@link #TYPE_WORK}</li> 3707 * <li>{@link #TYPE_OTHER}</li> 3708 * </ul> 3709 * </p> 3710 * </td> 3711 * </tr> 3712 * <tr> 3713 * <td>String</td> 3714 * <td>{@link #LABEL}</td> 3715 * <td>{@link #DATA3}</td> 3716 * <td></td> 3717 * </tr> 3718 * <tr> 3719 * <td>String</td> 3720 * <td>{@link #PROTOCOL}</td> 3721 * <td>{@link #DATA5}</td> 3722 * <td> 3723 * <p> 3724 * Allowed values: 3725 * <ul> 3726 * <li>{@link #PROTOCOL_CUSTOM}. Also provide the actual protocol name 3727 * as {@link #CUSTOM_PROTOCOL}.</li> 3728 * <li>{@link #PROTOCOL_AIM}</li> 3729 * <li>{@link #PROTOCOL_MSN}</li> 3730 * <li>{@link #PROTOCOL_YAHOO}</li> 3731 * <li>{@link #PROTOCOL_SKYPE}</li> 3732 * <li>{@link #PROTOCOL_QQ}</li> 3733 * <li>{@link #PROTOCOL_GOOGLE_TALK}</li> 3734 * <li>{@link #PROTOCOL_ICQ}</li> 3735 * <li>{@link #PROTOCOL_JABBER}</li> 3736 * <li>{@link #PROTOCOL_NETMEETING}</li> 3737 * </ul> 3738 * </p> 3739 * </td> 3740 * </tr> 3741 * <tr> 3742 * <td>String</td> 3743 * <td>{@link #CUSTOM_PROTOCOL}</td> 3744 * <td>{@link #DATA6}</td> 3745 * <td></td> 3746 * </tr> 3747 * </table> 3748 */ 3749 public static final class Im implements DataColumnsWithJoins, CommonColumns { 3750 /** 3751 * This utility class cannot be instantiated 3752 */ 3753 private Im() {} 3754 3755 /** MIME type used when storing this in data table. */ 3756 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im"; 3757 3758 public static final int TYPE_HOME = 1; 3759 public static final int TYPE_WORK = 2; 3760 public static final int TYPE_OTHER = 3; 3761 3762 /** 3763 * This column should be populated with one of the defined 3764 * constants, e.g. {@link #PROTOCOL_YAHOO}. If the value of this 3765 * column is {@link #PROTOCOL_CUSTOM}, the {@link #CUSTOM_PROTOCOL} 3766 * should contain the name of the custom protocol. 3767 */ 3768 public static final String PROTOCOL = DATA5; 3769 3770 public static final String CUSTOM_PROTOCOL = DATA6; 3771 3772 /* 3773 * The predefined IM protocol types. 3774 */ 3775 public static final int PROTOCOL_CUSTOM = -1; 3776 public static final int PROTOCOL_AIM = 0; 3777 public static final int PROTOCOL_MSN = 1; 3778 public static final int PROTOCOL_YAHOO = 2; 3779 public static final int PROTOCOL_SKYPE = 3; 3780 public static final int PROTOCOL_QQ = 4; 3781 public static final int PROTOCOL_GOOGLE_TALK = 5; 3782 public static final int PROTOCOL_ICQ = 6; 3783 public static final int PROTOCOL_JABBER = 7; 3784 public static final int PROTOCOL_NETMEETING = 8; 3785 3786 /** 3787 * Return the string resource that best describes the given 3788 * {@link #TYPE}. Will always return a valid resource. 3789 */ 3790 public static final int getTypeLabelResource(int type) { 3791 switch (type) { 3792 case TYPE_HOME: return com.android.internal.R.string.imTypeHome; 3793 case TYPE_WORK: return com.android.internal.R.string.imTypeWork; 3794 case TYPE_OTHER: return com.android.internal.R.string.imTypeOther; 3795 default: return com.android.internal.R.string.imTypeCustom; 3796 } 3797 } 3798 3799 /** 3800 * Return a {@link CharSequence} that best describes the given type, 3801 * possibly substituting the given {@link #LABEL} value 3802 * for {@link #TYPE_CUSTOM}. 3803 */ 3804 public static final CharSequence getTypeLabel(Resources res, int type, 3805 CharSequence label) { 3806 if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) { 3807 return label; 3808 } else { 3809 final int labelRes = getTypeLabelResource(type); 3810 return res.getText(labelRes); 3811 } 3812 } 3813 3814 /** 3815 * Return the string resource that best describes the given 3816 * {@link #PROTOCOL}. Will always return a valid resource. 3817 */ 3818 public static final int getProtocolLabelResource(int type) { 3819 switch (type) { 3820 case PROTOCOL_AIM: return com.android.internal.R.string.imProtocolAim; 3821 case PROTOCOL_MSN: return com.android.internal.R.string.imProtocolMsn; 3822 case PROTOCOL_YAHOO: return com.android.internal.R.string.imProtocolYahoo; 3823 case PROTOCOL_SKYPE: return com.android.internal.R.string.imProtocolSkype; 3824 case PROTOCOL_QQ: return com.android.internal.R.string.imProtocolQq; 3825 case PROTOCOL_GOOGLE_TALK: return com.android.internal.R.string.imProtocolGoogleTalk; 3826 case PROTOCOL_ICQ: return com.android.internal.R.string.imProtocolIcq; 3827 case PROTOCOL_JABBER: return com.android.internal.R.string.imProtocolJabber; 3828 case PROTOCOL_NETMEETING: return com.android.internal.R.string.imProtocolNetMeeting; 3829 default: return com.android.internal.R.string.imProtocolCustom; 3830 } 3831 } 3832 3833 /** 3834 * Return a {@link CharSequence} that best describes the given 3835 * protocol, possibly substituting the given 3836 * {@link #CUSTOM_PROTOCOL} value for {@link #PROTOCOL_CUSTOM}. 3837 */ 3838 public static final CharSequence getProtocolLabel(Resources res, int type, 3839 CharSequence label) { 3840 if (type == PROTOCOL_CUSTOM && !TextUtils.isEmpty(label)) { 3841 return label; 3842 } else { 3843 final int labelRes = getProtocolLabelResource(type); 3844 return res.getText(labelRes); 3845 } 3846 } 3847 } 3848 3849 /** 3850 * <p> 3851 * A data kind representing an organization. 3852 * </p> 3853 * <p> 3854 * You can use all columns defined for {@link ContactsContract.Data} as 3855 * well as the following aliases. 3856 * </p> 3857 * <h2>Column aliases</h2> 3858 * <table class="jd-sumtable"> 3859 * <tr> 3860 * <th>Type</th> 3861 * <th>Alias</th><th colspan='2'>Data column</th> 3862 * </tr> 3863 * <tr> 3864 * <td>String</td> 3865 * <td>{@link #COMPANY}</td> 3866 * <td>{@link #DATA1}</td> 3867 * <td></td> 3868 * </tr> 3869 * <tr> 3870 * <td>int</td> 3871 * <td>{@link #TYPE}</td> 3872 * <td>{@link #DATA2}</td> 3873 * <td>Allowed values are: 3874 * <p> 3875 * <ul> 3876 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 3877 * <li>{@link #TYPE_WORK}</li> 3878 * <li>{@link #TYPE_OTHER}</li> 3879 * </ul> 3880 * </p> 3881 * </td> 3882 * </tr> 3883 * <tr> 3884 * <td>String</td> 3885 * <td>{@link #LABEL}</td> 3886 * <td>{@link #DATA3}</td> 3887 * <td></td> 3888 * </tr> 3889 * <tr> 3890 * <td>String</td> 3891 * <td>{@link #TITLE}</td> 3892 * <td>{@link #DATA4}</td> 3893 * <td></td> 3894 * </tr> 3895 * <tr> 3896 * <td>String</td> 3897 * <td>{@link #DEPARTMENT}</td> 3898 * <td>{@link #DATA5}</td> 3899 * <td></td> 3900 * </tr> 3901 * <tr> 3902 * <td>String</td> 3903 * <td>{@link #JOB_DESCRIPTION}</td> 3904 * <td>{@link #DATA6}</td> 3905 * <td></td> 3906 * </tr> 3907 * <tr> 3908 * <td>String</td> 3909 * <td>{@link #SYMBOL}</td> 3910 * <td>{@link #DATA7}</td> 3911 * <td></td> 3912 * </tr> 3913 * <tr> 3914 * <td>String</td> 3915 * <td>{@link #PHONETIC_NAME}</td> 3916 * <td>{@link #DATA8}</td> 3917 * <td></td> 3918 * </tr> 3919 * <tr> 3920 * <td>String</td> 3921 * <td>{@link #OFFICE_LOCATION}</td> 3922 * <td>{@link #DATA9}</td> 3923 * <td></td> 3924 * </tr> 3925 * </table> 3926 */ 3927 public static final class Organization implements DataColumnsWithJoins, CommonColumns { 3928 /** 3929 * This utility class cannot be instantiated 3930 */ 3931 private Organization() {} 3932 3933 /** MIME type used when storing this in data table. */ 3934 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/organization"; 3935 3936 public static final int TYPE_WORK = 1; 3937 public static final int TYPE_OTHER = 2; 3938 3939 /** 3940 * The company as the user entered it. 3941 * <P>Type: TEXT</P> 3942 */ 3943 public static final String COMPANY = DATA; 3944 3945 /** 3946 * The position title at this company as the user entered it. 3947 * <P>Type: TEXT</P> 3948 */ 3949 public static final String TITLE = DATA4; 3950 3951 /** 3952 * The department at this company as the user entered it. 3953 * <P>Type: TEXT</P> 3954 */ 3955 public static final String DEPARTMENT = DATA5; 3956 3957 /** 3958 * The job description at this company as the user entered it. 3959 * <P>Type: TEXT</P> 3960 */ 3961 public static final String JOB_DESCRIPTION = DATA6; 3962 3963 /** 3964 * The symbol of this company as the user entered it. 3965 * <P>Type: TEXT</P> 3966 */ 3967 public static final String SYMBOL = DATA7; 3968 3969 /** 3970 * The phonetic name of this company as the user entered it. 3971 * <P>Type: TEXT</P> 3972 */ 3973 public static final String PHONETIC_NAME = DATA8; 3974 3975 /** 3976 * The office location of this organization. 3977 * <P>Type: TEXT</P> 3978 */ 3979 public static final String OFFICE_LOCATION = DATA9; 3980 3981 /** 3982 * Return the string resource that best describes the given 3983 * {@link #TYPE}. Will always return a valid resource. 3984 */ 3985 public static final int getTypeLabelResource(int type) { 3986 switch (type) { 3987 case TYPE_WORK: return com.android.internal.R.string.orgTypeWork; 3988 case TYPE_OTHER: return com.android.internal.R.string.orgTypeOther; 3989 default: return com.android.internal.R.string.orgTypeCustom; 3990 } 3991 } 3992 3993 /** 3994 * Return a {@link CharSequence} that best describes the given type, 3995 * possibly substituting the given {@link #LABEL} value 3996 * for {@link #TYPE_CUSTOM}. 3997 */ 3998 public static final CharSequence getTypeLabel(Resources res, int type, 3999 CharSequence label) { 4000 if (type == TYPE_CUSTOM && !TextUtils.isEmpty(label)) { 4001 return label; 4002 } else { 4003 final int labelRes = getTypeLabelResource(type); 4004 return res.getText(labelRes); 4005 } 4006 } 4007 } 4008 4009 /** 4010 * <p> 4011 * A data kind representing a relation. 4012 * </p> 4013 * <p> 4014 * You can use all columns defined for {@link ContactsContract.Data} as 4015 * well as the following aliases. 4016 * </p> 4017 * <h2>Column aliases</h2> 4018 * <table class="jd-sumtable"> 4019 * <tr> 4020 * <th>Type</th> 4021 * <th>Alias</th><th colspan='2'>Data column</th> 4022 * </tr> 4023 * <tr> 4024 * <td>String</td> 4025 * <td>{@link #NAME}</td> 4026 * <td>{@link #DATA1}</td> 4027 * <td></td> 4028 * </tr> 4029 * <tr> 4030 * <td>int</td> 4031 * <td>{@link #TYPE}</td> 4032 * <td>{@link #DATA2}</td> 4033 * <td>Allowed values are: 4034 * <p> 4035 * <ul> 4036 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 4037 * <li>{@link #TYPE_ASSISTANT}</li> 4038 * <li>{@link #TYPE_BROTHER}</li> 4039 * <li>{@link #TYPE_CHILD}</li> 4040 * <li>{@link #TYPE_DOMESTIC_PARTNER}</li> 4041 * <li>{@link #TYPE_FATHER}</li> 4042 * <li>{@link #TYPE_FRIEND}</li> 4043 * <li>{@link #TYPE_MANAGER}</li> 4044 * <li>{@link #TYPE_MOTHER}</li> 4045 * <li>{@link #TYPE_PARENT}</li> 4046 * <li>{@link #TYPE_PARTNER}</li> 4047 * <li>{@link #TYPE_REFERRED_BY}</li> 4048 * <li>{@link #TYPE_RELATIVE}</li> 4049 * <li>{@link #TYPE_SISTER}</li> 4050 * <li>{@link #TYPE_SPOUSE}</li> 4051 * </ul> 4052 * </p> 4053 * </td> 4054 * </tr> 4055 * <tr> 4056 * <td>String</td> 4057 * <td>{@link #LABEL}</td> 4058 * <td>{@link #DATA3}</td> 4059 * <td></td> 4060 * </tr> 4061 * </table> 4062 */ 4063 public static final class Relation implements DataColumnsWithJoins, CommonColumns { 4064 /** 4065 * This utility class cannot be instantiated 4066 */ 4067 private Relation() {} 4068 4069 /** MIME type used when storing this in data table. */ 4070 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/relation"; 4071 4072 public static final int TYPE_ASSISTANT = 1; 4073 public static final int TYPE_BROTHER = 2; 4074 public static final int TYPE_CHILD = 3; 4075 public static final int TYPE_DOMESTIC_PARTNER = 4; 4076 public static final int TYPE_FATHER = 5; 4077 public static final int TYPE_FRIEND = 6; 4078 public static final int TYPE_MANAGER = 7; 4079 public static final int TYPE_MOTHER = 8; 4080 public static final int TYPE_PARENT = 9; 4081 public static final int TYPE_PARTNER = 10; 4082 public static final int TYPE_REFERRED_BY = 11; 4083 public static final int TYPE_RELATIVE = 12; 4084 public static final int TYPE_SISTER = 13; 4085 public static final int TYPE_SPOUSE = 14; 4086 4087 /** 4088 * The name of the relative as the user entered it. 4089 * <P>Type: TEXT</P> 4090 */ 4091 public static final String NAME = DATA; 4092 } 4093 4094 /** 4095 * <p> 4096 * A data kind representing an event. 4097 * </p> 4098 * <p> 4099 * You can use all columns defined for {@link ContactsContract.Data} as 4100 * well as the following aliases. 4101 * </p> 4102 * <h2>Column aliases</h2> 4103 * <table class="jd-sumtable"> 4104 * <tr> 4105 * <th>Type</th> 4106 * <th>Alias</th><th colspan='2'>Data column</th> 4107 * </tr> 4108 * <tr> 4109 * <td>String</td> 4110 * <td>{@link #START_DATE}</td> 4111 * <td>{@link #DATA1}</td> 4112 * <td></td> 4113 * </tr> 4114 * <tr> 4115 * <td>int</td> 4116 * <td>{@link #TYPE}</td> 4117 * <td>{@link #DATA2}</td> 4118 * <td>Allowed values are: 4119 * <p> 4120 * <ul> 4121 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 4122 * <li>{@link #TYPE_ANNIVERSARY}</li> 4123 * <li>{@link #TYPE_OTHER}</li> 4124 * <li>{@link #TYPE_BIRTHDAY}</li> 4125 * </ul> 4126 * </p> 4127 * </td> 4128 * </tr> 4129 * <tr> 4130 * <td>String</td> 4131 * <td>{@link #LABEL}</td> 4132 * <td>{@link #DATA3}</td> 4133 * <td></td> 4134 * </tr> 4135 * </table> 4136 */ 4137 public static final class Event implements DataColumnsWithJoins, CommonColumns { 4138 /** 4139 * This utility class cannot be instantiated 4140 */ 4141 private Event() {} 4142 4143 /** MIME type used when storing this in data table. */ 4144 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contact_event"; 4145 4146 public static final int TYPE_ANNIVERSARY = 1; 4147 public static final int TYPE_OTHER = 2; 4148 public static final int TYPE_BIRTHDAY = 3; 4149 4150 /** 4151 * The event start date as the user entered it. 4152 * <P>Type: TEXT</P> 4153 */ 4154 public static final String START_DATE = DATA; 4155 4156 /** 4157 * Return the string resource that best describes the given 4158 * {@link #TYPE}. Will always return a valid resource. 4159 */ 4160 public static int getTypeResource(Integer type) { 4161 if (type == null) { 4162 return com.android.internal.R.string.eventTypeOther; 4163 } 4164 switch (type) { 4165 case TYPE_ANNIVERSARY: 4166 return com.android.internal.R.string.eventTypeAnniversary; 4167 case TYPE_BIRTHDAY: return com.android.internal.R.string.eventTypeBirthday; 4168 case TYPE_OTHER: return com.android.internal.R.string.eventTypeOther; 4169 default: return com.android.internal.R.string.eventTypeOther; 4170 } 4171 } 4172 } 4173 4174 /** 4175 * <p> 4176 * A data kind representing an photo for the contact. 4177 * </p> 4178 * <p> 4179 * Some sync adapters will choose to download photos in a separate 4180 * pass. A common pattern is to use columns {@link ContactsContract.Data#SYNC1} 4181 * through {@link ContactsContract.Data#SYNC4} to store temporary 4182 * data, e.g. the image URL or ID, state of download, server-side version 4183 * of the image. It is allowed for the {@link #PHOTO} to be null. 4184 * </p> 4185 * <p> 4186 * You can use all columns defined for {@link ContactsContract.Data} as 4187 * well as the following aliases. 4188 * </p> 4189 * <h2>Column aliases</h2> 4190 * <table class="jd-sumtable"> 4191 * <tr> 4192 * <th>Type</th> 4193 * <th>Alias</th><th colspan='2'>Data column</th> 4194 * </tr> 4195 * <tr> 4196 * <td>BLOB</td> 4197 * <td>{@link #PHOTO}</td> 4198 * <td>{@link #DATA15}</td> 4199 * <td>By convention, binary data is stored in DATA15.</td> 4200 * </tr> 4201 * </table> 4202 */ 4203 public static final class Photo implements DataColumnsWithJoins { 4204 /** 4205 * This utility class cannot be instantiated 4206 */ 4207 private Photo() {} 4208 4209 /** MIME type used when storing this in data table. */ 4210 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/photo"; 4211 4212 /** 4213 * Thumbnail photo of the raw contact. This is the raw bytes of an image 4214 * that could be inflated using {@link android.graphics.BitmapFactory}. 4215 * <p> 4216 * Type: BLOB 4217 */ 4218 public static final String PHOTO = DATA15; 4219 } 4220 4221 /** 4222 * <p> 4223 * Notes about the contact. 4224 * </p> 4225 * <p> 4226 * You can use all columns defined for {@link ContactsContract.Data} as 4227 * well as the following aliases. 4228 * </p> 4229 * <h2>Column aliases</h2> 4230 * <table class="jd-sumtable"> 4231 * <tr> 4232 * <th>Type</th> 4233 * <th>Alias</th><th colspan='2'>Data column</th> 4234 * </tr> 4235 * <tr> 4236 * <td>String</td> 4237 * <td>{@link #NOTE}</td> 4238 * <td>{@link #DATA1}</td> 4239 * <td></td> 4240 * </tr> 4241 * </table> 4242 */ 4243 public static final class Note implements DataColumnsWithJoins { 4244 /** 4245 * This utility class cannot be instantiated 4246 */ 4247 private Note() {} 4248 4249 /** MIME type used when storing this in data table. */ 4250 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/note"; 4251 4252 /** 4253 * The note text. 4254 * <P>Type: TEXT</P> 4255 */ 4256 public static final String NOTE = DATA1; 4257 } 4258 4259 /** 4260 * <p> 4261 * Group Membership. 4262 * </p> 4263 * <p> 4264 * You can use all columns defined for {@link ContactsContract.Data} as 4265 * well as the following aliases. 4266 * </p> 4267 * <h2>Column aliases</h2> 4268 * <table class="jd-sumtable"> 4269 * <tr> 4270 * <th>Type</th> 4271 * <th>Alias</th><th colspan='2'>Data column</th> 4272 * </tr> 4273 * <tr> 4274 * <td>long</td> 4275 * <td>{@link #GROUP_ROW_ID}</td> 4276 * <td>{@link #DATA1}</td> 4277 * <td></td> 4278 * </tr> 4279 * <tr> 4280 * <td>String</td> 4281 * <td>{@link #GROUP_SOURCE_ID}</td> 4282 * <td>none</td> 4283 * <td> 4284 * <p> 4285 * The sourceid of the group that this group membership refers to. 4286 * Exactly one of this or {@link #GROUP_ROW_ID} must be set when 4287 * inserting a row. 4288 * </p> 4289 * <p> 4290 * If this field is specified, the provider will first try to 4291 * look up a group with this {@link Groups Groups.SOURCE_ID}. If such a group 4292 * is found, it will use the corresponding row id. If the group is not 4293 * found, it will create one. 4294 * </td> 4295 * </tr> 4296 * </table> 4297 */ 4298 public static final class GroupMembership implements DataColumnsWithJoins { 4299 /** 4300 * This utility class cannot be instantiated 4301 */ 4302 private GroupMembership() {} 4303 4304 /** MIME type used when storing this in data table. */ 4305 public static final String CONTENT_ITEM_TYPE = 4306 "vnd.android.cursor.item/group_membership"; 4307 4308 /** 4309 * The row id of the group that this group membership refers to. Exactly one of 4310 * this or {@link #GROUP_SOURCE_ID} must be set when inserting a row. 4311 * <P>Type: INTEGER</P> 4312 */ 4313 public static final String GROUP_ROW_ID = DATA1; 4314 4315 /** 4316 * The sourceid of the group that this group membership refers to. Exactly one of 4317 * this or {@link #GROUP_ROW_ID} must be set when inserting a row. 4318 * <P>Type: TEXT</P> 4319 */ 4320 public static final String GROUP_SOURCE_ID = "group_sourceid"; 4321 } 4322 4323 /** 4324 * <p> 4325 * A data kind representing a website related to the contact. 4326 * </p> 4327 * <p> 4328 * You can use all columns defined for {@link ContactsContract.Data} as 4329 * well as the following aliases. 4330 * </p> 4331 * <h2>Column aliases</h2> 4332 * <table class="jd-sumtable"> 4333 * <tr> 4334 * <th>Type</th> 4335 * <th>Alias</th><th colspan='2'>Data column</th> 4336 * </tr> 4337 * <tr> 4338 * <td>String</td> 4339 * <td>{@link #URL}</td> 4340 * <td>{@link #DATA1}</td> 4341 * <td></td> 4342 * </tr> 4343 * <tr> 4344 * <td>int</td> 4345 * <td>{@link #TYPE}</td> 4346 * <td>{@link #DATA2}</td> 4347 * <td>Allowed values are: 4348 * <p> 4349 * <ul> 4350 * <li>{@link #TYPE_CUSTOM}. Put the actual type in {@link #LABEL}.</li> 4351 * <li>{@link #TYPE_HOMEPAGE}</li> 4352 * <li>{@link #TYPE_BLOG}</li> 4353 * <li>{@link #TYPE_PROFILE}</li> 4354 * <li>{@link #TYPE_HOME}</li> 4355 * <li>{@link #TYPE_WORK}</li> 4356 * <li>{@link #TYPE_FTP}</li> 4357 * <li>{@link #TYPE_OTHER}</li> 4358 * </ul> 4359 * </p> 4360 * </td> 4361 * </tr> 4362 * <tr> 4363 * <td>String</td> 4364 * <td>{@link #LABEL}</td> 4365 * <td>{@link #DATA3}</td> 4366 * <td></td> 4367 * </tr> 4368 * </table> 4369 */ 4370 public static final class Website implements DataColumnsWithJoins, CommonColumns { 4371 /** 4372 * This utility class cannot be instantiated 4373 */ 4374 private Website() {} 4375 4376 /** MIME type used when storing this in data table. */ 4377 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/website"; 4378 4379 public static final int TYPE_HOMEPAGE = 1; 4380 public static final int TYPE_BLOG = 2; 4381 public static final int TYPE_PROFILE = 3; 4382 public static final int TYPE_HOME = 4; 4383 public static final int TYPE_WORK = 5; 4384 public static final int TYPE_FTP = 6; 4385 public static final int TYPE_OTHER = 7; 4386 4387 /** 4388 * The website URL string. 4389 * <P>Type: TEXT</P> 4390 */ 4391 public static final String URL = DATA; 4392 } 4393 } 4394 4395 /** 4396 * @see Groups 4397 */ 4398 protected interface GroupsColumns { 4399 /** 4400 * The display title of this group. 4401 * <p> 4402 * Type: TEXT 4403 */ 4404 public static final String TITLE = "title"; 4405 4406 /** 4407 * The package name to use when creating {@link Resources} objects for 4408 * this group. This value is only designed for use when building user 4409 * interfaces, and should not be used to infer the owner. 4410 * 4411 * @hide 4412 */ 4413 public static final String RES_PACKAGE = "res_package"; 4414 4415 /** 4416 * The display title of this group to load as a resource from 4417 * {@link #RES_PACKAGE}, which may be localized. 4418 * <P>Type: TEXT</P> 4419 * 4420 * @hide 4421 */ 4422 public static final String TITLE_RES = "title_res"; 4423 4424 /** 4425 * Notes about the group. 4426 * <p> 4427 * Type: TEXT 4428 */ 4429 public static final String NOTES = "notes"; 4430 4431 /** 4432 * The ID of this group if it is a System Group, i.e. a group that has a special meaning 4433 * to the sync adapter, null otherwise. 4434 * <P>Type: TEXT</P> 4435 */ 4436 public static final String SYSTEM_ID = "system_id"; 4437 4438 /** 4439 * The total number of {@link Contacts} that have 4440 * {@link CommonDataKinds.GroupMembership} in this group. Read-only value that is only 4441 * present when querying {@link Groups#CONTENT_SUMMARY_URI}. 4442 * <p> 4443 * Type: INTEGER 4444 */ 4445 public static final String SUMMARY_COUNT = "summ_count"; 4446 4447 /** 4448 * The total number of {@link Contacts} that have both 4449 * {@link CommonDataKinds.GroupMembership} in this group, and also have phone numbers. 4450 * Read-only value that is only present when querying 4451 * {@link Groups#CONTENT_SUMMARY_URI}. 4452 * <p> 4453 * Type: INTEGER 4454 */ 4455 public static final String SUMMARY_WITH_PHONES = "summ_phones"; 4456 4457 /** 4458 * Flag indicating if the contacts belonging to this group should be 4459 * visible in any user interface. 4460 * <p> 4461 * Type: INTEGER (boolean) 4462 */ 4463 public static final String GROUP_VISIBLE = "group_visible"; 4464 4465 /** 4466 * The "deleted" flag: "0" by default, "1" if the row has been marked 4467 * for deletion. When {@link android.content.ContentResolver#delete} is 4468 * called on a group, it is marked for deletion. The sync adaptor 4469 * deletes the group on the server and then calls ContactResolver.delete 4470 * once more, this time setting the the 4471 * {@link ContactsContract#CALLER_IS_SYNCADAPTER} query parameter to 4472 * finalize the data removal. 4473 * <P>Type: INTEGER</P> 4474 */ 4475 public static final String DELETED = "deleted"; 4476 4477 /** 4478 * Whether this group should be synced if the SYNC_EVERYTHING settings 4479 * is false for this group's account. 4480 * <p> 4481 * Type: INTEGER (boolean) 4482 */ 4483 public static final String SHOULD_SYNC = "should_sync"; 4484 } 4485 4486 /** 4487 * Constants for the groups table. Only per-account groups are supported. 4488 * <h2>Columns</h2> 4489 * <table class="jd-sumtable"> 4490 * <tr> 4491 * <th colspan='4'>Groups</th> 4492 * </tr> 4493 * <tr> 4494 * <td>long</td> 4495 * <td>{@link #_ID}</td> 4496 * <td>read-only</td> 4497 * <td>Row ID. Sync adapter should try to preserve row IDs during updates. 4498 * In other words, it would be a really bad idea to delete and reinsert a 4499 * group. A sync adapter should always do an update instead.</td> 4500 * </tr> 4501 * <tr> 4502 * <td>String</td> 4503 * <td>{@link #TITLE}</td> 4504 * <td>read/write</td> 4505 * <td>The display title of this group.</td> 4506 * </tr> 4507 * <tr> 4508 * <td>String</td> 4509 * <td>{@link #NOTES}</td> 4510 * <td>read/write</td> 4511 * <td>Notes about the group.</td> 4512 * </tr> 4513 * <tr> 4514 * <td>String</td> 4515 * <td>{@link #SYSTEM_ID}</td> 4516 * <td>read/write</td> 4517 * <td>The ID of this group if it is a System Group, i.e. a group that has a 4518 * special meaning to the sync adapter, null otherwise.</td> 4519 * </tr> 4520 * <tr> 4521 * <td>int</td> 4522 * <td>{@link #SUMMARY_COUNT}</td> 4523 * <td>read-only</td> 4524 * <td>The total number of {@link Contacts} that have 4525 * {@link CommonDataKinds.GroupMembership} in this group. Read-only value 4526 * that is only present when querying {@link Groups#CONTENT_SUMMARY_URI}.</td> 4527 * </tr> 4528 * <tr> 4529 * <td>int</td> 4530 * <td>{@link #SUMMARY_WITH_PHONES}</td> 4531 * <td>read-only</td> 4532 * <td>The total number of {@link Contacts} that have both 4533 * {@link CommonDataKinds.GroupMembership} in this group, and also have 4534 * phone numbers. Read-only value that is only present when querying 4535 * {@link Groups#CONTENT_SUMMARY_URI}.</td> 4536 * </tr> 4537 * <tr> 4538 * <td>int</td> 4539 * <td>{@link #GROUP_VISIBLE}</td> 4540 * <td>read-only</td> 4541 * <td>Flag indicating if the contacts belonging to this group should be 4542 * visible in any user interface. Allowed values: 0 and 1.</td> 4543 * </tr> 4544 * <tr> 4545 * <td>int</td> 4546 * <td>{@link #DELETED}</td> 4547 * <td>read/write</td> 4548 * <td>The "deleted" flag: "0" by default, "1" if the row has been marked 4549 * for deletion. When {@link android.content.ContentResolver#delete} is 4550 * called on a group, it is marked for deletion. The sync adaptor deletes 4551 * the group on the server and then calls ContactResolver.delete once more, 4552 * this time setting the the {@link ContactsContract#CALLER_IS_SYNCADAPTER} 4553 * query parameter to finalize the data removal.</td> 4554 * </tr> 4555 * <tr> 4556 * <td>int</td> 4557 * <td>{@link #SHOULD_SYNC}</td> 4558 * <td>read/write</td> 4559 * <td>Whether this group should be synced if the SYNC_EVERYTHING settings 4560 * is false for this group's account.</td> 4561 * </tr> 4562 * </table> 4563 */ 4564 public static final class Groups implements BaseColumns, GroupsColumns, SyncColumns { 4565 /** 4566 * This utility class cannot be instantiated 4567 */ 4568 private Groups() { 4569 } 4570 4571 /** 4572 * The content:// style URI for this table 4573 */ 4574 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "groups"); 4575 4576 /** 4577 * The content:// style URI for this table joined with details data from 4578 * {@link ContactsContract.Data}. 4579 */ 4580 public static final Uri CONTENT_SUMMARY_URI = Uri.withAppendedPath(AUTHORITY_URI, 4581 "groups_summary"); 4582 4583 /** 4584 * The MIME type of a directory of groups. 4585 */ 4586 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/group"; 4587 4588 /** 4589 * The MIME type of a single group. 4590 */ 4591 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/group"; 4592 4593 public static EntityIterator newEntityIterator(Cursor cursor) { 4594 return new EntityIteratorImpl(cursor); 4595 } 4596 4597 private static class EntityIteratorImpl extends CursorEntityIterator { 4598 public EntityIteratorImpl(Cursor cursor) { 4599 super(cursor); 4600 } 4601 4602 public Entity getEntityAndIncrementCursor(Cursor cursor) throws RemoteException { 4603 // we expect the cursor is already at the row we need to read from 4604 final ContentValues values = new ContentValues(); 4605 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, _ID); 4606 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, ACCOUNT_NAME); 4607 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, ACCOUNT_TYPE); 4608 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, DIRTY); 4609 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, VERSION); 4610 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SOURCE_ID); 4611 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, RES_PACKAGE); 4612 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, TITLE); 4613 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, TITLE_RES); 4614 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, GROUP_VISIBLE); 4615 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC1); 4616 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC2); 4617 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC3); 4618 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYNC4); 4619 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SYSTEM_ID); 4620 DatabaseUtils.cursorLongToContentValuesIfPresent(cursor, values, DELETED); 4621 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, NOTES); 4622 DatabaseUtils.cursorStringToContentValuesIfPresent(cursor, values, SHOULD_SYNC); 4623 cursor.moveToNext(); 4624 return new Entity(values); 4625 } 4626 } 4627 } 4628 4629 /** 4630 * <p> 4631 * Constants for the contact aggregation exceptions table, which contains 4632 * aggregation rules overriding those used by automatic aggregation. This 4633 * type only supports query and update. Neither insert nor delete are 4634 * supported. 4635 * </p> 4636 * <h2>Columns</h2> 4637 * <table class="jd-sumtable"> 4638 * <tr> 4639 * <th colspan='4'>AggregationExceptions</th> 4640 * </tr> 4641 * <tr> 4642 * <td>int</td> 4643 * <td>{@link #TYPE}</td> 4644 * <td>read/write</td> 4645 * <td>The type of exception: {@link #TYPE_KEEP_TOGETHER}, 4646 * {@link #TYPE_KEEP_SEPARATE} or {@link #TYPE_AUTOMATIC}.</td> 4647 * </tr> 4648 * <tr> 4649 * <td>long</td> 4650 * <td>{@link #RAW_CONTACT_ID1}</td> 4651 * <td>read/write</td> 4652 * <td>A reference to the {@link RawContacts#_ID} of the raw contact that 4653 * the rule applies to.</td> 4654 * </tr> 4655 * <tr> 4656 * <td>long</td> 4657 * <td>{@link #RAW_CONTACT_ID2}</td> 4658 * <td>read/write</td> 4659 * <td>A reference to the other {@link RawContacts#_ID} of the raw contact 4660 * that the rule applies to.</td> 4661 * </tr> 4662 * </table> 4663 */ 4664 public static final class AggregationExceptions implements BaseColumns { 4665 /** 4666 * This utility class cannot be instantiated 4667 */ 4668 private AggregationExceptions() {} 4669 4670 /** 4671 * The content:// style URI for this table 4672 */ 4673 public static final Uri CONTENT_URI = 4674 Uri.withAppendedPath(AUTHORITY_URI, "aggregation_exceptions"); 4675 4676 /** 4677 * The MIME type of {@link #CONTENT_URI} providing a directory of data. 4678 */ 4679 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/aggregation_exception"; 4680 4681 /** 4682 * The MIME type of a {@link #CONTENT_URI} subdirectory of an aggregation exception 4683 */ 4684 public static final String CONTENT_ITEM_TYPE = 4685 "vnd.android.cursor.item/aggregation_exception"; 4686 4687 /** 4688 * The type of exception: {@link #TYPE_KEEP_TOGETHER}, {@link #TYPE_KEEP_SEPARATE} or 4689 * {@link #TYPE_AUTOMATIC}. 4690 * 4691 * <P>Type: INTEGER</P> 4692 */ 4693 public static final String TYPE = "type"; 4694 4695 /** 4696 * Allows the provider to automatically decide whether the specified raw contacts should 4697 * be included in the same aggregate contact or not. 4698 */ 4699 public static final int TYPE_AUTOMATIC = 0; 4700 4701 /** 4702 * Makes sure that the specified raw contacts are included in the same 4703 * aggregate contact. 4704 */ 4705 public static final int TYPE_KEEP_TOGETHER = 1; 4706 4707 /** 4708 * Makes sure that the specified raw contacts are NOT included in the same 4709 * aggregate contact. 4710 */ 4711 public static final int TYPE_KEEP_SEPARATE = 2; 4712 4713 /** 4714 * A reference to the {@link RawContacts#_ID} of the raw contact that the rule applies to. 4715 */ 4716 public static final String RAW_CONTACT_ID1 = "raw_contact_id1"; 4717 4718 /** 4719 * A reference to the other {@link RawContacts#_ID} of the raw contact that the rule 4720 * applies to. 4721 */ 4722 public static final String RAW_CONTACT_ID2 = "raw_contact_id2"; 4723 } 4724 4725 /** 4726 * @see Settings 4727 */ 4728 protected interface SettingsColumns { 4729 /** 4730 * The name of the account instance to which this row belongs. 4731 * <P>Type: TEXT</P> 4732 */ 4733 public static final String ACCOUNT_NAME = "account_name"; 4734 4735 /** 4736 * The type of account to which this row belongs, which when paired with 4737 * {@link #ACCOUNT_NAME} identifies a specific account. 4738 * <P>Type: TEXT</P> 4739 */ 4740 public static final String ACCOUNT_TYPE = "account_type"; 4741 4742 /** 4743 * Depending on the mode defined by the sync-adapter, this flag controls 4744 * the top-level sync behavior for this data source. 4745 * <p> 4746 * Type: INTEGER (boolean) 4747 */ 4748 public static final String SHOULD_SYNC = "should_sync"; 4749 4750 /** 4751 * Flag indicating if contacts without any {@link CommonDataKinds.GroupMembership} 4752 * entries should be visible in any user interface. 4753 * <p> 4754 * Type: INTEGER (boolean) 4755 */ 4756 public static final String UNGROUPED_VISIBLE = "ungrouped_visible"; 4757 4758 /** 4759 * Read-only flag indicating if this {@link #SHOULD_SYNC} or any 4760 * {@link Groups#SHOULD_SYNC} under this account have been marked as 4761 * unsynced. 4762 */ 4763 public static final String ANY_UNSYNCED = "any_unsynced"; 4764 4765 /** 4766 * Read-only count of {@link Contacts} from a specific source that have 4767 * no {@link CommonDataKinds.GroupMembership} entries. 4768 * <p> 4769 * Type: INTEGER 4770 */ 4771 public static final String UNGROUPED_COUNT = "summ_count"; 4772 4773 /** 4774 * Read-only count of {@link Contacts} from a specific source that have 4775 * no {@link CommonDataKinds.GroupMembership} entries, and also have phone numbers. 4776 * <p> 4777 * Type: INTEGER 4778 */ 4779 public static final String UNGROUPED_WITH_PHONES = "summ_phones"; 4780 } 4781 4782 /** 4783 * <p> 4784 * Contacts-specific settings for various {@link Account}'s. 4785 * </p> 4786 * <h2>Columns</h2> 4787 * <table class="jd-sumtable"> 4788 * <tr> 4789 * <th colspan='4'>Settings</th> 4790 * </tr> 4791 * <tr> 4792 * <td>String</td> 4793 * <td>{@link #ACCOUNT_NAME}</td> 4794 * <td>read/write-once</td> 4795 * <td>The name of the account instance to which this row belongs.</td> 4796 * </tr> 4797 * <tr> 4798 * <td>String</td> 4799 * <td>{@link #ACCOUNT_TYPE}</td> 4800 * <td>read/write-once</td> 4801 * <td>The type of account to which this row belongs, which when paired with 4802 * {@link #ACCOUNT_NAME} identifies a specific account.</td> 4803 * </tr> 4804 * <tr> 4805 * <td>int</td> 4806 * <td>{@link #SHOULD_SYNC}</td> 4807 * <td>read/write</td> 4808 * <td>Depending on the mode defined by the sync-adapter, this flag controls 4809 * the top-level sync behavior for this data source.</td> 4810 * </tr> 4811 * <tr> 4812 * <td>int</td> 4813 * <td>{@link #UNGROUPED_VISIBLE}</td> 4814 * <td>read/write</td> 4815 * <td>Flag indicating if contacts without any 4816 * {@link CommonDataKinds.GroupMembership} entries should be visible in any 4817 * user interface.</td> 4818 * </tr> 4819 * <tr> 4820 * <td>int</td> 4821 * <td>{@link #ANY_UNSYNCED}</td> 4822 * <td>read-only</td> 4823 * <td>Read-only flag indicating if this {@link #SHOULD_SYNC} or any 4824 * {@link Groups#SHOULD_SYNC} under this account have been marked as 4825 * unsynced.</td> 4826 * </tr> 4827 * <tr> 4828 * <td>int</td> 4829 * <td>{@link #UNGROUPED_COUNT}</td> 4830 * <td>read-only</td> 4831 * <td>Read-only count of {@link Contacts} from a specific source that have 4832 * no {@link CommonDataKinds.GroupMembership} entries.</td> 4833 * </tr> 4834 * <tr> 4835 * <td>int</td> 4836 * <td>{@link #UNGROUPED_WITH_PHONES}</td> 4837 * <td>read-only</td> 4838 * <td>Read-only count of {@link Contacts} from a specific source that have 4839 * no {@link CommonDataKinds.GroupMembership} entries, and also have phone 4840 * numbers.</td> 4841 * </tr> 4842 * </table> 4843 */ 4844 4845 public static final class Settings implements SettingsColumns { 4846 /** 4847 * This utility class cannot be instantiated 4848 */ 4849 private Settings() { 4850 } 4851 4852 /** 4853 * The content:// style URI for this table 4854 */ 4855 public static final Uri CONTENT_URI = 4856 Uri.withAppendedPath(AUTHORITY_URI, "settings"); 4857 4858 /** 4859 * The MIME-type of {@link #CONTENT_URI} providing a directory of 4860 * settings. 4861 */ 4862 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/setting"; 4863 4864 /** 4865 * The MIME-type of {@link #CONTENT_URI} providing a single setting. 4866 */ 4867 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/setting"; 4868 } 4869 4870 /** 4871 * Helper methods to display QuickContact dialogs that allow users to pivot on 4872 * a specific {@link Contacts} entry. 4873 */ 4874 public static final class QuickContact { 4875 /** 4876 * Action used to trigger person pivot dialog. 4877 * @hide 4878 */ 4879 public static final String ACTION_QUICK_CONTACT = 4880 "com.android.contacts.action.QUICK_CONTACT"; 4881 4882 /** 4883 * Extra used to specify pivot dialog location in screen coordinates. 4884 * @hide 4885 */ 4886 public static final String EXTRA_TARGET_RECT = "target_rect"; 4887 4888 /** 4889 * Extra used to specify size of pivot dialog. 4890 * @hide 4891 */ 4892 public static final String EXTRA_MODE = "mode"; 4893 4894 /** 4895 * Extra used to indicate a list of specific MIME-types to exclude and 4896 * not display. Stored as a {@link String} array. 4897 * @hide 4898 */ 4899 public static final String EXTRA_EXCLUDE_MIMES = "exclude_mimes"; 4900 4901 /** 4902 * Small QuickContact mode, usually presented with minimal actions. 4903 */ 4904 public static final int MODE_SMALL = 1; 4905 4906 /** 4907 * Medium QuickContact mode, includes actions and light summary describing 4908 * the {@link Contacts} entry being shown. This may include social 4909 * status and presence details. 4910 */ 4911 public static final int MODE_MEDIUM = 2; 4912 4913 /** 4914 * Large QuickContact mode, includes actions and larger, card-like summary 4915 * of the {@link Contacts} entry being shown. This may include detailed 4916 * information, such as a photo. 4917 */ 4918 public static final int MODE_LARGE = 3; 4919 4920 /** 4921 * Trigger a dialog that lists the various methods of interacting with 4922 * the requested {@link Contacts} entry. This may be based on available 4923 * {@link ContactsContract.Data} rows under that contact, and may also 4924 * include social status and presence details. 4925 * 4926 * @param context The parent {@link Context} that may be used as the 4927 * parent for this dialog. 4928 * @param target Specific {@link View} from your layout that this dialog 4929 * should be centered around. In particular, if the dialog 4930 * has a "callout" arrow, it will be pointed and centered 4931 * around this {@link View}. 4932 * @param lookupUri A {@link ContactsContract.Contacts#CONTENT_LOOKUP_URI} style 4933 * {@link Uri} that describes a specific contact to feature 4934 * in this dialog. 4935 * @param mode Any of {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or 4936 * {@link #MODE_LARGE}, indicating the desired dialog size, 4937 * when supported. 4938 * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types 4939 * to exclude when showing this dialog. For example, when 4940 * already viewing the contact details card, this can be used 4941 * to omit the details entry from the dialog. 4942 */ 4943 public static void showQuickContact(Context context, View target, Uri lookupUri, int mode, 4944 String[] excludeMimes) { 4945 // Find location and bounds of target view 4946 final int[] location = new int[2]; 4947 target.getLocationOnScreen(location); 4948 4949 final Rect rect = new Rect(); 4950 rect.left = location[0]; 4951 rect.top = location[1]; 4952 rect.right = rect.left + target.getWidth(); 4953 rect.bottom = rect.top + target.getHeight(); 4954 4955 // Trigger with obtained rectangle 4956 showQuickContact(context, rect, lookupUri, mode, excludeMimes); 4957 } 4958 4959 /** 4960 * Trigger a dialog that lists the various methods of interacting with 4961 * the requested {@link Contacts} entry. This may be based on available 4962 * {@link ContactsContract.Data} rows under that contact, and may also 4963 * include social status and presence details. 4964 * 4965 * @param context The parent {@link Context} that may be used as the 4966 * parent for this dialog. 4967 * @param target Specific {@link Rect} that this dialog should be 4968 * centered around, in screen coordinates. In particular, if 4969 * the dialog has a "callout" arrow, it will be pointed and 4970 * centered around this {@link Rect}. 4971 * @param lookupUri A {@link ContactsContract.Contacts#CONTENT_LOOKUP_URI} style 4972 * {@link Uri} that describes a specific contact to feature 4973 * in this dialog. 4974 * @param mode Any of {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or 4975 * {@link #MODE_LARGE}, indicating the desired dialog size, 4976 * when supported. 4977 * @param excludeMimes Optional list of {@link Data#MIMETYPE} MIME-types 4978 * to exclude when showing this dialog. For example, when 4979 * already viewing the contact details card, this can be used 4980 * to omit the details entry from the dialog. 4981 */ 4982 public static void showQuickContact(Context context, Rect target, Uri lookupUri, int mode, 4983 String[] excludeMimes) { 4984 // Launch pivot dialog through intent for now 4985 final Intent intent = new Intent(ACTION_QUICK_CONTACT); 4986 intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP 4987 | Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED); 4988 4989 intent.setData(lookupUri); 4990 intent.putExtra(EXTRA_TARGET_RECT, target); 4991 intent.putExtra(EXTRA_MODE, mode); 4992 intent.putExtra(EXTRA_EXCLUDE_MIMES, excludeMimes); 4993 context.startActivity(intent); 4994 } 4995 } 4996 4997 /** 4998 * Contains helper classes used to create or manage {@link android.content.Intent Intents} 4999 * that involve contacts. 5000 */ 5001 public static final class Intents { 5002 /** 5003 * This is the intent that is fired when a search suggestion is clicked on. 5004 */ 5005 public static final String SEARCH_SUGGESTION_CLICKED = 5006 "android.provider.Contacts.SEARCH_SUGGESTION_CLICKED"; 5007 5008 /** 5009 * This is the intent that is fired when a search suggestion for dialing a number 5010 * is clicked on. 5011 */ 5012 public static final String SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED = 5013 "android.provider.Contacts.SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED"; 5014 5015 /** 5016 * This is the intent that is fired when a search suggestion for creating a contact 5017 * is clicked on. 5018 */ 5019 public static final String SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED = 5020 "android.provider.Contacts.SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED"; 5021 5022 /** 5023 * Starts an Activity that lets the user pick a contact to attach an image to. 5024 * After picking the contact it launches the image cropper in face detection mode. 5025 */ 5026 public static final String ATTACH_IMAGE = 5027 "com.android.contacts.action.ATTACH_IMAGE"; 5028 5029 /** 5030 * Takes as input a data URI with a mailto: or tel: scheme. If a single 5031 * contact exists with the given data it will be shown. If no contact 5032 * exists, a dialog will ask the user if they want to create a new 5033 * contact with the provided details filled in. If multiple contacts 5034 * share the data the user will be prompted to pick which contact they 5035 * want to view. 5036 * <p> 5037 * For <code>mailto:</code> URIs, the scheme specific portion must be a 5038 * raw email address, such as one built using 5039 * {@link Uri#fromParts(String, String, String)}. 5040 * <p> 5041 * For <code>tel:</code> URIs, the scheme specific portion is compared 5042 * to existing numbers using the standard caller ID lookup algorithm. 5043 * The number must be properly encoded, for example using 5044 * {@link Uri#fromParts(String, String, String)}. 5045 * <p> 5046 * Any extras from the {@link Insert} class will be passed along to the 5047 * create activity if there are no contacts to show. 5048 * <p> 5049 * Passing true for the {@link #EXTRA_FORCE_CREATE} extra will skip 5050 * prompting the user when the contact doesn't exist. 5051 */ 5052 public static final String SHOW_OR_CREATE_CONTACT = 5053 "com.android.contacts.action.SHOW_OR_CREATE_CONTACT"; 5054 5055 /** 5056 * Used with {@link #SHOW_OR_CREATE_CONTACT} to force creating a new 5057 * contact if no matching contact found. Otherwise, default behavior is 5058 * to prompt user with dialog before creating. 5059 * <p> 5060 * Type: BOOLEAN 5061 */ 5062 public static final String EXTRA_FORCE_CREATE = 5063 "com.android.contacts.action.FORCE_CREATE"; 5064 5065 /** 5066 * Used with {@link #SHOW_OR_CREATE_CONTACT} to specify an exact 5067 * description to be shown when prompting user about creating a new 5068 * contact. 5069 * <p> 5070 * Type: STRING 5071 */ 5072 public static final String EXTRA_CREATE_DESCRIPTION = 5073 "com.android.contacts.action.CREATE_DESCRIPTION"; 5074 5075 /** 5076 * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to specify a 5077 * dialog location using screen coordinates. When not specified, the 5078 * dialog will be centered. 5079 * 5080 * @hide 5081 */ 5082 @Deprecated 5083 public static final String EXTRA_TARGET_RECT = "target_rect"; 5084 5085 /** 5086 * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to specify a 5087 * desired dialog style, usually a variation on size. One of 5088 * {@link #MODE_SMALL}, {@link #MODE_MEDIUM}, or {@link #MODE_LARGE}. 5089 * 5090 * @hide 5091 */ 5092 @Deprecated 5093 public static final String EXTRA_MODE = "mode"; 5094 5095 /** 5096 * Value for {@link #EXTRA_MODE} to show a small-sized dialog. 5097 * 5098 * @hide 5099 */ 5100 @Deprecated 5101 public static final int MODE_SMALL = 1; 5102 5103 /** 5104 * Value for {@link #EXTRA_MODE} to show a medium-sized dialog. 5105 * 5106 * @hide 5107 */ 5108 @Deprecated 5109 public static final int MODE_MEDIUM = 2; 5110 5111 /** 5112 * Value for {@link #EXTRA_MODE} to show a large-sized dialog. 5113 * 5114 * @hide 5115 */ 5116 @Deprecated 5117 public static final int MODE_LARGE = 3; 5118 5119 /** 5120 * Optional extra used with {@link #SHOW_OR_CREATE_CONTACT} to indicate 5121 * a list of specific MIME-types to exclude and not display. Stored as a 5122 * {@link String} array. 5123 * 5124 * @hide 5125 */ 5126 @Deprecated 5127 public static final String EXTRA_EXCLUDE_MIMES = "exclude_mimes"; 5128 5129 /** 5130 * Intents related to the Contacts app UI. 5131 * 5132 * @hide 5133 */ 5134 public static final class UI { 5135 /** 5136 * The action for the default contacts list tab. 5137 */ 5138 public static final String LIST_DEFAULT = 5139 "com.android.contacts.action.LIST_DEFAULT"; 5140 5141 /** 5142 * The action for the contacts list tab. 5143 */ 5144 public static final String LIST_GROUP_ACTION = 5145 "com.android.contacts.action.LIST_GROUP"; 5146 5147 /** 5148 * When in LIST_GROUP_ACTION mode, this is the group to display. 5149 */ 5150 public static final String GROUP_NAME_EXTRA_KEY = "com.android.contacts.extra.GROUP"; 5151 5152 /** 5153 * The action for the all contacts list tab. 5154 */ 5155 public static final String LIST_ALL_CONTACTS_ACTION = 5156 "com.android.contacts.action.LIST_ALL_CONTACTS"; 5157 5158 /** 5159 * The action for the contacts with phone numbers list tab. 5160 */ 5161 public static final String LIST_CONTACTS_WITH_PHONES_ACTION = 5162 "com.android.contacts.action.LIST_CONTACTS_WITH_PHONES"; 5163 5164 /** 5165 * The action for the starred contacts list tab. 5166 */ 5167 public static final String LIST_STARRED_ACTION = 5168 "com.android.contacts.action.LIST_STARRED"; 5169 5170 /** 5171 * The action for the frequent contacts list tab. 5172 */ 5173 public static final String LIST_FREQUENT_ACTION = 5174 "com.android.contacts.action.LIST_FREQUENT"; 5175 5176 /** 5177 * The action for the "strequent" contacts list tab. It first lists the starred 5178 * contacts in alphabetical order and then the frequent contacts in descending 5179 * order of the number of times they have been contacted. 5180 */ 5181 public static final String LIST_STREQUENT_ACTION = 5182 "com.android.contacts.action.LIST_STREQUENT"; 5183 5184 /** 5185 * A key for to be used as an intent extra to set the activity 5186 * title to a custom String value. 5187 */ 5188 public static final String TITLE_EXTRA_KEY = 5189 "com.android.contacts.extra.TITLE_EXTRA"; 5190 5191 /** 5192 * Activity Action: Display a filtered list of contacts 5193 * <p> 5194 * Input: Extra field {@link #FILTER_TEXT_EXTRA_KEY} is the text to use for 5195 * filtering 5196 * <p> 5197 * Output: Nothing. 5198 */ 5199 public static final String FILTER_CONTACTS_ACTION = 5200 "com.android.contacts.action.FILTER_CONTACTS"; 5201 5202 /** 5203 * Used as an int extra field in {@link #FILTER_CONTACTS_ACTION} 5204 * intents to supply the text on which to filter. 5205 */ 5206 public static final String FILTER_TEXT_EXTRA_KEY = 5207 "com.android.contacts.extra.FILTER_TEXT"; 5208 } 5209 5210 /** 5211 * Convenience class that contains string constants used 5212 * to create contact {@link android.content.Intent Intents}. 5213 */ 5214 public static final class Insert { 5215 /** The action code to use when adding a contact */ 5216 public static final String ACTION = Intent.ACTION_INSERT; 5217 5218 /** 5219 * If present, forces a bypass of quick insert mode. 5220 */ 5221 public static final String FULL_MODE = "full_mode"; 5222 5223 /** 5224 * The extra field for the contact name. 5225 * <P>Type: String</P> 5226 */ 5227 public static final String NAME = "name"; 5228 5229 // TODO add structured name values here. 5230 5231 /** 5232 * The extra field for the contact phonetic name. 5233 * <P>Type: String</P> 5234 */ 5235 public static final String PHONETIC_NAME = "phonetic_name"; 5236 5237 /** 5238 * The extra field for the contact company. 5239 * <P>Type: String</P> 5240 */ 5241 public static final String COMPANY = "company"; 5242 5243 /** 5244 * The extra field for the contact job title. 5245 * <P>Type: String</P> 5246 */ 5247 public static final String JOB_TITLE = "job_title"; 5248 5249 /** 5250 * The extra field for the contact notes. 5251 * <P>Type: String</P> 5252 */ 5253 public static final String NOTES = "notes"; 5254 5255 /** 5256 * The extra field for the contact phone number. 5257 * <P>Type: String</P> 5258 */ 5259 public static final String PHONE = "phone"; 5260 5261 /** 5262 * The extra field for the contact phone number type. 5263 * <P>Type: Either an integer value from 5264 * {@link CommonDataKinds.Phone}, 5265 * or a string specifying a custom label.</P> 5266 */ 5267 public static final String PHONE_TYPE = "phone_type"; 5268 5269 /** 5270 * The extra field for the phone isprimary flag. 5271 * <P>Type: boolean</P> 5272 */ 5273 public static final String PHONE_ISPRIMARY = "phone_isprimary"; 5274 5275 /** 5276 * The extra field for an optional second contact phone number. 5277 * <P>Type: String</P> 5278 */ 5279 public static final String SECONDARY_PHONE = "secondary_phone"; 5280 5281 /** 5282 * The extra field for an optional second contact phone number type. 5283 * <P>Type: Either an integer value from 5284 * {@link CommonDataKinds.Phone}, 5285 * or a string specifying a custom label.</P> 5286 */ 5287 public static final String SECONDARY_PHONE_TYPE = "secondary_phone_type"; 5288 5289 /** 5290 * The extra field for an optional third contact phone number. 5291 * <P>Type: String</P> 5292 */ 5293 public static final String TERTIARY_PHONE = "tertiary_phone"; 5294 5295 /** 5296 * The extra field for an optional third contact phone number type. 5297 * <P>Type: Either an integer value from 5298 * {@link CommonDataKinds.Phone}, 5299 * or a string specifying a custom label.</P> 5300 */ 5301 public static final String TERTIARY_PHONE_TYPE = "tertiary_phone_type"; 5302 5303 /** 5304 * The extra field for the contact email address. 5305 * <P>Type: String</P> 5306 */ 5307 public static final String EMAIL = "email"; 5308 5309 /** 5310 * The extra field for the contact email type. 5311 * <P>Type: Either an integer value from 5312 * {@link CommonDataKinds.Email} 5313 * or a string specifying a custom label.</P> 5314 */ 5315 public static final String EMAIL_TYPE = "email_type"; 5316 5317 /** 5318 * The extra field for the email isprimary flag. 5319 * <P>Type: boolean</P> 5320 */ 5321 public static final String EMAIL_ISPRIMARY = "email_isprimary"; 5322 5323 /** 5324 * The extra field for an optional second contact email address. 5325 * <P>Type: String</P> 5326 */ 5327 public static final String SECONDARY_EMAIL = "secondary_email"; 5328 5329 /** 5330 * The extra field for an optional second contact email type. 5331 * <P>Type: Either an integer value from 5332 * {@link CommonDataKinds.Email} 5333 * or a string specifying a custom label.</P> 5334 */ 5335 public static final String SECONDARY_EMAIL_TYPE = "secondary_email_type"; 5336 5337 /** 5338 * The extra field for an optional third contact email address. 5339 * <P>Type: String</P> 5340 */ 5341 public static final String TERTIARY_EMAIL = "tertiary_email"; 5342 5343 /** 5344 * The extra field for an optional third contact email type. 5345 * <P>Type: Either an integer value from 5346 * {@link CommonDataKinds.Email} 5347 * or a string specifying a custom label.</P> 5348 */ 5349 public static final String TERTIARY_EMAIL_TYPE = "tertiary_email_type"; 5350 5351 /** 5352 * The extra field for the contact postal address. 5353 * <P>Type: String</P> 5354 */ 5355 public static final String POSTAL = "postal"; 5356 5357 /** 5358 * The extra field for the contact postal address type. 5359 * <P>Type: Either an integer value from 5360 * {@link CommonDataKinds.StructuredPostal} 5361 * or a string specifying a custom label.</P> 5362 */ 5363 public static final String POSTAL_TYPE = "postal_type"; 5364 5365 /** 5366 * The extra field for the postal isprimary flag. 5367 * <P>Type: boolean</P> 5368 */ 5369 public static final String POSTAL_ISPRIMARY = "postal_isprimary"; 5370 5371 /** 5372 * The extra field for an IM handle. 5373 * <P>Type: String</P> 5374 */ 5375 public static final String IM_HANDLE = "im_handle"; 5376 5377 /** 5378 * The extra field for the IM protocol 5379 */ 5380 public static final String IM_PROTOCOL = "im_protocol"; 5381 5382 /** 5383 * The extra field for the IM isprimary flag. 5384 * <P>Type: boolean</P> 5385 */ 5386 public static final String IM_ISPRIMARY = "im_isprimary"; 5387 } 5388 } 5389 5390} 5391