写在前面的话：说两点。1、很荣幸自己的两篇文章《 Android官方文档之App Components（Intents and Intent Filters）》、《Android官方文档之App Components（Common Intents）》被郭霖老师转载了，一方面说明我的博客内容得到了认可，另一方面也鞭策我继续写出质量更高的博文；2、最近在翻译官方文档，今天翻墙一看，发现页面改版了，而且居然默认显示了中文的文档（其实改版以前也有官方的中文文档，只是默认显示英文而已，另外中文官方文档只翻译了一部分，还有一些未翻译），我就在想，到底还是否继续翻译，我的答案是肯定的：之前已经翻译了10多篇文档，在这期间，我不仅提升了英文的阅读水平，还对Android的知识有了新的收获，所以我将继续翻译下去，当然了，如果遇到不会翻译的地方我就会查看官方中文文档，我争取翻译得比官方文档还好：）

创建ContentProvider前需要考虑的事（Before You Start Building）

• 如您的程序需要向外界应用提供以下内容之一，那么程序中需要创建ContentProvider：
  • 需要向其他应用程序提供复杂的数据或文件（ offer complex data or files to other applications）；
  • 希望用户能从您的应用向其他应用复制复杂的数据（allow users to copy complex data from your app into other apps）；
  • 希望使用搜索框架提供提供定制的搜索建议（ provide custom search suggestions using the search framework）。

• 为您的应用程序设计原始存储。ContentProvider以如下两种方式提供数据：
  • 文件数据（File data）：在应用程序的的私有空间中，数据以不同形式的文件存储，如照片（photos）、音频（audio） 、视频（videos）等。为了能让其他应用程序读取您的程序中的这些文件，需要provider作为媒介。
  • 结构化数据（”Structured” data）：数据存储于数据库、数据或其他类似的结构中。存储的数据支持行列表的形式（Store the data in a form that’s compatible with tables of rows and columns）。每行代表一个实体（entity），如个人信息等。每列表示每个实体的不同属性，如人的身高、体重等。这些表结构及其数据信息可以存储于SQLite数据库中。
• 实现ContentProvider中的方法；
• 为ContentProvider定义authority字符串，该字符串包含了content URI以及表中列的字段。若您希望ContentProvider可以处理intent，那么还需定义intent的action、data、flag等。并为provider定义其他应用程序需要访问它的权限。

设计数据存储（Designing Data Storage）

• Android提供了SQLite数据库API以访问面向表的数据存储（to store table-oriented data），SQLiteOpenHelper可帮助您创建数据库，而SQLiteDatabase类是访问数据库的基础类。provider提供给外界程序的内容表现为一张或多张表。
• Android提供了多个面向文件存储的API，关于文件存储，您可以参考这个链接 Data Storage，若您希望创建一个访问媒体文件（如音乐或多媒体）的provider，那么该provider还能提供访问表和其他文件的方法。
• 使用java.net或android.net包中的API可以访问网络数据，您可以将网络数据同步到本地（如同步到本地的数据库中），并将本地数据以表或文件的形式提供给程序。

数据设计的注意事项（Data design considerations）

• 必须为数据表提供主键（primary key）以保证数据的唯一性，您也可以将此值链接至其他表的相关行中（外键，foreign key），尽管可以为该列的字段取任何名字，但推荐使用BaseColumns._ID作为其字段。因为当需要将表中数据绑定到ListView上时，ListView需要一个列名为_ID的字段。

• 若您需要提供bitmap图像，或者大型的面向文件的数据，最好将这些数据存储在一个文件中并直接提供而不是将它们存储在表中。

• 使用二进制大型对象数据类型（Binary Large OBject (BLOB) ）存储大小或结构会发生变化的数据，您可以使用 BLOB 列来存储缓冲协议（ protocol buffer）或JSON结构的数据（JSON structure）。

设计Content URIs（Designing Content URIs）

设置authority（Designing an authority）

设置path（Designing a path structure）

处理content URI的ID（Handling content URI IDs）

Content URI的格式 （Content URI patterns）

• “*”表示任意长度的任意字符；
• “#”表示任意长度的数字。

• content://com.example.app.provider/table1: 查询table1；
• content://com.example.app.provider/table2/dataset1：查询table2中的dataset1；
• content://com.example.app.provider/table2/dataset2：查询table2中的dataset2；
• content://com.example.app.provider/table3: A table called table3：查询table3；
• content://com.example.app.provider/table3/1：查询table3中行ID为1的条目；

content://com.example.app.provider/*

content://com.example.app.provider/table2/*

在provider中，下面的写法可以匹配第五个URI：

content://com.example.app.provider/table3/#

public class ExampleProvider extends ContentProvider {
...
    // Creates a UriMatcher object.
    private static final UriMatcher sUriMatcher;
...
    /*
     * The calls to addURI() go here, for all of the content URI patterns that the provider
     * should recognize. For this snippet, only the calls for table 3 are shown.
     */
...
    /*
     * Sets the integer value for multiple rows in table 3 to 1. Notice that no wildcard is used
     * in the path
     */
    sUriMatcher.addURI("com.example.app.provider", "table3", 1);

    /*
     * Sets the code for a single row to 2. In this case, the "#" wildcard is
     * used. "content://com.example.app.provider/table3/3" matches, but
     * "content://com.example.app.provider/table3 doesn‘t.
     */
    sUriMatcher.addURI("com.example.app.provider", "table3/#", 2);
...
    // Implements ContentProvider.query()
    public Cursor query(
        Uri uri,
        String[] projection,
        String selection,
        String[] selectionArgs,
        String sortOrder) {
...
        /*
         * Choose the table to query and a sort order based on the code returned for the incoming
         * URI. Here, too, only the statements for table 3 are shown.
         */
        switch (sUriMatcher.match(uri)) {

            // If the incoming URI was for all of table3
            case 1:

                if (TextUtils.isEmpty(sortOrder)) sortOrder = "_ID ASC";
                break;

            // If the incoming URI was for a single row
            case 2:

                /*
                 * Because this URI was for a single row, the _ID value part is
                 * present. Get the last path segment from the URI; this is the _ID value.
                 * Then, append the value to the WHERE clause for the query
                 */
                selection = selection + "_ID = " uri.getLastPathSegment();
                break;

            default:
            ...
                // If the URI is not recognized, you should do some error handling here.
        }
        // call the code to actually do the query
    }

实现ContentProvider类（Implementing the ContentProvider Class）

需实现的方法（Required methods）

• query()：从provider中查询数据，并将结果以Cursor对象返回；
• insert()：向provider的某张表中插入一行新的数据，方法回传的Uri参数用于指向需要插入的表，而ContentValue参数用于回传插入的内容，该方法返回新插入行的Uri地址；
• update()：用于修改某些行，并返回修改的行数；
• delete()：删除某些行，并返回删除的行数。
• getType()：返回content URI对应的MIME 类型（Return the MIME type corresponding to a content URI），该方法的具体含义请您参考后续章节。
• onCreate()：该方法用于初始化ContentProvider，当ContentProvider被实例化后，该方法将被立刻回调。！请注意：只有ContentResolver试图访问您的ContentProvider，该实例才会被创建（Notice that your provider is not created until a ContentResolver object tries to access it）。

• 除了onCreate()方法外，其余方法均可在多个线程中同时调用，这就需要保证线程安全（can be called by multiple threads at once, so they must be thread-safe）。
• 避免在onCreate()方法中做耗时操作（Avoid doing lengthy operations in onCreate()）。当方法中涉及的资源用到时再加载（Defer initialization tasks until they are actually needed）。
• 尽管您必须实现这些方法，但是您可以不做任何操作。比如说，当您需要向表中插入数据时，若只是在insert()中返回0，则数据插入操作不会成功。

实现query()方法（Implementing the query() method）

若您是使用SQLite数据库存储数据，那么调用SQLiteDatabase的query()方法返回的Cursor对象可以直接作为该方法的返回值（you can simply return the Cursor returned by one of the query() methods of the SQLiteDatabase class）。若未查询到匹配结果，那么返回的Cursor对象中，其getCount()方法应返回0。若出现异常，Cursor对象应返回null。

若您并没有使用SQLite数据库存储数据，那么应根据具体数据的结构，使用系统提供的Cursor子类对象作为返回值。比如，MatrixCursor是Cursor的一个子类，它可以指向每一行都是一个Object对象数组的矩阵结构（each row is an array of Object）。调用该类的addRow()方法可添加一行数据。

实现insert()方法（Implementing the insert() method）

实现delete()方法（Implementing the delete() method）

实现update()方法（Implementing the update() method）

实现onCreate()方法（Implementing the onCreate() method）

比方说，您可以在ContentProvider.onCreate()方法中创建一个SQLiteOpenHelper对象，第一次打开数据库时创建SQL表，实现方式是调用getWritableDatabase()方法，调用该方法会立即触发SQLiteOpenHelper.onCreate()方法的回调，可以在该方法中创建数据库和表。

下面将以代码片段的方式展示上述实现过程：

public class ExampleProvider extends ContentProvider

    /*
     * Defines a handle to the database helper object. The MainDatabaseHelper class is defined
     * in a following snippet.
     */
    private MainDatabaseHelper mOpenHelper;

    // Defines the database name
    private static final String DBNAME = "mydb";

    // Holds the database object
    private SQLiteDatabase db;

    public boolean onCreate() {

        /*
         * Creates a new helper object. This method always returns quickly.
         * Notice that the database itself isn‘t created or opened
         * until SQLiteOpenHelper.getWritableDatabase is called
         */
        mOpenHelper = new MainDatabaseHelper(
            getContext(),        // the application context
            DBNAME,              // the name of the database)
            null,                // uses the default SQLite cursor
            1                    // the version number
        );

        return true;
    }

    ...

    // Implements the provider‘s insert method
    public Cursor insert(Uri uri, ContentValues values) {
        // Insert code here to determine which table to open, handle error-checking, and so forth

        ...

        /*
         * Gets a writeable database. This will trigger its creation if it doesn‘t already exist.
         *
         */
        db = mOpenHelper.getWritableDatabase();
    }
}

...
// A string that defines the SQL statement for creating a table
private static final String SQL_CREATE_MAIN = "CREATE TABLE " +
    "main " +                       // Table‘s name
    "(" +                           // The columns in the table
    " _ID INTEGER PRIMARY KEY, " +
    " WORD TEXT"
    " FREQUENCY INTEGER " +
    " LOCALE TEXT )";
...
/**
 * Helper class that actually creates and manages the provider‘s underlying data repository.
 */
protected static final class MainDatabaseHelper extends SQLiteOpenHelper {

    /*
     * Instantiates an open helper for the provider‘s SQLite data repository
     * Do not do database creation and upgrade here.
     */
    MainDatabaseHelper(Context context) {
        super(context, DBNAME, null, 1);
    }

    /*
     * Creates the data repository. This is called when the provider attempts to open the
     * repository and SQLite reports that it doesn‘t exist.
     */
    public void onCreate(SQLiteDatabase db) {

        // Creates the main table
        db.execSQL(SQL_CREATE_MAIN);
    }
}

实现与URI对应的MIME类型（Implementing ContentProvider MIME Types）

• getType()：该方法必须实现（One of the required methods that you must implement for any provider）；
• getStreamTypes()：若您的provider提供了文件访问，需实现该方法（A method that you’re expected to implement if your provider offers files.

  ）。

表的MIME类型（MIME types for tables）

常见的MIME类型有 text,、HTML、JPEG 等。如需查看MIME的全部类型及解析，您可以点击这个链接：《IANA MIME Media Types》。

• Type 部分：vnd
• Subtype 部分：
  • 若回传的Uri指向表的某一行，那么格式应为：android.cursor.item/
  • 若回传的Uri指向表的多行（一行以上），那么格式应为：android.cursor.dir/
• Provider-specific 部分：vnd.<name>.<type>。其中<name>应是唯一的，<type>能体现指向Uri的唯一性。好的做法是将<name>命名为公司名的倒序或是应用程序的包名，将<type>命名为指定的表名。

vnd.android.cursor.dir/vnd.com.example.provider.table1

vnd.android.cursor.item/vnd.com.example.provider.table1

文件的MIME类型（MIME types for files）

String mimeTypeFilter)方法。该方法返回一个String数组，数组中的每一项表示传入的Uri所指向的文件类型（for the files your provider can return for a given content URI），若其他应用程序只对某个特定类型的文件感兴趣，那么应给getStreamTypes()方法的第二个参数传入感兴趣的文件的MIME类型。

比如说，provider提供了 .jpg、.png 和 .gif类型的图像文件，其他应用程序调用ContentResolver.getStreamTypes()方法并传入过滤参数image/*，那么系统将返回如下所示的String数组：

{ "image/jpeg", "image/png", "image/gif"}

{"image/jpeg"}

实现Contract类（Implementing a Contract Class）

为ContentProvider设置权限（Implementing Content Provider Permissions）

• 默认情况下，存储在设备内部存储的文件对您的应用货provider是私有的；
• 程序中创建的SQLiteDatabase数据库只有您自己的程序和provider可以操作；
• 默认情况下，外部存储中的文件是公开的（data files that you save to external storage are public and world-readable），您无需使用provider访问外存中的文件。因为这些文件使用系统提供的API就能访问。

实现权限（Implementing permissions）

这需要在manifest中设置<permission>标签，并由android:name属性指定，指定的权限应具有唯一性。如为provider添加只读的权限：

com.example.app.provider.permission.READ_PROVIDER

• 统一的读写provider级别权限（Single read-write provider-level permission）：在<provider>标签中由android:permission属性指定。
• 单独的读写provider级别权限（Separate read and write provider-level permission）：在<provider>标签中由android:readPermission 和android:writePermission属性指定。该权限高于上面的统一读写权限（They take precedence over the permission required by android:permission）。
• path级别的权限（Path-level permission）：在provider的content URI中设置只读、只写、或可读可写的权限。在<provider>的子标签<path-permission>中设定您需要控制的每一个URI。您可以为每一URI指定只读权限、或只写权限、或可读可写权限，其中只读或只写得权限高于可读可写权限。而path级别权限高于provider级别权限。

<provider> 标签（The <provider> Element）

• Authority：使用android:authorities属性配置。该属性为provider提供一个唯一的标识。
• Provider class name：使用android:name属性定义。属性值为定制的ContentProvider的全限定类名。
• Permissions：指定了其他应用需要访问该provider所需声明的权限。
  • android:grantUriPermssions：临时权限；
  • android:permission：provider范围内的读写权限；
  • android:readPermission：provider范围的只读权限；
  • android:writePermission：provider范围的只写权限。

• Startup and control attributes：下列属性决定了系统何时以及如何启动provider、provider的特性、以及运行时设置：
  • android:enabled：是否允许系统启动provider；
  • android:exported：是否允许其他应用程序访问provider；
  • android:initOrder：指定同一进程中，相对于其他provider的启动顺序；
  • android:multiProcess：是否允许在与client端相同的进程中启动provider；
  • android:process：provider运行的进程名；
  • android:syncable：provider中的数据与服务器上的数据同步。

• Informational attributes：为provider提供可选的图标和标题。
  • android:icon：指定一个drawable资源，该图标出现在设置 > 应用 > 全部 中应用列表内的provider标签旁；
  • android:label：描述provider（和）或其数据的信息标签。 该标签出现在设置 > 应用 > 全部中的应用列表内。