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