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