ContactsContract.Data

public static final class ContactsContract.Data
extends Object implements ContactsContract.DataColumnsWithJoins

数据表的常量，其中包含绑定到原始联系人的数据点。 数据表的每一行通常用于存储单个联系人信息（例如电话号码）及其关联的元数据（例如，它是工作还是家庭号码）。

Data kinds

数据是一个通用表格，可以容纳任何类型的联系人数据。 存储在给定行中的数据类型由行MIMETYPE值指定，该值确定了通用列DATA1到DATA15 。 例如，如果数据类型为Phone.CONTENT_ITEM_TYPE ，则列DATA1存储电话号码，但如果数据类型为Email.CONTENT_ITEM_TYPE ，则DATA1将存储电子邮件地址。 同步适配器和应用程序可以引入它们自己的数据种类。

ContactsContract限定了少数预定义的数据种，例如 ContactsContract.CommonDataKinds.Phone ， ContactsContract.CommonDataKinds.Email等为方便起见，这些类定义数据类型的特定别名DATA1等。例如， Phone.NUMBER相同 Data.DATA1 。

DATA1是一个索引列，应该用于查询选择中最常用的数据元素。 例如，对于表示电子邮件地址的行DATA1可能应该用于电子邮件地址本身，而DATA2等可用于辅助信息，例如电子邮件地址的类型。

按照惯例， DATA15用于存储BLOB（二进制数据）。

给定帐户类型的同步适配器必须正确处理相应原始联系人中使用的每种数据类型。 否则可能导致数据丢失或损坏。

同样，您应该避免为其他方的帐户类型引入新的数据。 例如，如果您向Google帐户拥有的原始联系人添加“最喜欢的歌曲”的数据行，则该数据行不会与服务器同步，因为Google同步适配器不知道如何处理此类数据。 因此，通常会引入新的数据类型以及新的帐户类型，即新的同步适配器。

Batch operations

数据行可以被插入/更新/使用传统的删除insert(Uri, ContentValues) ， update(Uri, ContentValues, String, String[])和delete(Uri, String, String[])方法，但是基于批次的新机制ContentProviderOperation将被证明是在几乎所有情况下，更好的选择。 批处理中的所有操作都在单个事务中执行，这可确保原始联系人的电话端和服务器端状态始终保持一致。 此外，基于批处理的方法效率更高：不仅在单个事务中执行数据库操作时速度更快，而且向内容提供者发送一批命令可节省大量时间，以便在进程和内容提供者运行的过程。

使用批处理操作的另一面是大批量数据库可能会长时间锁定数据库，从而阻止其他应用程序访问数据并可能导致ANR（“应用程序未响应”对话框）。

为了避免这种数据库锁定，请确保在批次中插入“屈服点”。 屈服点指示内容提供者，在执行下一个操作之前，它可以提交已经做出的更改，屈服于其他请求，打开另一个事务并继续处理操作。 屈服点不会自动提交事务，但只有在数据库上有另一个请求正在等待时。 通常，同步适配器应在批处理中的每个原始联系人操作序列的开始处插入一个屈服点。 见withYieldAllowed(boolean) 。

Operations

Insert

可以使用传统的insert(Uri, ContentValues)方法插入单个数据行。 多行应始终作为批次插入。

传统插入的一个例子：

 ContentValues values = new ContentValues();
 values.put(Data.RAW_CONTACT_ID, rawContactId);
 values.put(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE);
 values.put(Phone.NUMBER, "1-800-GOOG-411");
 values.put(Phone.TYPE, Phone.TYPE_CUSTOM);
 values.put(Phone.LABEL, "free directory assistance");
 Uri dataUri = getContentResolver().insert(Data.CONTENT_URI, values);
 

使用ContentProviderOperations完成相同的操作：

 ArrayList<ContentProviderOperation> ops =
          new ArrayList<ContentProviderOperation>();

 ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
          .withValue(Data.RAW_CONTACT_ID, rawContactId)
          .withValue(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE)
          .withValue(Phone.NUMBER, "1-800-GOOG-411")
          .withValue(Phone.TYPE, Phone.TYPE_CUSTOM)
          .withValue(Phone.LABEL, "free directory assistance")
          .build());
 getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
 

Update

就像插入一样，更新可以逐步完成或作为批处理完成，批处理模式是首选方法：

 ArrayList<ContentProviderOperation> ops =
          new ArrayList<ContentProviderOperation>();

 ops.add(ContentProviderOperation.newUpdate(Data.CONTENT_URI)
          .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)})
          .withValue(Email.DATA, "[email protected]")
          .build());
 getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
 

Delete

就像插入和更新一样，可以使用 delete(Uri, String, String[])方法或使用ContentProviderOperation完成删除操作：

 ArrayList<ContentProviderOperation> ops =
          new ArrayList<ContentProviderOperation>();

 ops.add(ContentProviderOperation.newDelete(Data.CONTENT_URI)
          .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)})
          .build());
 getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
 

Query

Finding all Data of a given type for a given contact

 Cursor c = getContentResolver().query(Data.CONTENT_URI,
          new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},
          Data.CONTACT_ID + "=?" + " AND "
                  + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",
          new String[] {String.valueOf(contactId)}, null);
 

Finding all Data of a given type for a given raw contact

 Cursor c = getContentResolver().query(Data.CONTENT_URI,
          new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},
          Data.RAW_CONTACT_ID + "=?" + " AND "
                  + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",
          new String[] {String.valueOf(rawContactId)}, null);
 

Finding all Data for a given raw contact

Most sync adapters will want to read all data rows for a raw contact along with the raw contact itself. For that you should use the ContactsContract.RawContactsEntity. See also ContactsContract.RawContacts.

Columns

许多列可通过CONTENT_URI查询获得。 为了获得最佳性能，您应该明确指定一个投影到只需要那些列。

最近一次关联状态更新中的某些列也可以通过隐式连接获得。

来自关联的原始联系人的某些列也可以通过隐式联接来使用。 在这种情况下，其他列被排除为不感兴趣。

相关联的聚合联系人表ContactsContract.Contacts的ID列可通过对ContactsContract.RawContacts表的隐式ContactsContract.Contacts来获得，参见上文。 通过隐式连接，此表中剩余的列也可用。 这有助于通过单个数据元素的值进行查找，例如电子邮件地址。

Summary

Inherited constants
From interface android.provider.BaseColumns String _COUNT 目录中的行数。 String _ID 一行的唯一ID。
From interface android.provider.ContactsContract.DataColumns String CARRIER_PRESENCE 运营商存在信息。 int CARRIER_PRESENCE_VT_CAPABLE 表示该条目是当前运营商的视频电话（VT）。 String DATA1 通用数据列，含义是 MIMETYPE具体 String DATA10 泛型数据列，含义是 MIMETYPE具体 String DATA11 泛型数据列，含义是 MIMETYPE具体 String DATA12 泛型数据列，含义是 MIMETYPE具体 String DATA13 泛型数据列，含义是 MIMETYPE具体 String DATA14 通用数据列，含义是 MIMETYPE具体 String DATA15 通用数据列，含义是 MIMETYPE具体。 String DATA2 泛型数据列，含义是 MIMETYPE具体 String DATA3 泛型数据列，含义是 MIMETYPE具体 String DATA4 泛型数据列，含义是 MIMETYPE具体 String DATA5 泛型数据列，含义是 MIMETYPE具体 String DATA6 通用数据列，含义是 MIMETYPE具体 String DATA7 泛型数据列，含义是 MIMETYPE具体 String DATA8 泛型数据列，含义是 MIMETYPE具体 String DATA9 泛型数据列，含义是 MIMETYPE具体 String DATA_VERSION 此数据记录的版本。 String IS_PRIMARY 这是否属于其原始联系人的主要条目。 String IS_READ_ONLY “只读”标志：默认情况下为“0”，如果除了同步适配器以外不能修改或删除该行，则为“1”。 String IS_SUPER_PRIMARY 这是否属于它所属类别的主要入口。 String MIMETYPE 该行表示的项目的MIME类型。 String RAW_CONTACT_ID 此数据所属的 _ID的引用。 String RES_PACKAGE 为此数据行创建 Resources对象时使用的包名称。 String SYNC1 同步适配器使用的通用列。 String SYNC2 同步适配器使用的通用列。 String SYNC3 同步适配器使用的通用列。 String SYNC4 同步适配器使用的通用列。
From interface android.provider.ContactsContract.StatusColumns int AVAILABLE 允许的值为 PRESENCE 。 int AWAY 允许的值为 PRESENCE 。 int CAPABILITY_HAS_CAMERA 允许的标志为 CHAT_CAPABILITY 。 int CAPABILITY_HAS_VIDEO 允许的标志为 CHAT_CAPABILITY 。 int CAPABILITY_HAS_VOICE 允许的国旗 CHAT_CAPABILITY 。 String CHAT_CAPABILITY 联系人的音频/视频聊天功能级别。 int DO_NOT_DISTURB 允许的值为 PRESENCE 。 int IDLE 允许的值为 PRESENCE 。 int INVISIBLE 允许的值为 PRESENCE 。 int OFFLINE 允许的值为 PRESENCE 。 String PRESENCE 联系人的最新存在级别。 String PRESENCE_CUSTOM_STATUS 此常数在API级别8中已弃用。请使用STATUS String PRESENCE_STATUS 此常数在API级别8中已弃用。请使用PRESENCE String STATUS 联系最新状态更新。 String STATUS_ICON 状态更新源图标的资源ID。 String STATUS_LABEL 描述状态更新源的标签的资源ID，例如 String STATUS_RES_PACKAGE 包含此状态资源的包：标签和图标。 String STATUS_TIMESTAMP 插入/更新最新状态的绝对时间（以毫秒为单位）。
From interface android.provider.ContactsContract.RawContactsColumns String ACCOUNT_TYPE_AND_DATA_SET 帐户类型和数据集的串联（用正斜杠分隔） - 如果数据集为空，则与帐户类型相同。 String AGGREGATION_MODE 此联系人的聚合模式。 String BACKUP_ID 其帐户中每个raw_contact的持久性唯一标识。 String CONTACT_ID 此数据属于 _ID的引用。 String DATA_SET 该行属于该帐户内的数据集。 String DELETED “已删除”标志：默认为“0”，如果该行已被标记为删除，则为“1”。 String METADATA_DIRTY 表示原始联系人的元数据已更改的标志，并且其元数据需要由服务器同步。 String RAW_CONTACT_IS_READ_ONLY “只读”标志：默认情况下为“0”，如果除了同步适配器以外不能修改或删除该行，则为“1”。 String RAW_CONTACT_IS_USER_PROFILE 反映此原始联系人是否属于用户的个人资料条目的标志。
From interface android.provider.ContactsContract.ContactsColumns String CONTACT_LAST_UPDATED_TIMESTAMP 此联系人上次更新时的时间戳（自纪元起的毫秒数）。 String DISPLAY_NAME 联系人的显示名称。 String HAS_PHONE_NUMBER 指示该联系人是否至少有一个电话号码的指示符。 String IN_DEFAULT_DIRECTORY 反映联系人是否存在于默认目录内的标志。 String IN_VISIBLE_GROUP 反映此联系人的任何 ContactsContract.CommonDataKinds.GroupMembership的 GROUP_VISIBLE状态的标志。 String IS_USER_PROFILE 反映该联系人是否代表用户的个人资料条目的标志。 String LOOKUP_KEY 一个不透明的值，包含有关如何查找联系人（如果其行ID由于同步或聚合而更改）的提示。 String NAME_RAW_CONTACT_ID 参考RawContacts表中保存联系人姓名的行。 String PHOTO_FILE_ID 全尺寸照片的照片文件ID。 String PHOTO_ID 参照保存照片的数据表中的行。 String PHOTO_THUMBNAIL_URI 可用于检索联系人照片缩略图的URI。 String PHOTO_URI 可用于检索联系人的全尺寸照片的URI。
From interface android.provider.ContactsContract.ContactNameColumns String DISPLAY_NAME_ALTERNATIVE 显示名称的替代表示，例如“姓氏优先”，而不是“西方名字的第一个名字”。 String DISPLAY_NAME_PRIMARY 基于联系人的最佳可用信息（例如，如果名称不可用，可能是电子邮件地址），显示标准文本作为联系人的显示名称。 String DISPLAY_NAME_SOURCE 用作联系人显示名称的数据种类，如结构化名称或电子邮件地址。 String PHONETIC_NAME PHONETIC_NAME_STYLE指定拼音字母中的全名的发音。 String PHONETIC_NAME_STYLE 用于表示 PHONETIC_NAME的拼音字母表。 String SORT_KEY_ALTERNATIVE 根据全名的替代表示排序键， DISPLAY_NAME_ALTERNATIVE 。 String SORT_KEY_PRIMARY 排序键考虑了基于地区的传统，用于在地址簿中对姓名进行排序。
From interface android.provider.ContactsContract.ContactOptionsColumns String CUSTOM_RINGTONE 与联系人关联的自定义铃声的URI。 String LAST_TIME_CONTACTED 上次与联系人联系的时间。 String PINNED 触点被固定的位置。 String SEND_TO_VOICEMAIL 是否应始终将联系人发送到语音邮件。 String STARRED 该联系人是否已主演？ 类型：INTEGER（布尔值） String TIMES_CONTACTED 联系人联系的次数 类型：INTEGER
From interface android.provider.ContactsContract.ContactStatusColumns String CONTACT_CHAT_CAPABILITY 联系聊天功能。 String CONTACT_PRESENCE 联系人在线状态。 String CONTACT_STATUS 联系人的最新状态更新。 String CONTACT_STATUS_ICON 联系人状态图标的资源ID。 String CONTACT_STATUS_LABEL 描述联系人状态来源的标签的资源ID，例如 String CONTACT_STATUS_RES_PACKAGE 包含此状态资源的包：标签和图标。 String CONTACT_STATUS_TIMESTAMP 插入/更新最新状态的绝对时间（以毫秒为单位）。
From interface android.provider.ContactsContract.DataUsageStatColumns String LAST_TIME_USED 最后一次（以毫秒为单位）使用了这个 ContactsContract.Contacts.Data 。 String TIMES_USED 引用的 ContactsContract.Contacts.Data已被使用的次数。

Inherited methods

From class java.lang.Object Object clone() 创建并返回此对象的副本。 boolean equals(Object obj) 指示其他某个对象是否“等于”这一个。 void finalize() 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 final Class<?> getClass() 返回此 Object的运行时类。 int hashCode() 返回对象的哈希码值。 final void notify() 唤醒正在等待该对象监视器的单个线程。 final void notifyAll() 唤醒在该对象监视器上等待的所有线程。 String toString() 返回对象的字符串表示形式。 final void wait(long millis, int nanos) 导致当前线程等待，直到另一个线程为该对象调用方法 notify()或方法 notifyAll() ，或者其他线程中断当前线程或经过一定的实时时间。 final void wait(long millis) 导致当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法或经过了指定的时间量。 final void wait() 导致当前线程等待，直到另一个线程调用此对象的方法 notify()或方法 notifyAll() 。

Constants

String CONTENT_TYPE

String EXTRA_ADDRESS_BOOK_INDEX

 Example:

 import android.provider.ContactsContract.Contacts;

 Uri uri = Contacts.CONTENT_URI.buildUpon()
          .appendQueryParameter(Contacts.EXTRA_ADDRESS_BOOK_INDEX, "true")
          .build();
 Cursor cursor = getContentResolver().query(uri,
          new String[] {Contacts.DISPLAY_NAME},
          null, null, null);
 Bundle bundle = cursor.getExtras();
 if (bundle.containsKey(Contacts.EXTRA_ADDRESS_BOOK_INDEX_TITLES) &&
         bundle.containsKey(Contacts.EXTRA_ADDRESS_BOOK_INDEX_COUNTS)) {
     String sections[] =
             bundle.getStringArray(Contacts.EXTRA_ADDRESS_BOOK_INDEX_TITLES);
     int counts[] = bundle.getIntArray(Contacts.EXTRA_ADDRESS_BOOK_INDEX_COUNTS);
 }
 

String EXTRA_ADDRESS_BOOK_INDEX_COUNTS

String EXTRA_ADDRESS_BOOK_INDEX_TITLES

String VISIBLE_CONTACTS_ONLY

Fields

Uri CONTENT_URI

Public methods

Uri getContactLookupUri (ContentResolver resolver, 
                Uri dataUri)