ContactsContract.java revision 03d9490758c9318cee6d14d3cc5007556dce92d0
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 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 294 public static final String DATA1 = "data1"; 295 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 296 public static final String DATA2 = "data2"; 297 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 298 public static final String DATA3 = "data3"; 299 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 300 public static final String DATA4 = "data4"; 301 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 302 public static final String DATA5 = "data5"; 303 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 304 public static final String DATA6 = "data6"; 305 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 306 public static final String DATA7 = "data7"; 307 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 308 public static final String DATA8 = "data8"; 309 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 310 public static final String DATA9 = "data9"; 311 /** Generic data column, the meaning is {@link #MIMETYPE} specific */ 312 public static final String DATA10 = "data10"; 313 } 314 315 /** 316 * Constants for the data table, which contains data points tied to a contact. 317 * For example, a phone number or email address. Each row in this table contains a type 318 * definition and some generic columns. Each data type can define the meaning for each of 319 * the generic columns. 320 */ 321 public static final class Data implements BaseColumns, DataColumns { 322 /** 323 * This utility class cannot be instantiated 324 */ 325 private Data() {} 326 327 /** 328 * The content:// style URI for this table 329 */ 330 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data"); 331 332 /** 333 * The MIME type of {@link #CONTENT_URI} providing a directory of data. 334 */ 335 public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data"; 336 } 337 338 /** 339 * A table that represents the result of looking up a phone number, for example for caller ID. 340 * The table joins that data row for the phone number with the contact that owns the number. 341 * To perform a lookup you must append the number you want to find to {@link #CONTENT_URI}. 342 */ 343 public static final class PhoneLookup implements BaseColumns, DataColumns, AggregatesColumns { 344 /** 345 * This utility class cannot be instantiated 346 */ 347 private PhoneLookup() {} 348 349 /** 350 * The content:// style URI for this table. Append the phone number you want to lookup 351 * to this URI and query it to perform a lookup. For example: 352 * 353 * {@code 354 * Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_URI, phoneNumber); 355 * } 356 */ 357 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "phone_lookup"); 358 } 359 360 /** 361 * Container for definitions of common data types stored in the {@link Data} table. 362 */ 363 public static final class CommonDataKinds { 364 /** 365 * The {@link Data#PACKAGE} value for common data that should be shown 366 * using a default style. 367 */ 368 public static final String PACKAGE_COMMON = "common"; 369 370 /** 371 * Columns common across the specific types. 372 */ 373 private interface BaseCommonColumns { 374 /** 375 * The package name that defines this type of data. 376 */ 377 public static final String PACKAGE = "package"; 378 379 /** 380 * The mime-type of the item represented by this row. 381 */ 382 public static final String MIMETYPE = "mimetype"; 383 384 /** 385 * A reference to the {@link android.provider.ContactsContract.Contacts#_ID} that this 386 * data belongs to. 387 */ 388 public static final String CONTACT_ID = "contact_id"; 389 } 390 391 /** 392 * Columns common across the specific types. 393 */ 394 private interface CommonColumns { 395 /** 396 * The type of data, for example Home or Work. 397 * <P>Type: INTEGER</P> 398 */ 399 public static final String TYPE = "data1"; 400 401 /** 402 * The user defined label for the the contact method. 403 * <P>Type: TEXT</P> 404 */ 405 public static final String LABEL = "data2"; 406 407 /** 408 * The data for the contact method. 409 * <P>Type: TEXT</P> 410 */ 411 public static final String DATA = "data3"; 412 413 /** 414 * Whether this is the primary entry of its kind for the contact it belongs to 415 * <P>Type: INTEGER (if set, non-0 means true)</P> 416 */ 417 public static final String ISPRIMARY = "data4"; 418 } 419 420 /** 421 * Parts of the name. 422 */ 423 public static final class StructuredName { 424 private StructuredName() {} 425 426 /** Mime-type used when storing this in data table. */ 427 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/name"; 428 429 /** 430 * The contact's honorific prefix, e.g. "Sir" 431 */ 432 public static final String PREFIX = "data1"; 433 434 /** 435 * The given name for the contact. 436 * <P>Type: TEXT</P> 437 */ 438 public static final String GIVEN_NAME = "data2"; 439 440 /** 441 * The contact's middle name 442 * <P>Type: TEXT</P> 443 */ 444 public static final String MIDDLE_NAME = "data3"; 445 446 /** 447 * The family name for the contact. 448 * <P>Type: TEXT</P> 449 */ 450 public static final String FAMILY_NAME = "data4"; 451 452 /** 453 * The contact's honorific suffix, e.g. "Jr" 454 */ 455 public static final String SUFFIX = "data5"; 456 457 /** 458 * The phonetic version of the given name for the contact. 459 * <P>Type: TEXT</P> 460 */ 461 public static final String PHONETIC_GIVEN_NAME = "data6"; 462 463 /** 464 * The phonetic version of the additional name for the contact. 465 * <P>Type: TEXT</P> 466 */ 467 public static final String PHONETIC_MIDDLE_NAME = "data7"; 468 469 /** 470 * The phonetic version of the family name for the contact. 471 * <P>Type: TEXT</P> 472 */ 473 public static final String PHONETIC_FAMILY_NAME = "data8"; 474 475 /** 476 * The name that should be used to display the contact. 477 * <P>Type: TEXT</P> 478 */ 479 public static final String DISPLAY_NAME = "data9"; 480 } 481 482 /** 483 * A nickname. 484 */ 485 public static final class Nickname { 486 private Nickname() {} 487 488 /** Mime-type used when storing this in data table. */ 489 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/nickname"; 490 491 /** 492 * The type of data, for example Home or Work. 493 * <P>Type: INTEGER</P> 494 */ 495 public static final String TYPE = "data1"; 496 497 public static final int TYPE_CUSTOM = 1; 498 public static final int TYPE_DEFAULT = 2; 499 public static final int TYPE_OTHER_NAME = 3; 500 public static final int TYPE_MAINDEN_NAME = 4; 501 public static final int TYPE_SHORT_NAME = 5; 502 public static final int TYPE_INITIALS = 6; 503 504 /** 505 * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}. 506 * <P>Type: TEXT</P> 507 */ 508 public static final String LABEL = "data2"; 509 510 /** 511 * The name itself 512 */ 513 public static final String NAME = "data3"; 514 } 515 516 /** 517 * Common data definition for telephone numbers. 518 */ 519 public static final class Phone implements BaseCommonColumns, CommonColumns { 520 private Phone() {} 521 522 /** Mime-type used when storing this in data table. */ 523 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone"; 524 525 public static final int TYPE_CUSTOM = 0; 526 public static final int TYPE_HOME = 1; 527 public static final int TYPE_MOBILE = 2; 528 public static final int TYPE_WORK = 3; 529 public static final int TYPE_FAX_WORK = 4; 530 public static final int TYPE_FAX_HOME = 5; 531 public static final int TYPE_PAGER = 6; 532 public static final int TYPE_OTHER = 7; 533 534 /** 535 * The phone number as the user entered it. 536 * <P>Type: TEXT</P> 537 */ 538 public static final String NUMBER = "data3"; 539 540 } 541 542 /** 543 * Common data definition for email addresses. 544 */ 545 public static final class Email implements BaseCommonColumns, CommonColumns { 546 private Email() {} 547 548 /** Mime-type used when storing this in data table. */ 549 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/email"; 550 551 public static final int TYPE_CUSTOM = 0; 552 public static final int TYPE_HOME = 1; 553 public static final int TYPE_WORK = 2; 554 public static final int TYPE_OTHER = 3; 555 556 } 557 558 /** 559 * Common data definition for postal addresses. 560 */ 561 public static final class Postal implements BaseCommonColumns, CommonColumns { 562 private Postal() {} 563 564 /** Mime-type used when storing this in data table. */ 565 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/postal-address"; 566 567 public static final int TYPE_CUSTOM = 0; 568 public static final int TYPE_HOME = 1; 569 public static final int TYPE_WORK = 2; 570 public static final int TYPE_OTHER = 3; 571 } 572 573 /** 574 * Common data definition for IM addresses. 575 */ 576 public static final class Im implements BaseCommonColumns, CommonColumns { 577 private Im() {} 578 579 /** Mime-type used when storing this in data table. */ 580 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/im"; 581 582 public static final int TYPE_CUSTOM = 0; 583 public static final int TYPE_HOME = 1; 584 public static final int TYPE_WORK = 2; 585 public static final int TYPE_OTHER = 3; 586 587 public static final String PROTOCOL = "data5"; 588 589 /** 590 * The predefined IM protocol types. The protocol can either be non-present, one 591 * of these types, or a free-form string. These cases are encoded in the PROTOCOL 592 * column as: 593 * - null 594 * - pre:<an integer, one of the protocols below> 595 * - custom:<a string> 596 */ 597 public static final int PROTOCOL_AIM = 0; 598 public static final int PROTOCOL_MSN = 1; 599 public static final int PROTOCOL_YAHOO = 2; 600 public static final int PROTOCOL_SKYPE = 3; 601 public static final int PROTOCOL_QQ = 4; 602 public static final int PROTOCOL_GOOGLE_TALK = 5; 603 public static final int PROTOCOL_ICQ = 6; 604 public static final int PROTOCOL_JABBER = 7; 605 } 606 607 /** 608 * Common data definition for organizations. 609 */ 610 public static final class Organization implements BaseCommonColumns { 611 private Organization() {} 612 613 /** Mime-type used when storing this in data table. */ 614 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/organization"; 615 616 /** 617 * The type of data, for example Home or Work. 618 * <P>Type: INTEGER</P> 619 */ 620 public static final String TYPE = "data1"; 621 622 public static final int TYPE_CUSTOM = 0; 623 public static final int TYPE_HOME = 1; 624 public static final int TYPE_WORK = 2; 625 public static final int TYPE_OTHER = 3; 626 627 /** 628 * The user provided label, only used if TYPE is {@link #TYPE_CUSTOM}. 629 * <P>Type: TEXT</P> 630 */ 631 public static final String LABEL = "data2"; 632 633 /** 634 * The company as the user entered it. 635 * <P>Type: TEXT</P> 636 */ 637 public static final String COMPANY = "data3"; 638 639 /** 640 * The position title at this company as the user entered it. 641 * <P>Type: TEXT</P> 642 */ 643 public static final String TITLE = "data4"; 644 645 /** 646 * Whether this is the primary organization 647 * <P>Type: INTEGER (if set, non-0 means true)</P> 648 */ 649 public static final String ISPRIMARY = "data5"; 650 651 } 652 653 /** 654 * Photo of the contact. 655 */ 656 public static final class Photo implements BaseCommonColumns { 657 private Photo() {} 658 659 /** Mime-type used when storing this in data table. */ 660 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/photo"; 661 662 /** 663 * Thumbnail photo of the contact. This is the raw bytes of an image 664 * that could be inflated using {@link BitmapFactory}. 665 * <p> 666 * Type: BLOB 667 */ 668 public static final String PHOTO = "data1"; 669 } 670 671 /** 672 * Notes about the contact. 673 */ 674 public static final class Note implements BaseCommonColumns { 675 private Note() {} 676 677 /** Mime-type used when storing this in data table. */ 678 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/note"; 679 680 /** 681 * The note text. 682 * <P>Type: TEXT</P> 683 */ 684 public static final String NOTE = "data1"; 685 } 686 687 public static final class CustomRingtone implements BaseCommonColumns { 688 private CustomRingtone() {} 689 690 public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/custom_ringtone"; 691 692 /** 693 * Whether to send the number to voicemail. 694 * <P>Type: INTEGER (if set, non-0 means true)</P> 695 */ 696 public static final String SEND_TO_VOICEMAIL = "data1"; 697 698 /** 699 * The ringtone uri. 700 * <P>Type: TEXT</P> 701 */ 702 public static final String RINGTONE_URI = "data2"; 703 } 704 } 705 706} 707