ContactsContract.java revision ab5742dd63f4e62ee0f55f786854c024ef8c5bb4
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.graphics.BitmapFactory; 20import android.net.Uri; 21 22/** 23 * The contract between the contacts provider and applications. Contains definitions 24 * for the supported URIs and columns. 25 * 26 * @hide 27 */ 28public final class ContactsContract { 29 /** The authority for the contacts provider */ 30 public static final String AUTHORITY = "com.android.contacts"; 31 /** A content:// style uri to the authority for the contacts provider */ 32 public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY); 33 34 public interface AccountsColumns { 35 /** 36 * The name of this account data 37 * <P>Type: TEXT</P> 38 */ 39 public static final String NAME = "name"; 40 /** 41 * The name of this account data 42 * <P>Type: TEXT</P> 43 */ 44 public static final String TYPE = "type"; 45 /** 46 * The name of this account data 47 * <P>Type: TEXT</P> 48 */ 49 public static final String DATA1 = "data1"; 50 51 /** 52 * The value for this account data 53 * <P>Type: INTEGER</P> 54 */ 55 public static final String DATA2 = "data2"; 56 57 /** 58 * The value for this account data 59 * <P>Type: INTEGER</P> 60 */ 61 public static final String DATA3 = "data3"; 62 63 /** 64 * The value for this account data 65 * <P>Type: INTEGER</P> 66 */ 67 public static final String DATA4 = "data4"; 68 69 /** 70 * The value for this account data 71 * <P>Type: INTEGER</P> 72 */ 73 public static final String DATA5 = "data5"; 74 } 75 76 /** 77 * Constants for the aggregates table, which contains a record per group 78 * of contact representing the same person. 79 */ 80 public static final class Accounts implements BaseColumns, AccountsColumns { 81 /** 82 * This utility class cannot be instantiated 83 */ 84 private Accounts() {} 85 86 /** 87 * The content:// style URI for this table 88 */ 89 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "accounts"); 90 91 /** 92 * The MIME type of {@link #CONTENT_URI} providing a directory of 93 * account data. 94 */ 95 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/contacts_account"; 96 97 /** 98 * The MIME type of a {@link #CONTENT_URI} subdirectory of a account 99 */ 100 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/contacts_account"; 101 } 102 103 public interface AggregatesColumns { 104 /** 105 * The display name for the contact. 106 * <P>Type: TEXT</P> 107 */ 108 public static final String DISPLAY_NAME = "display_name"; 109 110 /** 111 * The number of times a person has been contacted 112 * <P>Type: INTEGER</P> 113 */ 114 public static final String TIMES_CONTACTED = "times_contacted"; 115 116 /** 117 * The last time a person was contacted. 118 * <P>Type: INTEGER</P> 119 */ 120 public static final String LAST_TIME_CONTACTED = "last_time_contacted"; 121 122 /** 123 * Is the contact starred? 124 * <P>Type: INTEGER (boolean)</P> 125 */ 126 public static final String STARRED = "starred"; 127 128 /** 129 * Reference to the row in the data table holding the primary phone number. 130 * <P>Type: INTEGER REFERENCES data(_id)</P> 131 */ 132 public static final String PRIMARY_PHONE_ID = "primary_phone_id"; 133 134 /** 135 * Reference to the row in the data table holding the primary email address. 136 * <P>Type: INTEGER REFERENCES data(_id)</P> 137 */ 138 public static final String PRIMARY_EMAIL_ID = "primary_email_id"; 139 140 /** 141 * Reference to the row in the data table holding the photo. 142 * <P>Type: INTEGER REFERENCES data(_id)</P> 143 */ 144 public static final String PHOTO_ID = "photo_id"; 145 146 /** 147 * Reference to a row containing custom ringtone and send to voicemail information. 148 * <P>Type: INTEGER REFERENCES data(_id)</P> 149 */ 150 public static final String CUSTOM_RINGTONE_ID = "custom_ringtone_id"; 151 } 152 153 /** 154 * Constants for the aggregates table, which contains a record per group 155 * of contact representing the same person. 156 */ 157 public static final class Aggregates implements BaseColumns, AggregatesColumns { 158 /** 159 * This utility class cannot be instantiated 160 */ 161 private Aggregates() {} 162 163 /** 164 * The content:// style URI for this table 165 */ 166 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "aggregates"); 167 168 /** 169 * The MIME type of {@link #CONTENT_URI} providing a directory of 170 * people. 171 */ 172 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/person_aggregate"; 173 174 /** 175 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 176 * person. 177 */ 178 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/person_aggregate"; 179 180 /** 181 * A sub-directory of a single contact aggregate that contains all of their 182 * {@link Data} rows. 183 */ 184 public static final class Data implements BaseColumns, DataColumns { 185 /** 186 * no public constructor since this is a utility class 187 */ 188 private Data() {} 189 190 /** 191 * The directory twig for this sub-table 192 */ 193 public static final String CONTENT_DIRECTORY = "data"; 194 } 195 } 196 197 198 /** 199 * Constants for the contacts table, which contains the base contact information. 200 */ 201 public static final class Contacts implements BaseColumns { 202 /** 203 * This utility class cannot be instantiated 204 */ 205 private Contacts() {} 206 207 /** 208 * A reference to the {@link Accounts#_ID} that this data belongs to. 209 */ 210 public static final String ACCOUNTS_ID = "accounts_id"; 211 212 /** 213 * A reference to the {@link Aggregates#_ID} that this data belongs to. 214 */ 215 public static final String AGGREGATE_ID = "aggregate_id"; 216 217 /** 218 * The content:// style URI for this table 219 */ 220 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "contacts"); 221 222 /** 223 * The content:// style URL for filtering people by email address. The 224 * filter argument should be passed as an additional path segment after 225 * this URI. 226 * 227 * @hide 228 */ 229 public static final Uri CONTENT_FILTER_EMAIL_URI = Uri.withAppendedPath(CONTENT_URI, "filter_email"); 230 231 /** 232 * The MIME type of {@link #CONTENT_URI} providing a directory of 233 * people. 234 */ 235 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/person"; 236 237 /** 238 * The MIME type of a {@link #CONTENT_URI} subdirectory of a single 239 * person. 240 */ 241 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/person"; 242 243 /** 244 * A string that uniquely identifies this contact to its source, which is referred to 245 * by the {@link #ACCOUNTS_ID} 246 */ 247 public static final String SOURCE_ID = "sourceid"; 248 249 /** 250 * An integer that is updated whenever this contact or its data changes. 251 */ 252 public static final String VERSION = "version"; 253 254 /** 255 * Set to 1 whenever the version changes 256 */ 257 public static final String DIRTY = "dirty"; 258 259 /** 260 * A sub-directory of a single contact that contains all of their {@link Data} rows. 261 * To access this directory append 262 */ 263 public static final class Data implements BaseColumns, DataColumns { 264 /** 265 * no public constructor since this is a utility class 266 */ 267 private Data() {} 268 269 /** 270 * The directory twig for this sub-table 271 */ 272 public static final String CONTENT_DIRECTORY = "data"; 273 } 274 } 275 276 private interface DataColumns { 277 /** 278 * The package name that defines this type of data. 279 */ 280 public static final String PACKAGE = "package"; 281 282 /** 283 * The mime-type of the item represented by this row. 284 */ 285 public static final String MIMETYPE = "mimetype"; 286 287 /** 288 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} 289 * that this data belongs to. 290 */ 291 public static final String CONTACT_ID = "contact_id"; 292 293 /** 294 * Whether this is the primary entry of its kind for the contact it belongs to 295 * <P>Type: INTEGER (if set, non-0 means true)</P> 296 */ 297 public static final String IS_PRIMARY = "is_primary"; 298 299 /** 300 * Whether this is the primary entry of its kind for the aggregate it belongs to. Any data 301 * record that is "super primary" must also be "primary". 302 * <P>Type: INTEGER (if set, non-0 means true)</P> 303 */ 304 public static final String IS_SUPER_PRIMARY = "is_super_primary"; 305 306 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 307 public static final String DATA1 = "data1"; 308 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 309 public static final String DATA2 = "data2"; 310 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 311 public static final String DATA3 = "data3"; 312 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 313 public static final String DATA4 = "data4"; 314 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 315 public static final String DATA5 = "data5"; 316 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 317 public static final String DATA6 = "data6"; 318 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 319 public static final String DATA7 = "data7"; 320 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 321 public static final String DATA8 = "data8"; 322 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 323 public static final String DATA9 = "data9"; 324 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 325 public static final String DATA10 = "data10"; 326 } 327 328 /** 329 * Constants for the data table, which contains data points tied to a contact. 330 * For example, a phone number or email address. Each row in this table contains a type 331 * definition and some generic columns. Each data type can define the meaning for each of 332 * the generic columns. 333 */ 334 public static final class Data implements BaseColumns, DataColumns { 335 /** 336 * This utility class cannot be instantiated 337 */ 338 private Data() {} 339 340 /** 341 * The content:// style URI for this table 342 */ 343 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data"); 344 345 /** 346 * The MIME type of {@link #CONTENT_URI} providing a directory of data. 347 */ 348 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data"; 349 } 350 351 /** 352 * A table that represents the result of looking up a phone number, for example for caller ID. 353 * The table joins that data row for the phone number with the contact that owns the number. 354 * To perform a lookup you must append the number you want to find to {@link #CONTENT_URI}. 355 */ 356 public static final class PhoneLookup implements BaseColumns, DataColumns, AggregatesColumns { 357 /** 358 * This utility class cannot be instantiated 359 */ 360 private PhoneLookup() {} 361 362 /** 363 * The content:// style URI for this table. Append the phone number you want to lookup 364 * to this URI and query it to perform a lookup. For example: 365 * 366 * {@code 367 * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_URI, phoneNumber); 368 * } 369 */ 370 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "phone_lookup"); 371 } 372 373 /** 374 * Container for definitions of common data types stored in the {@link Data} table. 375 */ 376 public static final class CommonDataKinds { 377 /** 378 * The {@link Data#PACKAGE} value for common data that should be shown 379 * using a default style. 380 */ 381 public static final String PACKAGE_COMMON = "common"; 382 383 /** 384 * Columns common across the specific types. 385 */ 386 private interface BaseCommonColumns { 387 /** 388 * The package name that defines this type of data. 389 */ 390 public static final String PACKAGE = "package"; 391 392 /** 393 * The mime-type of the item represented by this row. 394 */ 395 public static final String MIMETYPE = "mimetype"; 396 397 /** 398 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} that this 399 * data belongs to. 400 */ 401 public static final String CONTACT_ID = "contact_id"; 402 } 403 404 /** 405 * Columns common across the specific types. 406 */ 407 private interface CommonColumns { 408 /** 409 * The type of data, for example Home or Work. 410 * <P>Type: INTEGER</P> 411 */ 412 public static final String TYPE = "data1"; 413 414 /** 415 * The data for the contact method. 416 * <P>Type: TEXT</P> 417 */ 418 public static final String DATA = "data2"; 419 420 /** 421 * The user defined label for the the contact method. 422 * <P>Type: TEXT</P> 423 */ 424 public static final String LABEL = "data3"; 425 } 426 427 /** 428 * Parts of the name. 429 */ 430 public static final class StructuredName { 431 private StructuredName() {} 432 433 /** Mime-type used when storing this in data table. */ 434 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/name"; 435 436 /** 437 * The given name for the contact. 438 * <P>Type: TEXT</P> 439 */ 440 public static final String GIVEN_NAME = "data1"; 441 442 /** 443 * The family name for the contact. 444 * <P>Type: TEXT</P> 445 */ 446 public static final String FAMILY_NAME = "data2"; 447 448 /** 449 * The contact's honorific prefix, e.g. "Sir" 450 * <P>Type: TEXT</P> 451 */ 452 public static final String PREFIX = "data3"; 453 454 /** 455 * The contact's middle name 456 * <P>Type: TEXT</P> 457 */ 458 public static final String MIDDLE_NAME = "data4"; 459 460 /** 461 * The contact's honorific suffix, e.g. "Jr" 462 */ 463 public static final String SUFFIX = "data5"; 464 465 /** 466 * The phonetic version of the given name for the contact. 467 * <P>Type: TEXT</P> 468 */ 469 public static final String PHONETIC_GIVEN_NAME = "data6"; 470 471 /** 472 * The phonetic version of the additional name for the contact. 473 * <P>Type: TEXT</P> 474 */ 475 public static final String PHONETIC_MIDDLE_NAME = "data7"; 476 477 /** 478 * The phonetic version of the family name for the contact. 479 * <P>Type: TEXT</P> 480 */ 481 public static final String PHONETIC_FAMILY_NAME = "data8"; 482 483 /** 484 * The name that should be used to display the contact. 485 * <P>Type: TEXT</P> 486 */ 487 public static final String DISPLAY_NAME = "data9"; 488 } 489 490 /** 491 * A nickname. 492 */ 493 public static final class Nickname { 494 private Nickname() {} 495 496 /** Mime-type used when storing this in data table. */ 497 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/nickname"; 498 499 /** 500 * The type of data, for example Home or Work. 501 * <P>Type: INTEGER</P> 502 */ 503 public static final String TYPE = "data1"; 504 505 public static final int TYPE_CUSTOM = 1; 506 public static final int TYPE_DEFAULT = 2; 507 public static final int TYPE_OTHER_NAME = 3; 508 public static final int TYPE_MAINDEN_NAME = 4; 509 public static final int TYPE_SHORT_NAME = 5; 510 public static final int TYPE_INITIALS = 6; 511 512 /** 513 * The name itself 514 */ 515 public static final String NAME = "data2"; 516 517 /** 518 * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}. 519 * <P>Type: TEXT</P> 520 */ 521 public static final String LABEL = "data3"; 522 } 523 524 /** 525 * Common data definition for telephone numbers. 526 */ 527 public static final class Phone implements BaseCommonColumns, CommonColumns { 528 private Phone() {} 529 530 /** Mime-type used when storing this in data table. */ 531 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone"; 532 533 public static final int TYPE_CUSTOM = 0; 534 public static final int TYPE_HOME = 1; 535 public static final int TYPE_MOBILE = 2; 536 public static final int TYPE_WORK = 3; 537 public static final int TYPE_FAX_WORK = 4; 538 public static final int TYPE_FAX_HOME = 5; 539 public static final int TYPE_PAGER = 6; 540 public static final int TYPE_OTHER = 7; 541 542 /** 543 * The phone number as the user entered it. 544 * <P>Type: TEXT</P> 545 */ 546 public static final String NUMBER = "data2"; 547 } 548 549 /** 550 * Common data definition for email addresses. 551 */ 552 public static final class Email implements BaseCommonColumns, CommonColumns { 553 private Email() {} 554 555 /** Mime-type used when storing this in data table. */ 556 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/email"; 557 558 public static final int TYPE_CUSTOM = 0; 559 public static final int TYPE_HOME = 1; 560 public static final int TYPE_WORK = 2; 561 public static final int TYPE_OTHER = 3; 562 } 563 564 /** 565 * Common data definition for postal addresses. 566 */ 567 public static final class Postal implements BaseCommonColumns, CommonColumns { 568 private Postal() {} 569 570 /** Mime-type used when storing this in data table. */ 571 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/postal-address"; 572 573 public static final int TYPE_CUSTOM = 0; 574 public static final int TYPE_HOME = 1; 575 public static final int TYPE_WORK = 2; 576 public static final int TYPE_OTHER = 3; 577 } 578 579 /** 580 * Common data definition for IM addresses. 581 */ 582 public static final class Im implements BaseCommonColumns, CommonColumns { 583 private Im() {} 584 585 /** Mime-type used when storing this in data table. */ 586 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im"; 587 588 public static final int TYPE_CUSTOM = 0; 589 public static final int TYPE_HOME = 1; 590 public static final int TYPE_WORK = 2; 591 public static final int TYPE_OTHER = 3; 592 593 public static final String PROTOCOL = "data5"; 594 595 /** 596 * The predefined IM protocol types. The protocol can either be non-present, one 597 * of these types, or a free-form string. These cases are encoded in the PROTOCOL 598 * column as: 599 * <ul> 600 * <li>null</li> 601 * <li>pre:<an integer, one of the protocols below></li> 602 * <li>custom:<a string></li> 603 * </ul> 604 */ 605 public static final int PROTOCOL_AIM = 0; 606 public static final int PROTOCOL_MSN = 1; 607 public static final int PROTOCOL_YAHOO = 2; 608 public static final int PROTOCOL_SKYPE = 3; 609 public static final int PROTOCOL_QQ = 4; 610 public static final int PROTOCOL_GOOGLE_TALK = 5; 611 public static final int PROTOCOL_ICQ = 6; 612 public static final int PROTOCOL_JABBER = 7; 613 } 614 615 /** 616 * Common data definition for organizations. 617 */ 618 public static final class Organization implements BaseCommonColumns { 619 private Organization() {} 620 621 /** Mime-type used when storing this in data table. */ 622 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/organization"; 623 624 /** 625 * The type of data, for example Home or Work. 626 * <P>Type: INTEGER</P> 627 */ 628 public static final String TYPE = "data1"; 629 630 public static final int TYPE_CUSTOM = 0; 631 public static final int TYPE_HOME = 1; 632 public static final int TYPE_WORK = 2; 633 public static final int TYPE_OTHER = 3; 634 635 /** 636 * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}. 637 * <P>Type: TEXT</P> 638 */ 639 public static final String LABEL = "data2"; 640 641 /** 642 * The company as the user entered it. 643 * <P>Type: TEXT</P> 644 */ 645 public static final String COMPANY = "data3"; 646 647 /** 648 * The position title at this company as the user entered it. 649 * <P>Type: TEXT</P> 650 */ 651 public static final String TITLE = "data4"; 652 } 653 654 /** 655 * Photo of the contact. 656 */ 657 public static final class Photo implements BaseCommonColumns { 658 private Photo() {} 659 660 /** Mime-type used when storing this in data table. */ 661 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/photo"; 662 663 /** 664 * Thumbnail photo of the contact. This is the raw bytes of an image 665 * that could be inflated using {@link BitmapFactory}. 666 * <p> 667 * Type: BLOB 668 */ 669 public static final String PHOTO = "data1"; 670 } 671 672 /** 673 * Notes about the contact. 674 */ 675 public static final class Note implements BaseCommonColumns { 676 private Note() {} 677 678 /** Mime-type used when storing this in data table. */ 679 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/note"; 680 681 /** 682 * The note text. 683 * <P>Type: TEXT</P> 684 */ 685 public static final String NOTE = "data1"; 686 } 687 688 /** 689 * Custom ringtone associated with the contact. 690 */ 691 public static final class CustomRingtone implements BaseCommonColumns { 692 private CustomRingtone() {} 693 694 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/custom_ringtone"; 695 696 /** 697 * Whether to send the number to voicemail. 698 * <P>Type: INTEGER (if set, non-0 means true)</P> 699 */ 700 public static final String SEND_TO_VOICEMAIL = "data1"; 701 702 /** 703 * The ringtone uri. 704 * <P>Type: TEXT</P> 705 */ 706 public static final String RINGTONE_URI = "data2"; 707 } 708 } 709 710 /** 711 * Constants for the contact aggregation exceptions table, which contains 712 * aggregation rules overriding those used by automatic aggregation. 713 */ 714 public static final class AggregationExceptions { 715 /** 716 * This utility class cannot be instantiated 717 */ 718 private AggregationExceptions() {} 719 720 /** 721 * The content:// style URI for this table 722 */ 723 public static final Uri CONTENT_URI = 724 Uri.withAppendedPath(AUTHORITY_URI, "aggregation_exception"); 725 726 /** 727 * The MIME type of {@link #CONTENT_URI} providing a directory of data. 728 */ 729 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/aggregation_exception"; 730 731 /** 732 * The type of exception: {@link #TYPE_NEVER_MATCH} or {@link #TYPE_ALWAYS_MATCH}. 733 * 734 * <P>Type: INTEGER</P> 735 */ 736 public static final String TYPE = "type"; 737 738 public static final int TYPE_NEVER_MATCH = 0; 739 public static final int TYPE_ALWAYS_MATCH = 1; 740 741 /** 742 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} of one of 743 * the contacts that the rule applies to. 744 */ 745 public static final String CONTACT_ID1 = "contact_id1"; 746 747 /** 748 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} of the other 749 * contact that the rule applies to. 750 */ 751 public static final String CONTACT_ID2 = "contact_id2"; 752 } 753} 754