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