ContactsContract.Data 类

定义

[Android.Runtime.Register("android/provider/ContactsContract$Data", DoNotGenerateAcw=true)]
public sealed class ContactsContract.Data : Java.Lang.Object

[<Android.Runtime.Register("android/provider/ContactsContract$Data", DoNotGenerateAcw=true)>]
type ContactsContract.Data = class
    inherit Object

继承

Object

Object

ContactsContract.Data

属性

RegisterAttribute

注解

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

<h3>数据类型</h3>

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

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

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

按照约定， #DATA15 用于存储 BLOB（二进制数据）。

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

同样，不应为对方的帐户类型引入新类型的数据。 例如，如果将“收藏夹歌曲”的数据行添加到 Google 帐户拥有的原始联系人，则不会同步到服务器，因为 Google 同步适配器不知道如何处理此类数据。 因此，通常会引入新的数据类型以及新的帐户类型，即新的同步适配器。

<h3>Batch 操作</h3>

可以使用传统ContentResolver#insertContentResolver#update行和ContentResolver#delete方法插入/更新/删除数据行，但基于一批ContentProviderOperation的新机制几乎在所有情况下都是更好的选择。 批处理中的所有操作都在单个事务中执行，这可确保原始联系人的手机端和服务器端状态始终一致。 此外，基于批处理的方法效率更高：不仅在单个事务中执行数据库操作更快，而且向内容提供程序发送一批命令可以节省大量时间，从而在进程与运行内容提供程序的进程之间进行上下文切换时节省大量时间。

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

若要避免数据库的此类锁定，请确保在批处理中插入“生成点”。 生成点向内容提供程序指示在执行下一个操作之前，它可以提交已进行的更改、向其他请求生成、打开另一个事务并继续处理操作。 生成点不会自动提交事务，但前提是有另一个请求正在等待数据库。 通常，同步适配器应在批处理中每个原始接触操作序列的开头插入一个生成点。 请参阅 ContentProviderOperation.Builder#withYieldAllowed(boolean)。

<h3>Operations</h3><dl><dt><b>Insert</b></dt><dd>

可以使用传统 ContentResolver#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);

</p><dt><b>Update</b></dt><dd>

与插入一样，更新可以增量完成或作为批处理，批处理模式是首选方法：

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

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

</p></dd<>dt><b>Delete</b></dt><dd>

与插入和更新一样，可以使用该方法或使用 ContentProviderOperation 进行 ContentResolver#delete 删除：

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);

</p></dd<>dt><b>Query</b></dt><dd>

<dl><dt>查找给定联系人</dt><dd 的给定类型的所有数据>

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);

</p>

</dd><dt>查找给定原始联系人</dt<>dd 的给定类型的所有数据>

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);

</dd><dt>查找给定原始联系人</dt><dd> 大多数同步适配器将想要读取原始联系人的所有数据行以及原始联系人本身。 因此，应使用 RawContactsEntity. 另请参阅 RawContacts。 </dd/dl<>/p<>/dd<>/dl><h2>Columns</h2><>

可通过查询使用 Data#CONTENT_URI 许多列。 为了获得最佳性能，应将投影显式指定为仅需要这些列。

<table class=“jd-sumtable”><tr><th colspan='4'Data></th<>/tr><><tr td style=“width： 7em;”>long</td><td style=“width： 20em;”>#_ID</td><td style=“width： 5em;”>只读</td><td>行 ID。 同步适配器应尝试在更新期间保留行 ID。 换句话说，删除和重新插入数据行是个坏主意。 同步适配器应始终执行更新。</td></tr><tr><td>String</td><td/td td><#MIMETYPE<>> read/write-once</td td td><>

此行表示的项的 MIME 类型。 常见 MIME 类型的示例包括：<ul<>liCommonDataKinds.StructuredName StructuredName.CONTENT_ITEM_TYPE></li>CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE><<<CommonDataKinds.Photo Photo.CONTENT_ITEM_TYPECommonDataKinds.Email Email.CONTENT_ITEM_TYPE><<<>>>/li/><>CommonDataKinds.Organization Organization.CONTENT_ITEM_TYPE<li/><>CommonDataKinds.Im Im.CONTENT_ITEM_TYPE<><>CommonDataKinds.Nickname Nickname.CONTENT_ITEM_TYPE<><>CommonDataKinds.Note Note.CONTENT_ITEM_TYPE<><>CommonDataKinds.StructuredPostal StructuredPostal.CONTENT_ITEM_TYPE<><>CommonDataKinds.GroupMembership GroupMembership.CONTENT_ITEM_TYPE<><>CommonDataKinds.Website Website.CONTENT_ITEM_TYPE<><>CommonDataKinds.Event Event.CONTENT_ITEM_TYPE<><li><CommonDataKinds.Relation Relation.CONTENT_ITEM_TYPE/li>>CommonDataKinds.SipAddress SipAddress.CONTENT_ITEM_TYPE<</li/li></ul>

</td></tr><tr><td>long</td><td td/td><td>>#RAW_CONTACT_ID< read/write-once</td td td<>>此数据所属的表中行RawContacts的 ID。</td></tr><tr><td>int</td><td td<>#IS_PRIMARY<>> read/write</td td td Td><>是否是它所属的原始联系人类型的主要条目。 如果为 true，则为“1”;如果为 false，则为“0”。 </td></tr><tr><td>int</td>><><td td<>#IS_SUPER_PRIMARY read/write</td td><>是否是它所属的聚合联系人类型的主要条目。 任何“超级主数据库”的数据记录也必须是“主要”。 例如，超级主要条目可以解释为其类型的默认联系人值（例如，用于联系人的默认电话号码）。</td></tr><tr><td>int</td><td td#DATA_VERSION<>/td><>只读</td td td>><此数据记录的版本。 每当数据行更改版本时，版本就会上升。 此值单调递增。</td/tr><tr><td>Any type</td td td><<#DATA15<>><#DATA13><#DATA12<>><#DATA10><#DATA9#DATA8>>>#DATA1><#DATA6>#DATA7#DATA5#DATA14><<#DATA4><<<#DATA2>>#DATA3<#DATA11< br/td><td>read/write</td td td<>><>

泛型数据列。 每个列的含义由该 #MIMETYPE列确定。 按照约定， #DATA15 用于存储 BLOB（二进制数据）。

不应使用其含义未为给定 MIMETYPE 显式定义的数据列。 不能保证任何同步适配器都会保留它们。 同步适配器本身不应使用此类列，但应改用 #SYNC1-#SYNC4。

</td></tr><tr><td>Any type</td><td><#SYNC2<>#SYNC1br br>#SYNC3#SYNC4<<>/td><td td>read/write</td td td><>Generic columns for use by sync adapters. 例如，照片行可以在 SYNC1 中存储图像 URL、SYNC2 中的状态（未加载、加载、加载、错误）、SYNC3 中的服务器端版本号和 SYNC4 中的错误代码。</td></tr></table>

来自最新关联状态更新的某些列也可通过隐式联接获得。

<table class=“jd-sumtable”><tr><th colspan='4'Join> with<StatusUpdates /th></tr<>><td style=“width： 7em;”>int</td><td style=“width： 20em;”>#PRESENCE</td><td style=“width： 5em;”>链接到此数据行的只读</td><td Td>IM 状态。 #CONTACT_PRESENCE与包含联系人在所有 IM 行中的状态进行比较。 请参阅 StatusUpdates 各个状态定义。 提供程序可以选择不将此值存储在永久性存储中。 预期是状态将定期更新。 </td/tr><tr><td>String</td>#STATUS<><>>< 只读</td td><td>最新状态更新与此数据行链接。<></td></tr><tr><td>long</td>#STATUS_TIMESTAMP>><<< 只读</td><td>td>：插入/更新此数据行的最新状态的绝对时间（以毫秒为单位）。</td></tr><tr><td>String</td><td/td><<>#STATUS_RES_PACKAGE td>只读</td td td>><包含此状态资源的包：标签和图标。</td/tr><tr><td>long</td><#STATUS_LABEL<><>> 只读</td<>td td>描述链接到此数据行的状态更新源的标签的资源 ID。>< 此资源的范围由 #STATUS_RES_PACKAGE.</td/tr><tr><td>long</td><#STATUS_ICON<><>> 只读</td<>td td>图标的资源 ID，用于链接到此数据行的状态更新源。>< 此资源的范围由 #STATUS_RES_PACKAGE.</td></tr></table>

关联的原始联系人中的某些列也可以通过隐式联接获得。 其他列被排除在此上下文中不感兴趣。

<table class=“jd-sumtable”><tr><th colspan='4'Join> with<ContactsContract.RawContacts /th></tr<>><td style=“width： 7em;”>long</td><td style=“width： 20em;”>#CONTACT_ID</td><td style=“width： 5em;”><只读/td td><>此数据所属表中行Contacts的 ID。</td></tr><tr><td>int</td><td>#AGGREGATION_MODE</td><td>read-only</td td>><SeeRawContacts.</td></tr><tr><td>int</td><td>#DELETED</td><td>read-only</td td>><SeeRawContacts.</td></tr></table>

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

<table class=“jd-sumtable”><tr><th colspan='4'Join> with<ContactsContract.Contacts /th></tr<>><td style=“width： 7em;”>String</td><td style=“width： 20em;”>#LOOKUP_KEY</td><td style=“width： 5em;”>read-only</td td><>See ContactsContract.Contacts</td></tr><><td>String</td><td td<<#DISPLAY_NAME>>> read-only</td>><See ContactsContract.Contacts</td<>/tr>><<tr td>long</<>td td td#PHOTO_ID></<>td td read-only</td>><td>See.<ContactsContract.Contacts/td></tr><tr><td>int</td><td>#IN_VISIBLE_GROUP</td><td>read-only</td td>><SeeContactsContract.Contacts.</td></tr><tr><td>int</td><td>#HAS_PHONE_NUMBER</td><td>read-only</td td>><SeeContactsContract.Contacts.</td></tr><tr><td>int</td><td>#STARRED</td><td>read-only</td td>><SeeContactsContract.Contacts.</td></tr><tr><td>String</td><td>#CUSTOM_RINGTONE</td><td>read-only</td td td>><See.<ContactsContract.Contacts/td></tr><tr><td>int</td><td>#SEND_TO_VOICEMAIL</td><td>read-only</td td>><SeeContactsContract.Contacts.</td></tr><tr><td>int</td><td>#CONTACT_PRESENCE</td><td>read-only</td td>><SeeContactsContract.Contacts.</td></tr><tr><td>String</td><td>#CONTACT_STATUS</td><td>read-only</td td td>><See.<ContactsContract.Contacts/td></tr><tr><td>long</td><td>#CONTACT_STATUS_TIMESTAMP</td><td>read-only</td td td>><See.<ContactsContract.Contacts/td></tr><tr><td>String</td><td>#CONTACT_STATUS_RES_PACKAGE</td><td>read-only</td td td>><See.<ContactsContract.Contacts/td></tr><tr><td>long</td><td>#CONTACT_STATUS_LABEL</td><td>read-only</td td td>><See.<ContactsContract.Contacts/td></tr><tr><td>long</td><td>#CONTACT_STATUS_ICON</td><td>read-only</td td td>><See.<ContactsContract.Contacts/td></tr></table>

适用于 . 的 android.provider.ContactsContract.DataJava 文档

本页的某些部分是根据 Android 开放源代码项目创建和共享的工作进行的修改，并根据 Creative Commons 2.5 属性许可证中所述的术语使用。

字段

属性

方法

显式接口实现

扩展方法

适用于