ContactsContract.java revision 57ac3d59c139ebc7d5ef470cbfb8bd315eff7a3e
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.content.Intent; 20import android.graphics.BitmapFactory; 21import android.net.Uri; 22 23/** 24 * The contract between the contacts provider and applications. Contains definitions 25 * for the supported URIs and columns. 26 * 27 * @hide 28 */ 29public final class ContactsContract { 30 /** The authority for the contacts provider */ 31 public static final String AUTHORITY = "com.android.contacts"; 32 /** A content:// style uri to the authority for the contacts provider */ 33 public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY); 34 35 public interface AccountsColumns { 36 /** 37 * The name of this account data 38 * <P>Type: TEXT</P> 39 */ 40 public static final String NAME = "name"; 41 /** 42 * The name of this account data 43 * <P>Type: TEXT</P> 44 */ 45 public static final String TYPE = "type"; 46 /** 47 * The name of this account data 48 * <P>Type: TEXT</P> 49 */ 50 public static final String DATA1 = "data1"; 51 52 /** 53 * The value for this account data 54 * <P>Type: INTEGER</P> 55 */ 56 public static final String DATA2 = "data2"; 57 58 /** 59 * The value for this account data 60 * <P>Type: INTEGER</P> 61 */ 62 public static final String DATA3 = "data3"; 63 64 /** 65 * The value for this account data 66 * <P>Type: INTEGER</P> 67 */ 68 public static final String DATA4 = "data4"; 69 70 /** 71 * The value for this account data 72 * <P>Type: INTEGER</P> 73 */ 74 public static final String DATA5 = "data5"; 75 } 76 77 /** 78 * Constants for the aggregates table, which contains a record per group 79 * of contact representing the same person. 80 */ 81 public static final class Accounts implements BaseColumns, AccountsColumns { 82 /** 83 * This utility class cannot be instantiated 84 */ 85 private Accounts() {} 86 87 /** 88 * The content:// style URI for this table 89 */ 90 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "accounts"); 91 92 /** 93 * The MIME type of {@link #CONTENT_URI} providing a directory of 94 * account data. 95 */ 96 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/contacts_account"; 97 98 /** 99 * The MIME type of a {@link #CONTENT_URI} subdirectory of a account 100 */ 101 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contacts_account"; 102 } 103 104 public interface AggregatesColumns { 105 /** 106 * The display name for the contact. 107 * <P>Type: TEXT</P> 108 */ 109 public static final String DISPLAY_NAME = "display_name"; 110 111 /** 112 * The number of times a person has been contacted 113 * <P>Type: INTEGER</P> 114 */ 115 public static final String TIMES_CONTACTED = "times_contacted"; 116 117 /** 118 * The last time a person was contacted. 119 * <P>Type: INTEGER</P> 120 */ 121 public static final String LAST_TIME_CONTACTED = "last_time_contacted"; 122 123 /** 124 * Is the contact starred? 125 * <P>Type: INTEGER (boolean)</P> 126 */ 127 public static final String STARRED = "starred"; 128 129 /** 130 * Reference to the row in the data table holding the primary phone number. 131 * <P>Type: INTEGER REFERENCES data(_id)</P> 132 */ 133 public static final String PRIMARY_PHONE_ID = "primary_phone_id"; 134 135 /** 136 * Reference to the row in the data table holding the primary email address. 137 * <P>Type: INTEGER REFERENCES data(_id)</P> 138 */ 139 public static final String PRIMARY_EMAIL_ID = "primary_email_id"; 140 141 /** 142 * Reference to the row in the data table holding the photo. 143 * <P>Type: INTEGER REFERENCES data(_id)</P> 144 */ 145 public static final String PHOTO_ID = "photo_id"; 146 147 /** 148 * Reference to a row containing custom ringtone and send to voicemail information. 149 * <P>Type: INTEGER REFERENCES data(_id)</P> 150 */ 151 public static final String CUSTOM_RINGTONE_ID = "custom_ringtone_id"; 152 } 153 154 /** 155 * Constants for the aggregates table, which contains a record per group 156 * of contact representing the same person. 157 */ 158 public static final class Aggregates implements BaseColumns, AggregatesColumns { 159 /** 160 * This utility class cannot be instantiated 161 */ 162 private Aggregates() {} 163 164 /** 165 * The content:// style URI for this table 166 */ 167 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "aggregates"); 168 169 /** 170 * The content:// style URI for this table joined with useful data from 171 * {@link Data} and {@link Presence}. 172 */ 173 public static final Uri CONTENT_SUMMARY_URI = Uri.withAppendedPath(AUTHORITY_URI, 174 "aggregates_summary"); 175 /** 176 * The content:// style URI used for "type-to-filter" functionality on the 177 * {@link CONTENT_SUMMARY_URI} URI. The filter string will be used to match 178 * various parts of the aggregate name. The filter argument should be passed 179 * as an additional path segment after this URI. 180 */ 181 public static final Uri CONTENT_SUMMARY_FILTER_URI = Uri.withAppendedPath( 182 CONTENT_SUMMARY_URI, "filter"); 183 /** 184 * The content:// style URI for this table joined with useful data from 185 * {@link Data} and {@link Presence}, filtered to include only starred aggregates 186 * and the most frequently contacted aggregates. 187 */ 188 public static final Uri CONTENT_SUMMARY_STREQUENT_URI = Uri.withAppendedPath( 189 CONTENT_SUMMARY_URI, "strequent"); 190 /** 191 * The content:// style URI used for "type-to-filter" functionality on the 192 * {@link CONTENT_SUMMARY_STREQUENT_URI} URI. The filter string will be used to match 193 * various parts of the aggregate name. The filter argument should be passed 194 * as an additional path segment after this URI. 195 */ 196 public static final Uri CONTENT_SUMMARY_STREQUENT_FILTER_URI = Uri.withAppendedPath( 197 CONTENT_SUMMARY_STREQUENT_URI, "filter"); 198 199 /** 200 * The MIME type of {@link #CONTENT_URI} providing a directory of 201 * people. 202 */ 203 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/person_aggregate"; 204 205 /** 206 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 207 * person. 208 */ 209 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/person_aggregate"; 210 211 /** 212 * A sub-directory of a single contact aggregate that contains all of their 213 * {@link Data} rows. 214 */ 215 public static final class Data implements BaseColumns, DataColumns { 216 /** 217 * no public constructor since this is a utility class 218 */ 219 private Data() {} 220 221 /** 222 * The directory twig for this sub-table 223 */ 224 public static final String CONTENT_DIRECTORY = "data"; 225 } 226 227 /** 228 * A sub-directory of a single contact aggregate that contains all aggregation suggestions 229 * (other aggregates). The aggregation suggestions are computed based on approximate 230 * data matches with this aggregate. 231 */ 232 public static final class AggregationSuggestions implements BaseColumns, AggregatesColumns { 233 /** 234 * No public constructor since this is a utility class 235 */ 236 private AggregationSuggestions() {} 237 238 /** 239 * The directory twig for this sub-table 240 */ 241 public static final String CONTENT_DIRECTORY = "suggestions"; 242 243 /** 244 * An optional query parameter that can be supplied to limit the number of returned 245 * suggestions. 246 * <p> 247 * Type: INTEGER 248 */ 249 public static final String MAX_SUGGESTIONS = "max_suggestions"; 250 } 251 } 252 253 254 /** 255 * Constants for the contacts table, which contains the base contact information. 256 */ 257 public static final class Contacts implements BaseColumns { 258 /** 259 * This utility class cannot be instantiated 260 */ 261 private Contacts() {} 262 263 /** 264 * The package name that owns this contact and all of its details. This 265 * package has control over the {@link #IS_RESTRICTED} flag, and can 266 * grant {@link RestrictionExceptions} to other packages. 267 */ 268 public static final String PACKAGE = "package"; 269 270 /** 271 * Flag indicating that this data entry has been restricted by the owner 272 * {@link #PACKAGE}. 273 */ 274 public static final String IS_RESTRICTED = "is_restricted"; 275 276 /** 277 * A reference to the {@link Accounts#_ID} that this data belongs to. 278 */ 279 public static final String ACCOUNTS_ID = "accounts_id"; 280 281 /** 282 * A reference to the {@link Aggregates#_ID} that this data belongs to. 283 */ 284 public static final String AGGREGATE_ID = "aggregate_id"; 285 286 /** 287 * The content:// style URI for this table 288 */ 289 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "contacts"); 290 291 /** 292 * The content:// style URL for filtering people by email address. The 293 * filter argument should be passed as an additional path segment after 294 * this URI. 295 * 296 * @hide 297 */ 298 public static final Uri CONTENT_FILTER_EMAIL_URI = 299 Uri.withAppendedPath(CONTENT_URI, "filter_email"); 300 301 /** 302 * The MIME type of {@link #CONTENT_URI} providing a directory of 303 * people. 304 */ 305 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/person"; 306 307 /** 308 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 309 * person. 310 */ 311 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/person"; 312 313 /** 314 * A string that uniquely identifies this contact to its source, which is referred to 315 * by the {@link #ACCOUNTS_ID} 316 */ 317 public static final String SOURCE_ID = "sourceid"; 318 319 /** 320 * An integer that is updated whenever this contact or its data changes. 321 */ 322 public static final String VERSION = "version"; 323 324 /** 325 * Set to 1 whenever the version changes 326 */ 327 public static final String DIRTY = "dirty"; 328 329 /** 330 * A sub-directory of a single contact that contains all of their {@link Data} rows. 331 * To access this directory append 332 */ 333 public static final class Data implements BaseColumns, DataColumns { 334 /** 335 * no public constructor since this is a utility class 336 */ 337 private Data() {} 338 339 /** 340 * The directory twig for this sub-table 341 */ 342 public static final String CONTENT_DIRECTORY = "data"; 343 } 344 } 345 346 private interface DataColumns { 347 /** 348 * The mime-type of the item represented by this row. 349 */ 350 public static final String MIMETYPE = "mimetype"; 351 352 /** 353 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} 354 * that this data belongs to. 355 */ 356 public static final String CONTACT_ID = "contact_id"; 357 358 /** 359 * Whether this is the primary entry of its kind for the contact it belongs to 360 * <P>Type: INTEGER (if set, non-0 means true)</P> 361 */ 362 public static final String IS_PRIMARY = "is_primary"; 363 364 /** 365 * Whether this is the primary entry of its kind for the aggregate it belongs to. Any data 366 * record that is "super primary" must also be "primary". 367 * <P>Type: INTEGER (if set, non-0 means true)</P> 368 */ 369 public static final String IS_SUPER_PRIMARY = "is_super_primary"; 370 371 /** 372 * The version of this data record. This is a read-only value. The data column is 373 * guaranteed to not change without the version going up. This value is monotonically 374 * increasing. 375 * <P>Type: INTEGER</P> 376 */ 377 public static final String DATA_VERSION = "data_version"; 378 379 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 380 public static final String DATA1 = "data1"; 381 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 382 public static final String DATA2 = "data2"; 383 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 384 public static final String DATA3 = "data3"; 385 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 386 public static final String DATA4 = "data4"; 387 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 388 public static final String DATA5 = "data5"; 389 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 390 public static final String DATA6 = "data6"; 391 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 392 public static final String DATA7 = "data7"; 393 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 394 public static final String DATA8 = "data8"; 395 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 396 public static final String DATA9 = "data9"; 397 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 398 public static final String DATA10 = "data10"; 399 } 400 401 /** 402 * Constants for the data table, which contains data points tied to a contact. 403 * For example, a phone number or email address. Each row in this table contains a type 404 * definition and some generic columns. Each data type can define the meaning for each of 405 * the generic columns. 406 */ 407 public static final class Data implements BaseColumns, DataColumns { 408 /** 409 * This utility class cannot be instantiated 410 */ 411 private Data() {} 412 413 /** 414 * The content:// style URI for this table 415 */ 416 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data"); 417 418 /** 419 * The MIME type of {@link #CONTENT_URI} providing a directory of data. 420 */ 421 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data"; 422 } 423 424 /** 425 * A table that represents the result of looking up a phone number, for example for caller ID. 426 * The table joins that data row for the phone number with the contact that owns the number. 427 * To perform a lookup you must append the number you want to find to {@link #CONTENT_URI}. 428 */ 429 public static final class PhoneLookup implements BaseColumns, DataColumns, AggregatesColumns { 430 /** 431 * This utility class cannot be instantiated 432 */ 433 private PhoneLookup() {} 434 435 /** 436 * The content:// style URI for this table. Append the phone number you want to lookup 437 * to this URI and query it to perform a lookup. For example: 438 * 439 * {@code 440 * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_URI, phoneNumber); 441 * } 442 */ 443 public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(AUTHORITY_URI, 444 "phone_lookup"); 445 } 446 447 /** 448 * Additional data mixed in with {@link Im.CommonPresenceColumns} to link 449 * back to specific {@link ContactsContract.Aggregates#_ID} entries. 450 */ 451 private interface PresenceColumns { 452 /** 453 * Reference to the {@link Aggregates#_ID} this presence references. 454 */ 455 public static final String AGGREGATE_ID = "aggregate_id"; 456 457 /** 458 * Reference to the {@link Data#_ID} entry that owns this presence. 459 */ 460 public static final String DATA_ID = "data_id"; 461 462 /** 463 * The IM service the presence is coming from. Formatted using either 464 * {@link Contacts.ContactMethods#encodePredefinedImProtocol} or 465 * {@link Contacts.ContactMethods#encodeCustomImProtocol}. 466 * <p> 467 * Type: STRING 468 */ 469 public static final String IM_PROTOCOL = "im_protocol"; 470 471 /** 472 * The IM handle the presence item is for. The handle is scoped to the 473 * {@link #IM_PROTOCOL}. 474 * <p> 475 * Type: STRING 476 */ 477 public static final String IM_HANDLE = "im_handle"; 478 479 /** 480 * The IM account for the local user that the presence data came from. 481 * <p> 482 * Type: STRING 483 */ 484 public static final String IM_ACCOUNT = "im_account"; 485 } 486 487 public static final class Presence implements BaseColumns, PresenceColumns, 488 Im.CommonPresenceColumns { 489 /** 490 * This utility class cannot be instantiated 491 */ 492 private Presence() { 493 } 494 495 /** 496 * The content:// style URI for this table 497 */ 498 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "presence"); 499 500 /** 501 * Gets the resource ID for the proper presence icon. 502 * 503 * @param status the status to get the icon for 504 * @return the resource ID for the proper presence icon 505 */ 506 public static final int getPresenceIconResourceId(int status) { 507 switch (status) { 508 case AVAILABLE: 509 return android.R.drawable.presence_online; 510 case IDLE: 511 case AWAY: 512 return android.R.drawable.presence_away; 513 case DO_NOT_DISTURB: 514 return android.R.drawable.presence_busy; 515 case INVISIBLE: 516 return android.R.drawable.presence_invisible; 517 case OFFLINE: 518 default: 519 return android.R.drawable.presence_offline; 520 } 521 } 522 523 /** 524 * The MIME type of {@link #CONTENT_URI} providing a directory of 525 * presence details. 526 */ 527 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/im-presence"; 528 529 /** 530 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 531 * presence detail. 532 */ 533 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im-presence"; 534 } 535 536 /** 537 * Container for definitions of common data types stored in the {@link Data} table. 538 */ 539 public static final class CommonDataKinds { 540 /** 541 * The {@link Data#PACKAGE} value for common data that should be shown 542 * using a default style. 543 */ 544 public static final String PACKAGE_COMMON = "common"; 545 546 /** 547 * Columns common across the specific types. 548 */ 549 private interface BaseCommonColumns { 550 /** 551 * The package name that defines this type of data. 552 */ 553 public static final String PACKAGE = "package"; 554 555 /** 556 * The mime-type of the item represented by this row. 557 */ 558 public static final String MIMETYPE = "mimetype"; 559 560 /** 561 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} that this 562 * data belongs to. 563 */ 564 public static final String CONTACT_ID = "contact_id"; 565 } 566 567 /** 568 * Columns common across the specific types. 569 */ 570 private interface CommonColumns { 571 /** 572 * The type of data, for example Home or Work. 573 * <P>Type: INTEGER</P> 574 */ 575 public static final String TYPE = "data1"; 576 577 /** 578 * The data for the contact method. 579 * <P>Type: TEXT</P> 580 */ 581 public static final String DATA = "data2"; 582 583 /** 584 * The user defined label for the the contact method. 585 * <P>Type: TEXT</P> 586 */ 587 public static final String LABEL = "data3"; 588 } 589 590 /** 591 * The base types that all "Typed" data kinds support. 592 */ 593 public interface BaseTypes { 594 595 /** 596 * A custom type. The custom label should be supplied by user. 597 */ 598 public static int TYPE_CUSTOM = 0; 599 } 600 601 /** 602 * Parts of the name. 603 */ 604 public static final class StructuredName { 605 private StructuredName() {} 606 607 /** Mime-type used when storing this in data table. */ 608 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/name"; 609 610 /** 611 * The given name for the contact. 612 * <P>Type: TEXT</P> 613 */ 614 public static final String GIVEN_NAME = "data1"; 615 616 /** 617 * The family name for the contact. 618 * <P>Type: TEXT</P> 619 */ 620 public static final String FAMILY_NAME = "data2"; 621 622 /** 623 * The contact's honorific prefix, e.g. "Sir" 624 * <P>Type: TEXT</P> 625 */ 626 public static final String PREFIX = "data3"; 627 628 /** 629 * The contact's middle name 630 * <P>Type: TEXT</P> 631 */ 632 public static final String MIDDLE_NAME = "data4"; 633 634 /** 635 * The contact's honorific suffix, e.g. "Jr" 636 */ 637 public static final String SUFFIX = "data5"; 638 639 /** 640 * The phonetic version of the given name for the contact. 641 * <P>Type: TEXT</P> 642 */ 643 public static final String PHONETIC_GIVEN_NAME = "data6"; 644 645 /** 646 * The phonetic version of the additional name for the contact. 647 * <P>Type: TEXT</P> 648 */ 649 public static final String PHONETIC_MIDDLE_NAME = "data7"; 650 651 /** 652 * The phonetic version of the family name for the contact. 653 * <P>Type: TEXT</P> 654 */ 655 public static final String PHONETIC_FAMILY_NAME = "data8"; 656 657 /** 658 * The name that should be used to display the contact. 659 * <P>Type: TEXT</P> 660 */ 661 public static final String DISPLAY_NAME = "data9"; 662 } 663 664 /** 665 * A nickname. 666 */ 667 public static final class Nickname implements BaseTypes { 668 private Nickname() {} 669 670 /** Mime-type used when storing this in data table. */ 671 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/nickname"; 672 673 /** 674 * The type of data, for example Home or Work. 675 * <P>Type: INTEGER</P> 676 */ 677 public static final String TYPE = "data1"; 678 679 public static final int TYPE_DEFAULT = 1; 680 public static final int TYPE_OTHER_NAME = 2; 681 public static final int TYPE_MAINDEN_NAME = 3; 682 public static final int TYPE_SHORT_NAME = 4; 683 public static final int TYPE_INITIALS = 5; 684 685 /** 686 * The name itself 687 */ 688 public static final String NAME = "data2"; 689 690 /** 691 * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}. 692 * <P>Type: TEXT</P> 693 */ 694 public static final String LABEL = "data3"; 695 } 696 697 /** 698 * Common data definition for telephone numbers. 699 */ 700 public static final class Phone implements BaseCommonColumns, CommonColumns, BaseTypes { 701 private Phone() {} 702 703 /** Mime-type used when storing this in data table. */ 704 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone"; 705 706 /** 707 * The MIME type of {@link #CONTENT_URI} providing a directory of 708 * phones. 709 */ 710 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/phone"; 711 712 /** 713 * The content:// style URI for all data records of the 714 * {@link Phone.CONTENT_ITEM_TYPE} mimetype, combined with the associated contact 715 * and aggregate data. 716 */ 717 public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI, 718 "phones"); 719 720 /** 721 * The content:// style URI for filtering data records of the 722 * {@link Phone.CONTENT_ITEM_TYPE} mimetype, combined with the associated contact 723 * and aggregate data. The filter argument should be passed 724 * as an additional path segment after this URI. 725 */ 726 public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI, 727 "filter"); 728 729 public static final int TYPE_HOME = 1; 730 public static final int TYPE_MOBILE = 2; 731 public static final int TYPE_WORK = 3; 732 public static final int TYPE_FAX_WORK = 4; 733 public static final int TYPE_FAX_HOME = 5; 734 public static final int TYPE_PAGER = 6; 735 public static final int TYPE_OTHER = 7; 736 737 /** 738 * The phone number as the user entered it. 739 * <P>Type: TEXT</P> 740 */ 741 public static final String NUMBER = "data2"; 742 } 743 744 /** 745 * Common data definition for email addresses. 746 */ 747 public static final class Email implements BaseCommonColumns, CommonColumns, BaseTypes { 748 private Email() {} 749 750 /** Mime-type used when storing this in data table. */ 751 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/email"; 752 753 public static final int TYPE_HOME = 1; 754 public static final int TYPE_WORK = 2; 755 public static final int TYPE_OTHER = 3; 756 } 757 758 /** 759 * Common data definition for postal addresses. 760 */ 761 public static final class Postal implements BaseCommonColumns, CommonColumns, BaseTypes { 762 private Postal() {} 763 764 /** Mime-type used when storing this in data table. */ 765 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/postal-address"; 766 767 /** 768 * The MIME type of {@link #CONTENT_URI} providing a directory of 769 * postal addresses. 770 */ 771 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/postal-address"; 772 773 /** 774 * The content:// style URI for all data records of the 775 * {@link Postal.CONTENT_ITEM_TYPE} mimetype, combined with the associated contact 776 * and aggregate data. 777 */ 778 public static final Uri CONTENT_URI = Uri.withAppendedPath(Data.CONTENT_URI, 779 "postals"); 780 781 public static final int TYPE_HOME = 1; 782 public static final int TYPE_WORK = 2; 783 public static final int TYPE_OTHER = 3; 784 } 785 786 /** 787 * Common data definition for IM addresses. 788 */ 789 public static final class Im implements BaseCommonColumns, CommonColumns, BaseTypes { 790 private Im() {} 791 792 /** Mime-type used when storing this in data table. */ 793 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im"; 794 795 public static final int TYPE_HOME = 1; 796 public static final int TYPE_WORK = 2; 797 public static final int TYPE_OTHER = 3; 798 799 public static final String PROTOCOL = "data5"; 800 801 /** 802 * The predefined IM protocol types. The protocol can either be non-present, one 803 * of these types, or a free-form string. These cases are encoded in the PROTOCOL 804 * column as: 805 * <ul> 806 * <li>null</li> 807 * <li>pre:<an integer, one of the protocols below></li> 808 * <li>custom:<a string></li> 809 * </ul> 810 */ 811 public static final int PROTOCOL_AIM = 0; 812 public static final int PROTOCOL_MSN = 1; 813 public static final int PROTOCOL_YAHOO = 2; 814 public static final int PROTOCOL_SKYPE = 3; 815 public static final int PROTOCOL_QQ = 4; 816 public static final int PROTOCOL_GOOGLE_TALK = 5; 817 public static final int PROTOCOL_ICQ = 6; 818 public static final int PROTOCOL_JABBER = 7; 819 820 public static String encodePredefinedImProtocol(int protocol) { 821 return "pre:" + protocol; 822 } 823 824 public static String encodeCustomImProtocol(String protocolString) { 825 return "custom:" + protocolString; 826 } 827 828 public static Object decodeImProtocol(String encodedString) { 829 if (encodedString == null) { 830 return null; 831 } 832 833 if (encodedString.startsWith("pre:")) { 834 return Integer.parseInt(encodedString.substring(4)); 835 } 836 837 if (encodedString.startsWith("custom:")) { 838 return encodedString.substring(7); 839 } 840 841 throw new IllegalArgumentException( 842 "the value is not a valid encoded protocol, " + encodedString); 843 } 844 } 845 846 /** 847 * Common data definition for organizations. 848 */ 849 public static final class Organization implements BaseCommonColumns, BaseTypes { 850 private Organization() {} 851 852 /** Mime-type used when storing this in data table. */ 853 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/organization"; 854 855 /** 856 * The type of data, for example Home or Work. 857 * <P>Type: INTEGER</P> 858 */ 859 public static final String TYPE = "data1"; 860 861 public static final int TYPE_HOME = 1; 862 public static final int TYPE_WORK = 2; 863 public static final int TYPE_OTHER = 3; 864 865 /** 866 * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}. 867 * <P>Type: TEXT</P> 868 */ 869 public static final String LABEL = "data2"; 870 871 /** 872 * The company as the user entered it. 873 * <P>Type: TEXT</P> 874 */ 875 public static final String COMPANY = "data3"; 876 877 /** 878 * The position title at this company as the user entered it. 879 * <P>Type: TEXT</P> 880 */ 881 public static final String TITLE = "data4"; 882 } 883 884 /** 885 * Photo of the contact. 886 */ 887 public static final class Photo implements BaseCommonColumns { 888 private Photo() {} 889 890 /** Mime-type used when storing this in data table. */ 891 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/photo"; 892 893 /** 894 * Thumbnail photo of the contact. This is the raw bytes of an image 895 * that could be inflated using {@link BitmapFactory}. 896 * <p> 897 * Type: BLOB 898 */ 899 public static final String PHOTO = "data1"; 900 } 901 902 /** 903 * Notes about the contact. 904 */ 905 public static final class Note implements BaseCommonColumns { 906 private Note() {} 907 908 /** Mime-type used when storing this in data table. */ 909 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/note"; 910 911 /** 912 * The note text. 913 * <P>Type: TEXT</P> 914 */ 915 public static final String NOTE = "data1"; 916 } 917 918 /** 919 * Custom ringtone associated with the contact. 920 */ 921 public static final class CustomRingtone implements BaseCommonColumns { 922 private CustomRingtone() {} 923 924 public static final String CONTENT_ITEM_TYPE = 925 "vnd.android.cursor.item/custom_ringtone"; 926 927 /** 928 * Whether to send the number to voicemail. 929 * <P>Type: INTEGER (if set, non-0 means true)</P> 930 */ 931 public static final String SEND_TO_VOICEMAIL = "data1"; 932 933 /** 934 * The ringtone uri. 935 * <P>Type: TEXT</P> 936 */ 937 public static final String RINGTONE_URI = "data2"; 938 } 939 940 /** 941 * Group Membership. 942 */ 943 public static final class GroupMembership implements BaseCommonColumns { 944 private GroupMembership() {} 945 946 /** Mime-type used when storing this in data table. */ 947 public static final String CONTENT_ITEM_TYPE = 948 "vnd.android.cursor.item/group_membership"; 949 950 /** 951 * The row id of the group that this group membership refers to. Either this or the 952 * GROUP_SOURCE_ID must be set. If they are both set then they must refer to the same 953 * group. 954 * <P>Type: INTEGER</P> 955 */ 956 public static final String GROUP_ROW_ID = "data1"; 957 958 /** 959 * The source id of the group that this membership refers to. Either this or the 960 * GROUP_ROW_ID must be set. If they are both set then they must refer to the same 961 * group. 962 * <P>Type: STRING</P> 963 */ 964 public static final String GROUP_SOURCE_ID = "data2"; 965 } 966 } 967 968 /** 969 * Constants for the contact aggregation exceptions table, which contains 970 * aggregation rules overriding those used by automatic aggregation. This type only 971 * supports query and update. Neither insert nor delete are supported. 972 */ 973 public static final class AggregationExceptions implements BaseColumns { 974 /** 975 * This utility class cannot be instantiated 976 */ 977 private AggregationExceptions() {} 978 979 /** 980 * The content:// style URI for this table 981 */ 982 public static final Uri CONTENT_URI = 983 Uri.withAppendedPath(AUTHORITY_URI, "aggregation_exceptions"); 984 985 /** 986 * The MIME type of {@link #CONTENT_URI} providing a directory of data. 987 */ 988 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/aggregation_exception"; 989 990 /** 991 * The MIME type of a {@link #CONTENT_URI} subdirectory of an aggregation exception 992 */ 993 public static final String CONTENT_ITEM_TYPE = 994 "vnd.android.cursor.item/aggregation_exception"; 995 996 /** 997 * The type of exception: {@link #TYPE_KEEP_IN}, {@link #TYPE_KEEP_OUT} or 998 * {@link #TYPE_AUTOMATIC}. 999 * 1000 * <P>Type: INTEGER</P> 1001 */ 1002 public static final String TYPE = "type"; 1003 1004 /** 1005 * Allows the provider to automatically decide whether the aggregate should include 1006 * a particular contact or not. 1007 */ 1008 public static final int TYPE_AUTOMATIC = 0; 1009 1010 /** 1011 * Makes sure that the specified contact is included in the specified aggregate. 1012 */ 1013 public static final int TYPE_KEEP_IN = 1; 1014 1015 /** 1016 * Makes sure that the specified contact is NOT included in the specified aggregate. 1017 */ 1018 public static final int TYPE_KEEP_OUT = 2; 1019 1020 /** 1021 * A reference to the {@link Aggregates#_ID} of the aggregate that the rule applies to. 1022 */ 1023 public static final String AGGREGATE_ID = "aggregate_id"; 1024 1025 /** 1026 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} of the 1027 * contact that the rule applies to. 1028 */ 1029 public static final String CONTACT_ID = "contact_id"; 1030 } 1031 1032 private interface RestrictionExceptionsColumns { 1033 /** 1034 * Package name of a specific data provider, which will be matched 1035 * against {@link Data#PACKAGE}. 1036 * <p> 1037 * Type: STRING 1038 */ 1039 public static final String PACKAGE_PROVIDER = "package_provider"; 1040 1041 /** 1042 * Package name of a specific data client, which will be matched against 1043 * the incoming {@link android.os.Binder#getCallingUid()} to decide if 1044 * the caller can access values with {@link Data#IS_RESTRICTED} flags. 1045 * <p> 1046 * Type: STRING 1047 */ 1048 public static final String PACKAGE_CLIENT = "package_client"; 1049 1050 /** 1051 * Flag indicating if {@link #PACKAGE_PROVIDER} allows 1052 * {@link #PACKAGE_CLIENT} to access restricted {@link Data} rows. 1053 * <p> 1054 * Type: INTEGER 1055 */ 1056 public static final String ALLOW_ACCESS = "allow_access"; 1057 } 1058 1059 /** 1060 * Constants for {@link Data} restriction exceptions. Sync adapters who 1061 * insert restricted data can use this table to specify exceptions about 1062 * which additional packages can access that restricted data.You can only 1063 * modify rules for a {@link RestrictionExceptionsColumns#PACKAGE_PROVIDER} 1064 * that your {@link android.os.Binder#getCallingUid()} owns. 1065 */ 1066 public static final class RestrictionExceptions implements RestrictionExceptionsColumns { 1067 /** 1068 * This utility class cannot be instantiated 1069 */ 1070 private RestrictionExceptions() {} 1071 1072 /** 1073 * The content:// style URI for this table 1074 */ 1075 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, 1076 "restriction_exceptions"); 1077 } 1078 1079 /** 1080 * Contains helper classes used to create or manage {@link android.content.Intent Intents} 1081 * that involve contacts. 1082 */ 1083 public static final class Intents { 1084 /** 1085 * This is the intent that is fired when a search suggestion is clicked on. 1086 */ 1087 public static final String SEARCH_SUGGESTION_CLICKED = 1088 "android.provider.Contacts.SEARCH_SUGGESTION_CLICKED"; 1089 1090 /** 1091 * This is the intent that is fired when a search suggestion for dialing a number 1092 * is clicked on. 1093 */ 1094 public static final String SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED = 1095 "android.provider.Contacts.SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED"; 1096 1097 /** 1098 * This is the intent that is fired when a search suggestion for creating a contact 1099 * is clicked on. 1100 */ 1101 public static final String SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED = 1102 "android.provider.Contacts.SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED"; 1103 1104 /** 1105 * Starts an Activity that lets the user pick a contact to attach an image to. 1106 * After picking the contact it launches the image cropper in face detection mode. 1107 */ 1108 public static final String ATTACH_IMAGE = 1109 "com.android.contacts.action.ATTACH_IMAGE"; 1110 1111 /** 1112 * Takes as input a data URI with a mailto: or tel: scheme. If a single 1113 * contact exists with the given data it will be shown. If no contact 1114 * exists, a dialog will ask the user if they want to create a new 1115 * contact with the provided details filled in. If multiple contacts 1116 * share the data the user will be prompted to pick which contact they 1117 * want to view. 1118 * <p> 1119 * For <code>mailto:</code> URIs, the scheme specific portion must be a 1120 * raw email address, such as one built using 1121 * {@link Uri#fromParts(String, String, String)}. 1122 * <p> 1123 * For <code>tel:</code> URIs, the scheme specific portion is compared 1124 * to existing numbers using the standard caller ID lookup algorithm. 1125 * The number must be properly encoded, for example using 1126 * {@link Uri#fromParts(String, String, String)}. 1127 * <p> 1128 * Any extras from the {@link Insert} class will be passed along to the 1129 * create activity if there are no contacts to show. 1130 * <p> 1131 * Passing true for the {@link #EXTRA_FORCE_CREATE} extra will skip 1132 * prompting the user when the contact doesn't exist. 1133 */ 1134 public static final String SHOW_OR_CREATE_CONTACT = 1135 "com.android.contacts.action.SHOW_OR_CREATE_CONTACT"; 1136 1137 /** 1138 * Used with {@link #SHOW_OR_CREATE_CONTACT} to force creating a new 1139 * contact if no matching contact found. Otherwise, default behavior is 1140 * to prompt user with dialog before creating. 1141 * <p> 1142 * Type: BOOLEAN 1143 */ 1144 public static final String EXTRA_FORCE_CREATE = 1145 "com.android.contacts.action.FORCE_CREATE"; 1146 1147 /** 1148 * Used with {@link #SHOW_OR_CREATE_CONTACT} to specify an exact 1149 * description to be shown when prompting user about creating a new 1150 * contact. 1151 * <p> 1152 * Type: STRING 1153 */ 1154 public static final String EXTRA_CREATE_DESCRIPTION = 1155 "com.android.contacts.action.CREATE_DESCRIPTION"; 1156 1157 /** 1158 * Intents related to the Contacts app UI. 1159 */ 1160 public static final class UI { 1161 /** 1162 * The action for the default contacts list tab. 1163 */ 1164 public static final String LIST_DEFAULT = 1165 "com.android.contacts.action.LIST_DEFAULT"; 1166 1167 /** 1168 * The action for the contacts list tab. 1169 */ 1170 public static final String LIST_GROUP_ACTION = 1171 "com.android.contacts.action.LIST_GROUP"; 1172 1173 /** 1174 * When in LIST_GROUP_ACTION mode, this is the group to display. 1175 */ 1176 public static final String GROUP_NAME_EXTRA_KEY = "com.android.contacts.extra.GROUP"; 1177 1178 /** 1179 * The action for the all contacts list tab. 1180 */ 1181 public static final String LIST_ALL_CONTACTS_ACTION = 1182 "com.android.contacts.action.LIST_ALL_CONTACTS"; 1183 1184 /** 1185 * The action for the contacts with phone numbers list tab. 1186 */ 1187 public static final String LIST_CONTACTS_WITH_PHONES_ACTION = 1188 "com.android.contacts.action.LIST_CONTACTS_WITH_PHONES"; 1189 1190 /** 1191 * The action for the starred contacts list tab. 1192 */ 1193 public static final String LIST_STARRED_ACTION = 1194 "com.android.contacts.action.LIST_STARRED"; 1195 1196 /** 1197 * The action for the frequent contacts list tab. 1198 */ 1199 public static final String LIST_FREQUENT_ACTION = 1200 "com.android.contacts.action.LIST_FREQUENT"; 1201 1202 /** 1203 * The action for the "strequent" contacts list tab. It first lists the starred 1204 * contacts in alphabetical order and then the frequent contacts in descending 1205 * order of the number of times they have been contacted. 1206 */ 1207 public static final String LIST_STREQUENT_ACTION = 1208 "com.android.contacts.action.LIST_STREQUENT"; 1209 1210 /** 1211 * A key for to be used as an intent extra to set the activity 1212 * title to a custom String value. 1213 */ 1214 public static final String TITLE_EXTRA_KEY = 1215 "com.android.contacts.extra.TITLE_EXTRA"; 1216 1217 /** 1218 * Activity Action: Display a filtered list of contacts 1219 * <p> 1220 * Input: Extra field {@link #FILTER_TEXT_EXTRA_KEY} is the text to use for 1221 * filtering 1222 * <p> 1223 * Output: Nothing. 1224 */ 1225 public static final String FILTER_CONTACTS_ACTION = 1226 "com.android.contacts.action.FILTER_CONTACTS"; 1227 1228 /** 1229 * Used as an int extra field in {@link #FILTER_CONTACTS_ACTION} 1230 * intents to supply the text on which to filter. 1231 */ 1232 public static final String FILTER_TEXT_EXTRA_KEY = 1233 "com.android.contacts.extra.FILTER_TEXT"; 1234 } 1235 1236 /** 1237 * Convenience class that contains string constants used 1238 * to create contact {@link android.content.Intent Intents}. 1239 */ 1240 public static final class Insert { 1241 /** The action code to use when adding a contact */ 1242 public static final String ACTION = Intent.ACTION_INSERT; 1243 1244 /** 1245 * If present, forces a bypass of quick insert mode. 1246 */ 1247 public static final String FULL_MODE = "full_mode"; 1248 1249 /** 1250 * The extra field for the contact name. 1251 * <P>Type: String</P> 1252 */ 1253 public static final String NAME = "name"; 1254 1255 // TODO add structured name values here. 1256 1257 /** 1258 * The extra field for the contact phonetic name. 1259 * <P>Type: String</P> 1260 */ 1261 public static final String PHONETIC_NAME = "phonetic_name"; 1262 1263 /** 1264 * The extra field for the contact company. 1265 * <P>Type: String</P> 1266 */ 1267 public static final String COMPANY = "company"; 1268 1269 /** 1270 * The extra field for the contact job title. 1271 * <P>Type: String</P> 1272 */ 1273 public static final String JOB_TITLE = "job_title"; 1274 1275 /** 1276 * The extra field for the contact notes. 1277 * <P>Type: String</P> 1278 */ 1279 public static final String NOTES = "notes"; 1280 1281 /** 1282 * The extra field for the contact phone number. 1283 * <P>Type: String</P> 1284 */ 1285 public static final String PHONE = "phone"; 1286 1287 /** 1288 * The extra field for the contact phone number type. 1289 * <P>Type: Either an integer value from 1290 * {@link android.provider.Contacts.PhonesColumns PhonesColumns}, 1291 * or a string specifying a custom label.</P> 1292 */ 1293 public static final String PHONE_TYPE = "phone_type"; 1294 1295 /** 1296 * The extra field for the phone isprimary flag. 1297 * <P>Type: boolean</P> 1298 */ 1299 public static final String PHONE_ISPRIMARY = "phone_isprimary"; 1300 1301 /** 1302 * The extra field for an optional second contact phone number. 1303 * <P>Type: String</P> 1304 */ 1305 public static final String SECONDARY_PHONE = "secondary_phone"; 1306 1307 /** 1308 * The extra field for an optional second contact phone number type. 1309 * <P>Type: Either an integer value from 1310 * {@link android.provider.Contacts.PhonesColumns PhonesColumns}, 1311 * or a string specifying a custom label.</P> 1312 */ 1313 public static final String SECONDARY_PHONE_TYPE = "secondary_phone_type"; 1314 1315 /** 1316 * The extra field for an optional third contact phone number. 1317 * <P>Type: String</P> 1318 */ 1319 public static final String TERTIARY_PHONE = "tertiary_phone"; 1320 1321 /** 1322 * The extra field for an optional third contact phone number type. 1323 * <P>Type: Either an integer value from 1324 * {@link android.provider.Contacts.PhonesColumns PhonesColumns}, 1325 * or a string specifying a custom label.</P> 1326 */ 1327 public static final String TERTIARY_PHONE_TYPE = "tertiary_phone_type"; 1328 1329 /** 1330 * The extra field for the contact email address. 1331 * <P>Type: String</P> 1332 */ 1333 public static final String EMAIL = "email"; 1334 1335 /** 1336 * The extra field for the contact email type. 1337 * <P>Type: Either an integer value from 1338 * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns} 1339 * or a string specifying a custom label.</P> 1340 */ 1341 public static final String EMAIL_TYPE = "email_type"; 1342 1343 /** 1344 * The extra field for the email isprimary flag. 1345 * <P>Type: boolean</P> 1346 */ 1347 public static final String EMAIL_ISPRIMARY = "email_isprimary"; 1348 1349 /** 1350 * The extra field for an optional second contact email address. 1351 * <P>Type: String</P> 1352 */ 1353 public static final String SECONDARY_EMAIL = "secondary_email"; 1354 1355 /** 1356 * The extra field for an optional second contact email type. 1357 * <P>Type: Either an integer value from 1358 * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns} 1359 * or a string specifying a custom label.</P> 1360 */ 1361 public static final String SECONDARY_EMAIL_TYPE = "secondary_email_type"; 1362 1363 /** 1364 * The extra field for an optional third contact email address. 1365 * <P>Type: String</P> 1366 */ 1367 public static final String TERTIARY_EMAIL = "tertiary_email"; 1368 1369 /** 1370 * The extra field for an optional third contact email type. 1371 * <P>Type: Either an integer value from 1372 * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns} 1373 * or a string specifying a custom label.</P> 1374 */ 1375 public static final String TERTIARY_EMAIL_TYPE = "tertiary_email_type"; 1376 1377 /** 1378 * The extra field for the contact postal address. 1379 * <P>Type: String</P> 1380 */ 1381 public static final String POSTAL = "postal"; 1382 1383 /** 1384 * The extra field for the contact postal address type. 1385 * <P>Type: Either an integer value from 1386 * {@link android.provider.Contacts.ContactMethodsColumns ContactMethodsColumns} 1387 * or a string specifying a custom label.</P> 1388 */ 1389 public static final String POSTAL_TYPE = "postal_type"; 1390 1391 /** 1392 * The extra field for the postal isprimary flag. 1393 * <P>Type: boolean</P> 1394 */ 1395 public static final String POSTAL_ISPRIMARY = "postal_isprimary"; 1396 1397 /** 1398 * The extra field for an IM handle. 1399 * <P>Type: String</P> 1400 */ 1401 public static final String IM_HANDLE = "im_handle"; 1402 1403 /** 1404 * The extra field for the IM protocol 1405 * <P>Type: the result of {@link Contacts.ContactMethods#encodePredefinedImProtocol} 1406 * or {@link Contacts.ContactMethods#encodeCustomImProtocol}.</P> 1407 */ 1408 public static final String IM_PROTOCOL = "im_protocol"; 1409 1410 /** 1411 * The extra field for the IM isprimary flag. 1412 * <P>Type: boolean</P> 1413 */ 1414 public static final String IM_ISPRIMARY = "im_isprimary"; 1415 } 1416 } 1417 1418} 1419