API翻译 --- Content Provider Basics

Getting data from query results  获取数据的查询结果

Rather than simply displaying query results, you can use them for other tasks. For example, you can retrieve spellings from the user dictionary and then look them up in other providers. To do this, you iterate over the rows in the Cursor:

而不是简单地显示查询结果,您可以使用它们为其他任务。例如,您可以从用户检索拼写字典,然后看他们在其他供应商。要做到这一点,您遍历游标的行:

// Determine the column index of the column named "word"  确定列索引的列命名为“单词”
int index = mCursor.getColumnIndex(UserDictionary.Words.WORD);

/*
 * Only executes if the cursor is valid. The User Dictionary Provider returns null if
 * an internal error occurs. Other providers may throw an Exception instead of returning null.
 */

if (mCursor != null) {
    /*
     * Moves to the next row in the cursor. Before the first movement in the cursor, the
     * "row pointer" is -1, and if you try to retrieve data at that position you will get an
     * exception.
     */
    while (mCursor.moveToNext()) {

        // Gets the value from the column.
        newWord = mCursor.getString(index);

        // Insert code here to process the retrieved word.

        ...

        // end of while loop
    }
} else {

    // Insert code here to report an error if the cursor is null or the provider threw an exception.
}

Cursor implementations contain several "get" methods for retrieving different types of data from the object. For example, the previous snippet uses getString(). They also have a getType() method that returns a value indicating the data type of the column.

游标实现包含多个“获得”的方法获取不同类型的数据对象。例如,前面的代码片段使用getString()。他们也有一个方法()方法,它返回一个值指示该列的数据类型。

Content Provider Permissions

A provider‘s application can specify permissions that other applications must have in order to access the provider‘s data. These permissions ensure that the user knows what data an application will try to access. Based on the provider‘s requirements, other applications request the permissions they need in order to access the provider. End users see the requested permissions when they install the application.

提供商的应用程序可以指定权限,其他应用程序必须以访问提供者的数据。这些权限,确保用户知道数据应用程序将尝试访问。根据供应商的要求,其他应用程序请求所需的权限来访问提供者。最终用户安装应用程序时看到请求的权限。

If a provider‘s application doesn‘t specify any permissions, then other applications have no access to the provider‘s data. However, components in the provider‘s application always have full read and write access, regardless of the specified permissions.

As noted previously, the User Dictionary Provider requires the android.permission.READ_USER_DICTIONARY permission to retrieve data from it. The provider has the separate android.permission.WRITE_USER_DICTIONARY permission for inserting, updating, or deleting data.

如果一个供应商的应用程序不指定任何权限,然后其他应用程序没有对提供者的数据的访问。然而,组件提供商的应用程序总是完整的读和写访问,无论指定的权限。
如前所述,用户词典提供程序需要android.permission。READ_USER_DICTIONARY许可从中检索数据。供应商有android.permission分开。WRITE_USER_DICTIONARY允许插入、更新或删除数据。

To get the permissions needed to access a provider, an application requests them with a <uses-permission> element in its manifest file. When the Android Package Manager installs the application, a user must approve all of the permissions the application requests. If the user approves all of them, Package Manager continues the installation; if the user doesn‘t approve them, Package Manager aborts the installation.

获得所需的权限访问提供者,一个应用程序请求他们< uses-permission >元素的清单文件。Android包管理器安装应用程序时,用户必须批准所有的应用程序请求的权限。如果用户批准所有的包管理器继续安装;如果用户不批准,包管理器中止安装。

The following <uses-permission> element requests read access to the User Dictionary Provider:

以下< uses-permission >元素请求读访问权的用户词典提供程序:

    <uses-permission android:name="android.permission.READ_USER_DICTIONARY">

The impact of permissions on provider access is explained in more detail in the Security and Permissions guide.

提供者访问权限的影响将更加详细地解释安全和权限指南。

Inserting, Updating, and Deleting Data

In the same way that you retrieve data from a provider, you also use the interaction between a provider client and the provider‘s ContentProvider to modify data. You call a method of ContentResolver with arguments that are passed to the corresponding method of ContentProvider. The provider and provider client automatically handle security and inter-process communication.

以同样的方式,你从提供者检索数据,您还可以使用提供者之间的交互的客户端和提供者的ContentProvider修改数据。您调用ContentResolver方法参数传递到相应的方法的内容提供者。提供者和提供者端自动处理安全与进程间通信。

Inserting data

To insert data into a provider, you call the ContentResolver.insert() method. This method inserts a new row into the provider and returns a content URI for that row. This snippet shows how to insert a new word into the User Dictionary Provider:

将数据插入一个提供者,你叫ContentResolver.insert()方法。这种方法将一个新行插入该行的内容提供者和返回一个URI。这个代码片段展示了如何将一个新单词插入到用户词典提供程序:

// Defines a new Uri object that receives the result of the insertion
Uri mNewUri;

...

// Defines an object to contain the new values to insert
ContentValues mNewValues = new ContentValues();

/*
 * Sets the values of each column and inserts the word. The arguments to the "put"
 * method are "column name" and "value"
 */
mNewValues.put(UserDictionary.Words.APP_ID, "example.user");
mNewValues.put(UserDictionary.Words.LOCALE, "en_US");
mNewValues.put(UserDictionary.Words.WORD, "insert");
mNewValues.put(UserDictionary.Words.FREQUENCY, "100");

mNewUri = getContentResolver().insert(
    UserDictionary.Word.CONTENT_URI,   // the user dictionary content URI
    mNewValues                          // the values to insert
);

The data for the new row goes into a single ContentValues object, which is similar in form to a one-row cursor. The columns in this object don‘t need to have the same data type, and if you don‘t want to specify a value at all, you can set a column to null using ContentValues.putNull().

的数据进入一个新行ContentValues对象,在形式上类似于一行光标。这个对象不需要的列有相同的数据类型,如果你不想指定一个值,您可以使用ContentValues.putNull列设置为null()。

The snippet doesn‘t add the _ID column, because this column is maintained automatically. The provider assigns a unique value of _ID to every row that is added. Providers usually use this value as the table‘s primary key.

代码片段不添加_ID列,因为这列是自动维护。_ID的提供者分配一个独特的价值,每一行添加。供应商通常使用该值作为表的主键。

The content URI returned in newUri identifies the newly-added row, with the following format:

内容的URI中返回(newUri识别新添加的行,使用以下格式:

content://user_dictionary/words/<id_value>

The <id_value> is the contents of _ID for the new row. Most providers can detect this form of content URI automatically and then perform the requested operation on that particular row.

< id_value >的内容是_ID新行。大多数提供者可以探测到这种形式的内容自动URI,然后执行所请求的操作,特定的行。

To get the value of _ID from the returned Uri, call ContentUris.parseId().

获得的价值_ID从返回的Uri,叫ContentUris.parseId()。

Updating data

To update a row, you use a ContentValues object with the updated values just as you do with an insertion, and selection criteria just as you do with a query. The client method you use is ContentResolver.update(). You only need to add values to the ContentValues object for columns you‘re updating. If you want to clear the contents of a column, set the value to null.

更新一行,您使用一个ContentValues对象与更新的值就像你插入,和选择标准,正如你查询。客户端使用方法ContentResolver.update()。你只需要将值添加到ContentValues对象列你更新。如果你想清楚的列的内容,将值设置为null。

The following snippet changes all the rows whose locale has the language "en" to a have a locale of null. The return value is the number of rows that were updated:

以下代码片段变化的地区语言的所有行“en”有一个空的区域。返回值是被更新的行数:

// Defines an object to contain the updated values
ContentValues mUpdateValues = new ContentValues();

// Defines selection criteria for the rows you want to update
String mSelectionClause = UserDictionary.Words.LOCALE +  "LIKE ?";
String[] mSelectionArgs = {"en_%"};

// Defines a variable to contain the number of updated rows
int mRowsUpdated = 0;

...

/*
 * Sets the updated value and updates the selected words.
 */
mUpdateValues.putNull(UserDictionary.Words.LOCALE);

mRowsUpdated = getContentResolver().update(
    UserDictionary.Words.CONTENT_URI,   // the user dictionary content URI
    mUpdateValues                       // the columns to update
    mSelectionClause                    // the column to select on
    mSelectionArgs                      // the value to compare to
);

You should also sanitize user input when you call ContentResolver.update(). To learn more about this, read the section Protecting against malicious input.

你也应该当你叫ContentResolver.update清洁用户输入()。要了解更多,请阅读部分防止恶意的输入。

Deleting data

Deleting rows is similar to retrieving row data: you specify selection criteria for the rows you want to delete and the client method returns the number of deleted rows. The following snippet deletes rows whose appid matches "user". The method returns the number of deleted rows.

删除行类似于检索行数据:你指定行你想删除的选择标准和客户方法返回删除的行数。以下代码片段删除行appid匹配的“用户”。该方法返回删除的行数。
// Defines selection criteria for the rows you want to delete
String mSelectionClause = UserDictionary.Words.APP_ID + " LIKE ?";
String[] mSelectionArgs = {"user"};

// Defines a variable to contain the number of rows deleted
int mRowsDeleted = 0;

...

// Deletes the words that match the selection criteria
mRowsDeleted = getContentResolver().delete(
    UserDictionary.Words.CONTENT_URI,   // the user dictionary content URI
    mSelectionClause                    // the column to select on
    mSelectionArgs                      // the value to compare to
);

You should also sanitize user input when you call ContentResolver.delete(). To learn more about this, read the section Protecting against malicious input.

你也应该当你叫ContentResolver.delete清洁用户输入()。要了解更多,请阅读部分防止恶意的输入。

Provider Data Types

Content providers can offer many different data types. The User Dictionary Provider offers only text, but providers can also offer the following formats:

内容提供商可以提供许多不同的数据类型。用户词典提供程序只提供文本,供应商也可以提供以下格式:

• integer 
• long integer (long)
• floating point
• long floating point (double)

Another data type that providers often use is Binary Large OBject (BLOB) implemented as a 64KB byte array. You can see the available data types by looking at the Cursor class "get" methods.

另一个供应商经常使用的数据类型是二进制大对象(BLOB)实现为一个64 kb的字节数组。你可以看到可用的数据类型通过查看光标类“获得”方法。

The data type for each column in a provider is usually listed in its documentation. The data types for the User Dictionary Provider are listed in the reference documentation for its contract class UserDictionary.Words (contract classes are described in the section Contract Classes). You can also determine the data type by calling Cursor.getType().

每一列的数据类型提供者通常列在其文档。数据类型为用户词典提供程序中列出UserDictionary合同类的参考文档。单词(合同类所描述的部分合同类)。您也可以通过调用Cursor.getType确定数据类型()。

Providers also maintain MIME data type information for each content URI they define. You can use the MIME type information to find out if your application can handle data that the provider offers, or to choose a type of handling based on the MIME type. You usually need the MIME type when you are working with a provider that contains complex data structures or files. For example, the ContactsContract.Data table in the Contacts Provider uses MIME types to label the type of contact data stored in each row. To get the MIME type corresponding to a content URI, call ContentResolver.getType().

提供者也维护MIME数据类型信息为每个URI定义内容。您可以使用MIME类型信息找出如果您的应用程序可以处理的数据提供者提供,或选择一个类型的处理基于MIME类型。你通常需要MIME类型正在与一个提供者,其中包含复杂的数据结构或文件。例如,ContactsContract。数据表中的联系人提供程序使用MIME类型标签接触每一行中存储的数据的类型。MIME类型的对应内容URI,叫ContentResolver.getType()。

The section MIME Type Reference describes the syntax of both standard and custom MIME types.

MIME类型引用部分描述的语法标准和定制的MIME类型。

Alternative Forms of Provider Access

Three alternative forms of provider access are important in application development:

三个可选形式的提供者访问是重要的在应用程序开发:

• Batch access: You can create a batch of access calls with methods in the ContentProviderOperation class, and then apply them with ContentResolver.applyBatch().
• 批量访问:您可以创建一个批处理ContentProviderOperation访问调用方法的类,然后将它们应用ContentResolver.applyBatch()。
  
• Asynchronous queries: You should do queries in a separate thread. One way to do this is to use a CursorLoader object. The examples in the Loaders guide demonstrate how to do this.
• 你要做异步查询:查询在一个单独的线程。一种方法是使用一个CursorLoader对象。加载器指南中的示例演示如何做到这一点。
  
• Data access via intents: Although you can‘t send an intent directly to a provider, you can send an intent to the provider‘s application, which is usually the best-equipped to modify the provider‘s data.
• 数据访问通过意图:虽然你不能发送一个意图直接提供者,您可以发送一个意图提供者的应用程序中,这通常是装备修改提供者的数据。
  

Batch access and modification via intents are described in the following sections.

批通过意图访问和修改以下部分中描述。

Batch access

Batch access to a provider is useful for inserting a large number of rows, or for inserting rows in multiple tables in the same method call, or in general for performing a set of operations across process boundaries as a transaction (an atomic operation).

批量访问提供者用于插入大量的行,或者在多个表中插入行相同的方法调用,或一般跨进程执行的一组操作作为一个事务(一个原子操作)。

To access a provider in "batch mode", you create an array of ContentProviderOperation objects and then dispatch them to a content provider with ContentResolver.applyBatch(). You pass the content provider‘s authority to this method, rather than a particular content URI. This allows each ContentProviderOperation object in the array to work against a different table. A call to ContentResolver.applyBatch() returns an array of results.

访问供应商在“批处理模式”,你创建ContentProviderOperation对象数组,然后分派到内容提供商与ContentResolver.applyBatch()。您通过此方法的内容提供者的权威,而不是一个特定的内容URI。这允许每个ContentProviderOperation对象数组中针对不同的工作表。调用ContentResolver.applyBatch()返回一个数组的结果。

The description of the ContactsContract.RawContacts contract class includes a code snippet that demonstrates batch insertion. The Contact Manager sample application contains an example of batch access in its ContactAdder.java source file.

ContactsContract的描述。RawContacts合同类包含一个代码片段,展示了批量插入。联系人管理器的示例应用程序包含一个例子ContactAdder批访问。java源文件。

Data access via intents

Intents can provide indirect access to a content provider. You allow the user to access data in a provider even if your application doesn‘t have access permissions, either by getting a result intent back from an application that has permissions, or by activating an application that has permissions and letting the user do work in it.

意图可以提供间接访问内容提供者。你允许用户访问数据的应用程序提供者即使没有访问权限,通过获得一个结果意图从一个应用程序,该应用程序权限,或通过激活的应用程序的权限,让用户完成工作。

Getting access with temporary permissions

You can access data in a content provider, even if you don‘t have the proper access permissions, by sending an intent to an application that does have the permissions and receiving back a result intent containing "URI" permissions. These are permissions for a specific content URI that last until the activity that receives them is finished. The application that has permanent permissions grants temporary permissions by setting a flag in the result intent:

您可以访问的数据在一个内容提供者,即使你没有适当的访问权限,通过发送一个意图有权限的应用程序和接收返回结果的意图包含“URI”权限。这些权限具体内容URI持续到接收完成他们的活动。永久权限授予临时权限的应用程序通过设置一个标记在结果的意图:

• Read permission: FLAG_GRANT_READ_URI_PERMISSION
• Write permission: FLAG_GRANT_WRITE_URI_PERMISSION

Note: These flags don‘t give general read or write access to the provider whose authority is contained in the content URI. The access is only for the URI itself.

注意:这些旗帜不给一般读或写访问提供者的权威是URI中包含的内容。的访问只是URI本身。

A provider defines URI permissions for content URIs in its manifest, using the android:grantUriPermission attribute of the<provider> element, as well as the <grant-uri-permission> child element of the <provider> element. The URI permissions mechanism is explained in more detail in the Security and Permissions guide, in the section "URI Permissions".

提供者定义URI URI的权限内容清单,使用android:grantUriPermission <供应商>元素的属性,以及< grant-uri-permission > <供应商>元素的子元素。URI的权限机制更详细地解释在安全性和权限指引,在部分“URI权限”。

For example, you can retrieve data for a contact in the Contacts Provider, even if you don‘t have the READ_CONTACTS permission. You might want to do this in an application that sends e-greetings to a contact on his or her birthday. Instead of requesting READ_CONTACTS, which gives you access to all of the user‘s contacts and all of their information, you prefer to let the user control which contacts are used by your application. To do this, you use the following process:

例如,您可以检索数据的接触联系供应商,即使你没有READ_CONTACTS许可。你可能想这样做在一个应用程序,该应用程序发送e-greetings联系在他或她的生日。而不是请求READ_CONTACTS,它给你访问所有用户的接触和他们所有的信息,你喜欢让用户控制哪些联系人使用您的应用程序。要做到这一点,您使用以下过程:

1. Your application sends an intent containing the action ACTION_PICK and the "contacts" MIME type CONTENT_ITEM_TYPE, using the method startActivityForResult().
2. 您的应用程序发送一个包含动作的意图ACTION_PICK CONTENT_ITEM_TYPE“联系人”MIME类型,使用方法startActivityForResult()。
   
3. Because this intent matches the intent filter for the People app‘s "selection" activity, the activity will come to the foreground.
4. 因为这个目的与意图过滤器匹配的人应用的“选择”的活动,活动将出现在前台。
   
5. In the selection activity, the user selects a contact to update. When this happens, the selection activity callssetResult(resultcode, intent) to set up a intent to give back to your application. The intent contains the content URI of the contact the user selected, and the "extras" flags FLAG_GRANT_READ_URI_PERMISSION. These flags grant URI permission to your app to read data for the contact pointed to by the content URI. The selection activity then calls finish() to return control to your application.
6. 在选择活动,用户选择一个联系人更新。当这一切发生的时候,选择活动callssetResult(resultcode意图)建立一个意图回馈您的应用程序。目的包含的内容URI联系用户选中,和“临时演员”旗帜FLAG_GRANT_READ_URI_PERMISSION。这些旗帜格兰特URI允许应用程序读取数据的接触URI指向的内容。选择活动然后调用完成()返回控制您的应用程序。
   
7. Your activity returns to the foreground, and the system calls your activity‘s onActivityResult() method. This method receives the result intent created by the selection activity in the People app.
8. 活动回到前台,和系统调用活动的onActivityResult()方法。这个方法接收结果的意图由人民选择活动应用程序。
   
9. With the content URI from the result intent, you can read the contact‘s data from the Contacts Provider, even though you didn‘t request permanent read access permission to the provider in your manifest. You can then get the contact‘s birthday information or his or her email address and then send the e-greeting.
10. 内容从结果URI的意图,你可以阅读从联系人联系的数据提供者,即使你没有请求永久读访问权限清单中的供应商。然后您可以获取联系人的生日信息或他或她的电子邮件地址,然后发送e-greeting。
    

Using another application

A simple way to allow the user to modify data to which you don‘t have access permissions is to activate an application that has permissions and let the user do the work there.

一个简单的方法,以允许用户修改数据,你没有访问权限是激活的应用程序的权限,让用户做这项工作。

For example, the Calendar application accepts an ACTION_INSERT intent, which allows you to activate the application‘s insert UI. You can pass "extras" data in this intent, which the application uses to pre-populate the UI. Because recurring events have a complex syntax, the preferred way of inserting events into the Calendar Provider is to activate the Calendar app with anACTION_INSERT and then let the user insert the event there.

例如,日历应用程序接受一个ACTION_INSERT意图,它允许您启动应用程序的UI插入。你可以通过“临时演员”数据在这个意图,该应用程序使用预填充UI。因为重复事件有一个复杂的语法,将事件插入日历提供者的首选方法是激活anACTION_INSERT的日历应用程序,然后让用户插入事件。

Contract Classes

A contract class defines constants that help applications work with the content URIs, column names, intent actions, and other features of a content provider. Contract classes are not included automatically with a provider; the provider‘s developer has to define them and then make them available to other developers. Many of the providers included with the Android platform have corresponding contract classes in the package android.provider.

合同类定义常量,帮助应用程序与内容uri,列名,意图行动,内容提供商和其他特性。合同类不包括自动与提供者;提供者的开发人员定义他们,然后让他们提供给其他开发人员。许多Android平台的提供者包括类的包android.provider相应合同。

For example, the User Dictionary Provider has a contract class UserDictionary containing content URI and column name constants. The content URI for the "words" table is defined in the constant UserDictionary.Words.CONTENT_URI. The UserDictionary.Words class also contains column name constants, which are used in the example snippets in this guide. For example, a query projection can be defined as:

例如,用户词典提供程序有一个合同类UserDictionary URI和列名称常量包含内容。URI的内容“单词”表中定义的常数UserDictionary.Words.CONTENT_URI。UserDictionary。文字类还包含列名常量,用于本指南中的示例代码片段。例如,一个查询投影可以定义为:

String[] mProjection =
{
    UserDictionary.Words._ID,
    UserDictionary.Words.WORD,
    UserDictionary.Words.LOCALE
};

Another contract class is ContactsContract for the Contacts Provider. The reference documentation for this class includes example code snippets. One of its subclasses, ContactsContract.Intents.Insert, is a contract class that contains constants for intents and intent data.

另一个合同类是接触ContactsContract提供者。这个类的参考文档包括示例代码片段。它的一个子类,ContactsContract.Intents。插入、是一个合同类,包含意图和目的的常量数据。

MIME Type Reference

Content providers can return standard MIME media types, or custom MIME type strings, or both.

MIME types have the format

内容提供者可以返回标准的MIME媒体类型,或自定义MIME类型字符串,或两者兼而有之。
MIME类型的格式

type/subtype

For example, the well-known MIME type text/html has the text type and the html subtype. If the provider returns this type for a URI, it means that a query using that URI will return text containing HTML tags.

例如,著名的MIME类型text / html文本类型和子类型的html。如果提供者返回这种类型的URI,它意味着一个查询使用这个URI将返回包含HTML标记文本。

Custom MIME type strings, also called "vendor-specific" MIME types, have more complex type and subtype values. The type value is always

定制的MIME类型字符串,也称为“特定于供应商的”MIME类型,有更复杂的类型和子类型值。值类型总是

vnd.android.cursor.dir

for multiple rows, or

vnd.android.cursor.item

for a single row.

单个行。

The subtype is provider-specific. The Android built-in providers usually have a simple subtype. For example, the when the Contacts application creates a row for a telephone number, it sets the following MIME type in the row:

特定于提供程序的子类型。Android内置提供者通常有一个简单的亚型。例如,当联系人应用程序创建一行电话号码,它集以下行MIME类型:

vnd.android.cursor.item/phone_v2

Notice that the subtype value is simply phone_v2.

注意,只是phone_v2子类型值。

Other provider developers may create their own pattern of subtypes based on the provider‘s authority and table names. For example, consider a provider that contains train timetables. The provider‘s authority is com.example.trains, and it contains the tables Line1, Line2, and Line3. In response to the content URI

其他供应商开发人员可以创建自己的模式基于提供者的亚型的权威和表名。例如,考虑一个提供者包含列车时刻表。是com.example提供者的权威。火车,它包含表Line1期,Line3。为了应对内容URI

content://com.example.trains/Line1

for table Line1, the provider returns the MIME type

对于表Line1,提供者返回的MIME类型

vnd.android.cursor.dir/vnd.example.line1

In response to the content URI

为了应对内容URI

content://com.example.trains/Line2/5

for row 5 in table Line2, the provider returns the MIME type

表5为行Line2,提供者返回的MIME类型

vnd.android.cursor.item/vnd.example.line2

Most content providers define contract class constants for the MIME types they use. The Contacts Provider contract class ContactsContract.RawContacts, for example, defines the constant CONTENT_ITEM_TYPE for the MIME type of a single raw contact row.

大部分内容提供商为MIME类型定义合同类常量。联系人ContactsContract提供者契约类。RawContacts,例如,定义了常数CONTENT_ITEM_TYPE MIME类型的单个原始行联系。

Content URIs for single rows are described in the section Content URIs.

内容uri uri单一行部分所描述的内容。