Android Content Provider Tutorial--安卓内容提供者系列3--操作安卓联系人

上一篇链接：Android Content Provider Tutorial--安卓内容提供者系列2--内容提供者的用法

Accessing Contact Information （通过ContentProvider访问联系人信息）

Objectives（学习目标）

After this section, you will be able to:

Describe the primary tables exposed by the system contacts content provider and the data they contain
Perform basic queries on the system contacts content provider

经过这部分的学习，你将能够:

描述系统联系人ContentProvider暴露出来的主要table及其包含的数据
在系统联系人ContentProvider中执行基本的查询操作

Android Contact Management Overview（安卓联系人管理概述）

The Android system contacts content provider manages an extensible database of contact-related information.

Android applications can define accounts, which can store contact information — including custom contact information — in the system contacts provider.
The system contacts provider aggregates the information from all accounts to present unified contact information.

Android系统联系人content provider管理了一个可扩展的联系人相关信息数据库。

Android应用程序可以定义帐号，去存储系统联系人ContentProvider中的联系人信息-包括自定义的联系人信息。
系统联系人ContentProvider会把所有帐户的信息汇总成统一的联系人信息。

For example, Facebook, Twitter, Google applications, and other apps can all define accounts that store contact information in the system contacts provider.

The system contact provider aggregates common contact information from different accounts, so a single Android contact might contain email addresses from a Google account, a Twitter username, phone numbers from Facebook, etc.

例如,Facebook,Twitter,谷歌等应用程序和其他应用程序都可以定义帐户去存储系统联系人ContentProvider中的联系人信息。

系统联系人ContentProvider可以从不同账户中收集同一个联系人的信息,所以一个Android联系人的信息可能会包含一个谷歌帐号的电子邮件地址,一个Twitter帐号的用户名、facebook帐号中的电话号码等等。

Contacts Content Provider Access（访问联系人ContentProvider）

The ContactsContract class and related inner classes and interfaces expose access to the system contacts provider.

The Android system contacts provider manages several tables of contact information, including:

ContactsContract类及其相关内部类和接口暴露了访问系统联系人ContentProvider的方法。

Android系统联系人ContentProvider管理了多个包含联系人信息的表,包括:

ContactsContract.RawContacts

A row in the ContactsContract.RawContacts table represents a set of data describing a person and associated with a single account (for example, one of the user’s Gmail accounts).

ContactsContract.RawContacts表中的一行代表了一组描述一个人,与一个单独的帐户(例如,一个用户的Gmail账户)的数据。

ContactsContract.Contacts

A row in the ContactsContract.Contacts table represents an aggregate of one or more raw contacts presumably describing the same person. When data in or associated with the RawContacts table is changed, the affected aggregate contacts are updated as necessary.

ContactsContract.Contacts表中的一行代表了大概描述同一个人的一个或多个原始联系人的集合。当RawContacts表中的或相关的数据发生变化,受影响的那个联系人集合也会立即更新。

ContactsContract.Data

A row in the ContactsContract.Data table store a single piece of contact information (such as a phone number) and its associated metadata (such as whether it is a work or home number) for a raw contact. The set of data kinds that can be stored in this table is open-ended. There is a predefined set of common kinds, defined by subclasses ofContactsContract.CommonDataKinds, but any application can add its own data kinds.

ContactsContract.Data表中的一行存储了一个原始联系人信息的一小片段(比如一个电话号码)及其相关的元数据(比如到底是工作电话还是家庭电话)。可以存储在这个表中的类似这样的数据类型是无限制的。有一组预定义的常见数据类型,他们是由ContactsContract.CommonDataKinds的子类所定义的,但任何应用程序都可以添加它自己的数据类型。

You application needs the android.permission.READ_CONTACTS permission to perform contact queries, and the android.permission.WRITE_CONTACTS permission to insert, update, or delete contact data.

你的应用程序需要设置 android.permission.READ_CONTACTS权限才能对联系人信息的做查询操作,设置android.permission.WRITE_CONTACTS权限才能插入、更新或删除联系人数据。

Basic Contact Query Example（简单的联系人查询示例）

The following example executes a query returning all contacts that have at least one phone number associated with them:

下面的例子执行一个查询，要求返回至少有一个相关联的电话号码的所有联系人:

import android.provider.ContactsContract.Contacts;

// ...

String[] projection = {
    
    Contacts._ID, Contacts.DISPLAY_NAME};
String selection = Contacts.HAS_PHONE_NUMBER + "=1";
String[] selectionArgs = null;
String orderBy = Contacts.DISPLAY_NAME + " ASC";

Cursor contactsCursor = getContentResolver()
        .query(Contacts.CONTENT_URI, projection, selection, selectionArgs, orderBy);

The tables managed by the contacts provider contain many columns of information. Therefore, when querying the contacts provider, you should always provide a projection argument (a String array of column names to return) to minimize the amount of data copied.

由联系人ContentProvider管理的表包含许多列的信息。因此,当你要查询联系人ContentProvider时,您应该提供一个projection 参数(一个用来返回的列名字符串数组)使得复制的数据量降到最低。

Finding a Contact by Partial Name（通过一部分名称来找到一个联系人）

You can search for contacts based on a partial contact name.

This can be handy for "type-to-filter" functionality.

你可以基于部分联系人名称来搜索联系人。

这对“类型过滤”功能来说很方便。

For filtered queries, use ContactsContract.Contacts.CONTENT_FILTER_URI as the base URI for the query.

The filter argument should be passed as an additional path segment after this URI.

对于过滤查询来说,使用ContactsContract.Contacts.CONTENT_FILTER_URI作为查询的基本URI。

传入的过滤参数应该是作为接着这个URI之后的一个额外的路径部分。

For example:（举个栗子：）

import android.provider.ContactsContract.Contacts;

// ...

Uri lookupUri;
if (TextUtils.isEmpty(filter)) {
    
    
        lookupUri = Contacts.CONTENT_URI;
} else {
    
    
        lookupUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI,
                        Uri.encode(filter));
}

String[] projection = {
    
    Contacts._ID, Contacts.DISPLAY_NAME};
String selection = Contacts.IN_VISIBLE_GROUP + "=1";
String[] selectionArgs = null;
String orderBy = Contacts.DISPLAY_NAME + " ASC";

Cursor contactsCursor = getContentResolver()
        .query(lookupUri, projection, selection, selectionArgs, orderBy);

Finding a Contact by Phone Number（通过电话号码来找到一个联系人）

The ContactsContract.PhoneLookup table represents the result of looking up a phone number

This query is highly optimized for use cases like caller ID.

To perform a lookup you must append the number you want to find to ContactsContract.PhoneLookup.CONTENT_FILTER_URI. For example:

ContactsContract.PhoneLookup表代表查找一个电话号码的结果

这个查询的方法是用例高度优化的来电显示。

要执行查找必须附加ContactsContract.PhoneLookup.CONTENT_FILTER_URI你想找到数量。例如:

import android.provider.ContactsContract.Contacts;
import android.provider.ContactsContract.PhoneLookup;

// ...

String phoneNumber = "415-555-1234";
Uri lookupUri = Uri.withAppendedPath(PhoneLookup.CONTENT_FILTER_URI,
                Uri.encode(phoneNumber));

String[] projection = {
    
    Contacts._ID, Contacts.DISPLAY_NAME};
String selection = Contacts.IN_VISIBLE_GROUP + "=1";
String[] selectionArgs = null;
String orderBy = Contacts.DISPLAY_NAME + " ASC";

Cursor contactsCursor = getContentResolver()
        .query(lookupUri, projection, selection, selectionArgs, orderBy);

Retrieving Contact Data(检索联系人数据)

Given a contact ID, you can retrieve information for that contact by querying the ContactsContract.Data table.

ContactsContract.Data is a generic table that can hold any kind of contact data.
The kind of data stored in a given row is specified by the row’s ContactsContract.Data.MIMETYPE column, which determines the meaning of the generic columns DATA1 through DATA15.

给定一个联系人ID,您可以通过查询ContactsContract.Data表来检索他的信息。

ContactsContract.Data是一个可以保存任何类型的联系人数据的表。
存储在一个给定的行里的数据的类型是由该行的ContactsContract.Data.MIMETYPE这一列来指定的,这一列决定了从DATA1 到 DATA15通用列的意义。

ContactsContract defines several pre-defined data kinds, e.g. ContactsContract.CommonDataKinds.Phone, ContactsContract.CommonDataKinds.Email, etc.

As a convenience, these classes define data kind specific aliases for DATA1 etc.
For example, ContactsContract.CommonDataKinds.Phone defines ContactsContract.CommonDataKinds.Phone.NUMBER as an alias for ContactsContract.Data.DATA1.
These data kind classes also define CONTENT_URI and sometimes CONTENT_FILTER_URI fields as a convenience to do queries on the ContactsContract.Data.

ContactsContract定义了多个预定义的数据类型,例如ContactsContract.CommonDataKinds.Phone,ContactsContract.CommonDataKinds.Email等。

为了方便起见,这些类给DATA1等等这些列的数据类型定义了特殊的别名。
例如,ContactsContract.CommonDataKinds.Phone定义了ContactsContract.CommonDataKinds.Phone.NUMBER作为ContactsContract.Data.DATA1的别名。
为了查询ContactsContract.Data数据更方便，这些数据类型类也会定义CONTENT_URI字段，有时候是CONTENT_FILTER_URI字段。

Example, Retrieving Contact Phone Numbers（一个检索联系人电话号码的例子）

The following example shows how to retrieve all of the phone numbers associated with a given contact:

下面的示例展示了如何检索与给定联系人相关的所有电话号码:

Uri baseUri = ContactsContract.CommonDataKinds.Phone.CONTENT_URI;
String[] projection = {
    
    
        CommonDataKinds.Phone.TYPE,
        CommonDataKinds.Phone.NUMBER
};
long contactID = 123;
String selection = Data.CONTACT_ID + "=" + contactID;
String[] selectionArgs = null;
String orderBy = null;

Cursor phoneCursor = getContentResolver()
        .query(baseUri, projection, selection, selectionArgs, orderBy);

int typeIdx = phoneCursor.getColumnIndex(CommonDataKinds.Phone.TYPE);
int phoneIdx = phoneCursor.getColumnIndex(CommonDataKinds.Phone.NUMBER);

while (dataCursor.moveToNext()) {
    
    
        int phoneTypeResource = CommonDataKinds.Phone.getTypeLabelResource(dataCursor.getInt(typeIdx));
        String phoneType = getString(phoneTypeResource);
        String phoneNumber = dataCursor.getString(phoneIdx);
        builder.append(phoneType)
                .append(": ")
                .append(phoneNumber)
                .append("\n\t");
}

Topic Summary（总结）

You should now be able to:

Describe the primary tables exposed by the system contacts content provider and the data they contain
Perform basic queries on the system contacts content provider

现在你应该可以：

描述系统联系人ContentProvider暴露出来的主要的表，和这些表包含的数据
对系统联系人ContentProvider执行基本的查询操作

下一篇链接：Android Content Provider Tutorial--安卓内容提供者系列4--如何创建内容提供者