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