ContentProvider

ContentProvider

ContentProvider ()

构建一个ContentProvider实例。 内容提供者必须是declared in the manifest ，由ContentResolver访问，并由系统自动创建，因此应用程序通常不直接创建ContentProvider实例。

在构建时，该对象未初始化，大多数字段和方法都不可用。 子类应该自行初始化为onCreate() ，而不是构造函数。

内容提供者在应用程序启动时在应用程序主线程上创建。 构造函数不能执行冗长的操作，否则应用程序启动将会延迟。

applyBatch

ContentProviderResult[] applyBatch (ArrayList<ContentProviderOperation> operations)

重写此操作以处理执行一批操作的请求，或者默认实现将迭代操作并在每个操作上调用apply(ContentProvider, ContentProviderResult[], int) 。 如果所有对apply(ContentProvider, ContentProviderResult[], int)调用apply(ContentProvider, ContentProviderResult[], int)成功，那么将会返回一个ContentProviderResult数组，其元素数与操作数一样多。 如果有任何呼叫失败，则实施有多少个生效。 该方法可以从多个线程调用，如Processes and Threads中所述 。

attachInfo

void attachInfo (Context context, 
                ProviderInfo info)

在被实例化之后，这被称为告诉内容提供者自己。

bulkInsert

int bulkInsert (Uri uri, 
                ContentValues[] values)

重写此操作以处理插入一组新行的请求，或者默认实现将迭代这些值并在每个值上调用insert(Uri, ContentValues) 。 作为礼节，插入后请拨打notifyChange() 。 该方法可以从多个线程中调用，如Processes and Threads中所述 。

call

Bundle call (String method, 
                String arg, 
                Bundle extras)

调用提供者定义的方法。 这可以用来实现对于类似表格的模型更便宜和/或不自然的接口。

警告：除了应用程序访问提供程序的基本功能外，框架不会对此内容提供程序中的条目进行权限检查。 例如，它不知道正在执行的调用是否可以读取或写入提供程序中的数据，因此无法强制执行这些单独的权限。 此方法的任何实现都必须对来电进行自己的权限检查，以确保它们被允许。

canonicalize

Uri canonicalize (Uri url)

实现这一点，以支持引用您的内容提供者的URI的标准化。 规范化的URI是可以跨设备，备份/恢复和其他上下文传输的，并且仍然能够引用相同的数据项。 通常这是通过向URI添加查询参数来实现的，从而允许内容提供者验证传入的规范URI是否引用与最初预期相同的数据，如果不是，则查找该数据（如果存在）当前的环境。

例如，如果内容提供者拥有人，并且其中的普通URI通过行索引创建到该人员数据库中，则该可信表示可以在末尾具有附加查询参数，该参数指定了其预期的人的姓名。 稍后使用该URI调用提供程序将查找该URI的基本索引的行，如果它不匹配或其条目的名称与查询参数中的名称不匹配，请在其数据库上执行查询以查找正确的行进行操作。

如果您实现了对规范化URI的支持，则所有具有URI（包括这个URI）的传入调用都必须执行此验证并恢复其接收到的任何规范化URI。 另外，您还必须实现uncanonicalize(Uri)以删除任何这些URI的规范化。

此方法的默认实现返回null，指示不支持规范URI。

delete

int delete (Uri uri, 
                String selection, 
                String[] selectionArgs)

实现这个来处理删除一行或多行的请求。 执行应该在执行删除时应用选择子句，从而允许操作影响目录中的多个行。 作为礼节，删除后请致电notifyChange() 。 该方法可以从多个线程中调用，如Processes and Threads中所述 。

如果特定的行被删除，该实现负责解析URI末尾的行ID。 也就是说，客户端将传入content://contacts/people/22并且该实现负责在创建SQL语句时解析记录号（22）。

dump

void dump (FileDescriptor fd, 
                PrintWriter writer, 
                String[] args)

将提供者的状态打印到给定的流中。 如果运行“adb shell dumpsys活动提供程序<provider_component_name>”，则会被调用。

getCallingPackage

String getCallingPackage ()

返回在当前线程上发起正在处理的请求的调用方的包名称。 返回的包将被验证属于主叫UID。 如果当前null请求，则返回null 。

处理 getType(Uri)或 getStreamTypes(Uri, String)请求时，将始终返回 null 。

getContext

Context getContext ()

检索此提供程序运行的上下文。仅在调用 onCreate()可用 - 这将在构造函数中返回 null 。

getPathPermissions

PathPermission[] getPathPermissions ()

返回对此内容提供者进行读取和/或写入访问所需的基于路径的权限。 该方法可以从多个线程调用，如Processes and Threads中所述 。

getReadPermission

String getReadPermission ()

将只读访问所需权限的名称返回给此内容提供者。 该方法可以从多个线程调用，如Processes and Threads中所述 。

getStreamTypes

String[] getStreamTypes (Uri uri, 
                String mimeTypeFilter)

由客户端调用以确定此内容提供程序支持的给定URI的数据流类型。 默认实现返回null ，表示没有类型。 如果您的内容提供者存储特定类型的数据，则返回该MIME类型（如果它与给定的mimeTypeFilter匹配）。 如果它可以执行类型转换，则返回与mimeTypeFilter匹配的所有支持的MIME类型的数组。

getType

String getType (Uri uri)

实现这个来处理给定URI处的数据的MIME类型请求。 返回的MIME类型应以vnd.android.cursor.item为单个记录vnd.android.cursor.dir/ ，或vnd.android.cursor.dir/为多个项目vnd.android.cursor.dir/ 。 该方法可以从多个线程中调用，如Processes and Threads中所述 。

请注意，应用程序访问此信息不需要任何权限; 如果您的内容提供者需要读取和/或写入权限，或者未导出，则所有应用程序仍可以调用此方法，而不考虑其访问权限。 这允许他们在调度意图时检索URI的MIME类型。

getWritePermission

String getWritePermission ()

将读取/写入权限所需的权限的名称返回给此内容提供者。 该方法可以从多个线程中调用，如Processes and Threads中所述 。

insert

Uri insert (Uri uri, 
                ContentValues values)

实现这个来处理插入新行的请求。 作为礼节，插入后请致电notifyChange() 。 该方法可以从多个线程中调用，如Processes and Threads中所述 。

onConfigurationChanged

void onConfigurationChanged (Configuration newConfig)

设备配置在组件运行时发生更改时由系统调用。 请注意，与活动不同，当配置更改时，其他组件不会重新启动：它们必须始终处理更改的结果，例如通过重新获取资源。

在调用此函数时，您的Resources对象将被更新为返回与新配置相匹配的资源值。

欲了解更多信息，请阅读Handling Runtime Changes 。 此方法始终在应用程序主线程上调用，并且不得执行冗长的操作。

默认的内容提供者实现什么都不做。 重写此方法以采取适当的操作。 （内容提供者通常不关心屏幕方向等内容，但可能想知道区域设置更改。）

onCreate

boolean onCreate ()

在启动时实现这个以初始化您的内容提供者。 在应用程序启动时，应用程序主线程上的所有注册内容提供者都会调用此方法。 它不能执行冗长的操作，否则应用程序启动将会延迟。

你应该推迟平凡的初始化（如打开，升级和扫描数据库），直到使用内容提供商（通过query(Uri, String[], String, String[], String) ， insert(Uri, ContentValues) ，等等）。 延迟初始化可以使应用程序快速启动，避免不必要的工作（如果提供程序不需要），并停止数据库错误（如完整磁盘）停止应用程序启动。

如果您使用SQLite， SQLiteOpenHelper是一个有用的实用程序类，可以轻松管理数据库，并会在首次使用前自动推迟打开。 如果确实使用SQLiteOpenHelper，请确保避免使用此方法调用getReadableDatabase()或getWritableDatabase() 。 （相反，覆盖onOpen(SQLiteDatabase)以在数据库第一次打开时对其进行初始化。）

onLowMemory

void onLowMemory ()

这在整个系统内存不足时调用，并且主动运行的进程应该修剪内存使用情况。 虽然没有定义它的确切位置，但通常会在所有后台进程都被终止时发生。 也就是说，在达到托管服务和前台UI的杀死进程之前，我们希望避免杀死。

你应该实现这个方法来释放你可能持有的任何缓存或其他不必要的资源。 系统将从此方法返回后为您执行垃圾回收。

优选地，您应该从ComponentCallbacks2实施onTrimMemory(int) ，以基于不同级别的内存需求逐步卸载资源。 该API可用于API级别14和更高的，所以你应该只使用这个onLowMemory()方法，旧版本的回退，可以治疗一样onTrimMemory(int)与TRIM_MEMORY_COMPLETE水平。

默认的内容提供者实现什么都不做。 子类可以重写此方法以采取适当的操作。

onTrimMemory

void onTrimMemory (int level)

当操作系统确定进程从其进程中删除不需要的内存是一个好时机时调用。 例如，当它进入后台并且没有足够的内存来保持尽可能多的后台进程运行时，会发生这种情况。 您不应该与级别的确切值进行比较，因为可能会添加新的中间值 - 如果值大于或等于您感兴趣的级别，通常需要比较。

要在任何点检索处理当前修剪水平，可以使用 ActivityManager.getMyMemoryState(RunningAppProcessInfo) 。

openAssetFile

AssetFileDescriptor openAssetFile (Uri uri, 
                String mode, 
                CancellationSignal signal)

这类似于openFile(Uri, String) ，但可以由需要能够返回文件子部分的提供者实现，这些文件通常是.apk中的资源。 此方法可以从多个线程调用，如Processes and Threads中所述 。

如果你实现这个，你的客户必须能够处理这种文件切片，或者直接使用 openAssetFileDescriptor(Uri, String) ，或者使用更高级别的 ContentResolver.openInputStream或 ContentResolver.openOutputStream方法。

返回的AssetFileDescriptor可以是管道或套接字对，以启用数据流式传输。

如果要实现此操作以返回完整文件，则应该创建 UNKNOWN_LENGTH的AssetFileDescriptor以与无法处理文件子部分的应用程序兼容。

要在Intents中使用，您需要实现getType(Uri)以返回此处使用相同URI返回的数据的适当MIME类型。 这将允许意图解决方案自动确定数据MIME类型，并选择适当的匹配目标作为其操作的一部分。

为了更好地与其他应用程序互操作，建议对于可以打开的任何URI，还支持对其至少包含由 OpenableColumns指定的列的 OpenableColumns 。

openAssetFile

AssetFileDescriptor openAssetFile (Uri uri, 
                String mode)

这类似于openFile(Uri, String) ，但可以由需要能够返回文件子部分的提供者实现，这些文件通常是.apk中的资源。 此方法可以从多个线程中调用，如Processes and Threads中所述 。

如果你实现这个，你的客户必须能够直接使用 openAssetFileDescriptor(Uri, String)或使用更高级别的 ContentResolver.openInputStream或 ContentResolver.openOutputStream方法来处理这种文件切片。

返回的AssetFileDescriptor可以是管道或套接字对，以启用数据流式传输。

如果您正在实现此操作以返回完整文件，则应创建 UNKNOWN_LENGTH的AssetFileDescriptor以与无法处理文件子部分的应用程序兼容。

为了在Intents中使用，您需要实现getType(Uri)以返回此处使用相同URI返回的数据的适当MIME类型。 这将允许意图解决方案自动确定数据MIME类型，并选择适当的匹配目标作为其操作的一部分。

为了更好地与其他应用程序互操作，建议对于可以打开的任何URI，还支持对其至少包含由 OpenableColumns指定的列的 OpenableColumns 。

openFile

ParcelFileDescriptor openFile (Uri uri, 
                String mode, 
                CancellationSignal signal)

重写这个来处理打开一个文件blob的请求。 默认实现总是抛出FileNotFoundException 。 此方法可以从多个线程调用，如Processes and Threads中所述 。

这个方法返回一个ParcelFileDescriptor，它直接返回给调用者。 这样可以在不复制内容的情况下返回大量数据（如图像和文档）。

返回的ParcelFileDescriptor由调用者拥有，因此他们有责任在完成时关闭它。 也就是说，这个方法的实现应该为每个调用创建一个新的ParcelFileDescriptor。

如果以独有的“r”或“w”模式打开，返回的ParcelFileDescriptor可以是管道或套接字对，以启用数据流式传输。 以“rw”或“rwt”模式打开意味着磁盘上的文件支持查找。

如果您需要检测什么时候回来ParcelFileDescriptor已经关闭，或者远程进程崩溃或出现了其他错误，你可以使用 open(File, int, android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener) ， createReliablePipe() ，或 createReliableSocketPair() 。

为了在Intents中使用，您需要实现getType(Uri)以返回此处使用相同URI返回的数据的适当MIME类型。 这将允许意图解决方案自动确定数据MIME类型，并选择适当的匹配目标作为其操作的一部分。

为了更好地与其他应用程序互操作，建议对于可以打开的任何URI，还支持至少包含由OpenableColumns指定的列的OpenableColumns 。 如果您需要提供其他元数据，则可能还需要支持其他常用列，例如DATE_ADDED中的MediaStore.MediaColumns 。

openFile

ParcelFileDescriptor openFile (Uri uri, 
                String mode)

重写这个来处理打开一个文件blob的请求。 默认实现总是抛出FileNotFoundException 。 该方法可以从多个线程中调用，如Processes and Threads中所述 。

这个方法返回一个ParcelFileDescriptor，它直接返回给调用者。 这样可以在不复制内容的情况下返回大量数据（如图像和文档）。

返回的ParcelFileDescriptor由调用者拥有，因此他们有责任在完成时关闭它。 也就是说，这个方法的实现应该为每个调用创建一个新的ParcelFileDescriptor。

如果以独有的“r”或“w”模式打开，返回的ParcelFileDescriptor可以是管道或套接字对，以启用数据流式传输。 以“rw”或“rwt”模式打开意味着磁盘上的文件支持查找。

如果您需要检测什么时候回来ParcelFileDescriptor已经关闭，或者远程进程崩溃或出现了其他错误，你可以使用 open(File, int, android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener) ， createReliablePipe() ，或 createReliableSocketPair() 。

为了在Intents中使用，您需要实现getType(Uri)以返回此处使用相同URI返回的数据的适当MIME类型。 这将允许意图解决方案自动确定数据MIME类型，并选择适当的匹配目标作为其操作的一部分。

为了更好地与其他应用程序互操作，建议对于可以打开的任何URI，还支持对其至少包含由OpenableColumns指定的列的OpenableColumns 。 如果您需要提供其他元数据，则可能还需要支持其他常用列，例如DATE_ADDED中的MediaStore.MediaColumns 。

openPipeHelper

ParcelFileDescriptor openPipeHelper (Uri uri, 
                String mimeType, 
                Bundle opts, 
                T args, 
                PipeDataWriter<T> func)

用于实现openTypedAssetFile(Uri, String, Bundle)辅助函数，用于创建数据管道和后台线程，允许您将生成的数据传输回客户端。 这个函数返回一个新的ParcelFileDescriptor，它应该返回给调用者（调用者负责关闭它）。

openTypedAssetFile

AssetFileDescriptor openTypedAssetFile (Uri uri, 
                String mimeTypeFilter, 
                Bundle opts)

由客户端调用以打开包含特定MIME类型数据的只读流。 这就像openAssetFile(Uri, String) ，除了文件只能是只读的，内容提供者可以执行数据转换来生成所需类型的数据。

默认实现将给定的mimeType与 getType(Uri)的结果进行 getType(Uri) ，如果它们匹配，则只需调用 openAssetFile(Uri, String) 。

有关此方法的使用和实施示例，请参见 ClipData 。

返回的AssetFileDescriptor可以是管道或套接字对，以启用数据流式传输。

为了更好地与其他应用程序互操作，建议对于可以打开的任何URI，还支持对其至少包含由OpenableColumns指定的列的OpenableColumns 。 如果您需要提供其他元数据（如DATE_ADDED中的MediaStore.MediaColumns ，则可能还需要支持其他常用列。

openTypedAssetFile

AssetFileDescriptor openTypedAssetFile (Uri uri, 
                String mimeTypeFilter, 
                Bundle opts, 
                CancellationSignal signal)

由客户端调用以打开包含特定MIME类型数据的只读流。 这与openAssetFile(Uri, String) ，只是文件只能是只读的，内容提供者可以执行数据转换以生成所需类型的数据。

默认实现将给定的mimeType与 getType(Uri)的结果进行 getType(Uri) ，如果它们匹配，则简单地调用 openAssetFile(Uri, String) 。

有关此方法的使用和实施示例，请参见 ClipData 。

返回的AssetFileDescriptor可以是管道或套接字对，以启用数据流式传输。

为了更好地与其他应用程序互操作，建议对于可以打开的任何URI，还支持对其至少包含由OpenableColumns指定的列的OpenableColumns 。 如果您需要提供其他元数据，则可能还需要支持其他常用列，例如DATE_ADDED中的MediaStore.MediaColumns 。

query

Cursor query (Uri uri, 
                String[] projection, 
                String selection, 
                String[] selectionArgs, 
                String sortOrder, 
                CancellationSignal cancellationSignal)

实现这个来处理来自客户端的查询请求，并支持取消。 此方法可以从多个线程调用，如Processes and Threads中所述 。

客户呼叫示例：

// Request a specific record.
 Cursor managedCursor = managedQuery(
                ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
                projection,    // Which columns to return.
                null,          // WHERE clause.
                null,          // WHERE clause value substitution
                People.NAME + " ASC");   // Sort order.

// SQLiteQueryBuilder is a helper class that creates the
        // proper SQL syntax for us.
        SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();

        // Set the table we're querying.
        qBuilder.setTables(DATABASE_TABLE_NAME);

        // If the query ends in a specific record number, we're
        // being asked for a specific record, so set the
        // WHERE clause in our query.
        if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
            qBuilder.appendWhere("_id=" + uri.getPathLeafId());
        }

        // Make the query.
        Cursor c = qBuilder.query(mDb,
                projection,
                selection,
                selectionArgs,
                groupBy,
                having,
                sortOrder);
        c.setNotificationUri(getContext().getContentResolver(), uri);
        return c;

如果您实现此方法，则还必须实现不取消取消信号的版本 query(Uri, String[], String, String[], String) ，以确保在旧版Android Framework的正确操作中，取消信号过载不可用。

query

Cursor query (Uri uri, 
                String[] projection, 
                String selection, 
                String[] selectionArgs, 
                String sortOrder)

实现这个来处理来自客户端的查询请求。 该方法可以从多个线程调用，如Processes and Threads中所述 。

客户呼叫示例：

// Request a specific record.
 Cursor managedCursor = managedQuery(
                ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
                projection,    // Which columns to return.
                null,          // WHERE clause.
                null,          // WHERE clause value substitution
                People.NAME + " ASC");   // Sort order.

// SQLiteQueryBuilder is a helper class that creates the
        // proper SQL syntax for us.
        SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();

        // Set the table we're querying.
        qBuilder.setTables(DATABASE_TABLE_NAME);

        // If the query ends in a specific record number, we're
        // being asked for a specific record, so set the
        // WHERE clause in our query.
        if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
            qBuilder.appendWhere("_id=" + uri.getPathLeafId());
        }

        // Make the query.
        Cursor c = qBuilder.query(mDb,
                projection,
                selection,
                selectionArgs,
                groupBy,
                having,
                sortOrder);
        c.setNotificationUri(getContext().getContentResolver(), uri);
        return c;

shutdown

void shutdown ()

实现这个关闭ContentProvider实例。 然后你可以在单元测试中调用这个方法。

Android通常会自动处理ContentProvider的启动和关闭。 您不需要启动或关闭ContentProvider。 但是，当您在ContentProvider上调用测试方法时，即使后续测试实例化另一个ContentProvider，ContentProvider实例也会启动并在测试完成后继续运行。 由于这两个实例通常针对相同的基础数据源（例如，一个sqlite数据库）运行，所以会发生冲突。

实现shutDown（）通过提供终止ContentProvider的方法来避免这种冲突。 此方法还可以防止ContentProvider的多个实例存在内存泄漏，并且可以通过在完成下一个测试之前完全清理测试夹具来确保单元测试隔离。

uncanonicalize

Uri uncanonicalize (Uri url)

从以前由canonicalize(Uri)返回的规范化URI中删除规范化。 例如，如果你的实现是添加一个查询参数来规范一个URI，那么这个方法可以简单地将这个URI上的任何查询参数传递出去。 默认实现总是返回传入的相同url 。

update

int update (Uri uri, 
                ContentValues values, 
                String selection, 
                String[] selectionArgs)

实现这个来处理更新一行或多行的请求。 实现应该更新与选择相匹配的所有行，以根据提供的值映射设置列。 为了礼貌，更新后请致电notifyChange() 。 该方法可以从多个线程中调用，如Processes and Threads中所述 。

isTemporary

boolean isTemporary ()

如果此实例是临时内容提供者，则返回true。

openFileHelper

ParcelFileDescriptor openFileHelper (Uri uri, 
                String mode)

方便希望实现 openFile(Uri, String)的子类，方法是在给定的URI处查找名为“ openFile(Uri, String) ”的列。

setPathPermissions

void setPathPermissions (PathPermission[] permissions)

更改在内容提供者中读取和/或写入数据所需的基于路径的权限。 这通常是在首次创建提供程序时从其清单信息中为您设置的。

setReadPermission

void setReadPermission (String permission)

更改从内容提供者读取数据所需的权限。 这通常是在首次创建提供程序时从其清单信息中为您设置的。

setWritePermission

void setWritePermission (String permission)

更改在内容提供者中读取和写入数据所需的权限。 这通常是在首次创建提供程序时从其清单信息中为您设置的。