FileProvider

public class FileProvider
extends ContentProvider

FileProvider是一个特殊的子类 ContentProvider ，通过建立一个便于与应用程序相关的文件安全共享 content:// Uri的文件，而不是一个 file:/// Uri 。

内容URI允许您使用临时访问权限授予读取和写入访问权限。 当您创建包含内容URI的Intent ，为了将内容URI发送到客户端应用程序，您还可以调用Intent.setFlags()来添加权限。 只要接收Activity的堆栈处于活动状态，客户端应用就可以使用这些权限。 对于Intent转到Service ，只要Service正在运行，权限就可用。

相比之下，要控制对file:/// Uri访问，您必须修改底层文件的文件系统权限。 您提供的权限可用于任何应用程序，并在您更改它们之前保持有效。 这种访问级别基本上是不安全的。

由内容URI提供的文件访问安全级别的提高使得FileProvider成为Android安全基础设施的关键部分。

FileProvider的这个概述包括以下主题：

1. Defining a FileProvider
2. Specifying Available Files
3. Retrieving the Content URI for a File
4. Granting Temporary Permissions to a URI
5. Serving a Content URI to Another App

Defining a FileProvider

由于FileProvider的默认功能包括文件的内容URI生成，因此您无需在代码中定义子类。 相反，您可以通过在您的应用程序中完全使用XML来指定FileProvider。 要指定FileProvider组件本身，请将<provider>元素添加到您的应用清单。 将android:name属性设置为android.support.v4.content.FileProvider 。 根据您控制的域将android:authorities属性设置为URI权限; 例如，如果您控制域mydomain.com ，则应使用权限com.mydomain.fileprovider 。 将android:exported属性设置为false ; FileProvider不需要公开。 将android:grantUriPermissions属性设置为true ，以允许您授予对文件的临时访问权限。 例如：

<manifest>
    ...
    <application>
        ...
        <provider
            android:name="android.support.v4.content.FileProvider"
            android:authorities="com.mydomain.fileprovider"
            android:exported="false"
            android:grantUriPermissions="true">
            ...
        </provider>
        ...
    </application>
</manifest>

如果要覆盖FileProvider方法的任何默认行为，请扩展FileProvider类并在 <provider>元素的 android:name属性中使用完全限定的类名称。

Specifying Available Files

<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <files-path name="my_images" path="images/"/>
    ...
</paths>

<paths>元素必须包含一个或多个以下子元素：

<files-path name="name" path="path" />

Represents files in the files/ subdirectory of your app's internal storage area. This subdirectory is the same as the value returned by Context.getFilesDir().

<external-path name="name" path="path" />

Represents the root of the external storage. The root path of this subdirectory is the same that Environment.getExternalStorageDirectory() returns.

<cache-path name="name" path="path" />

Represents files in the cache subdirectory of your app's internal storage area. The root path of this subdirectory is the same as the value returned by getCacheDir().

这些子元素都使用相同的属性：

name="name"

A URI path segment. To enforce security, this value hides the name of the subdirectory you're sharing. The subdirectory name for this value is contained in the path attribute.

path="path"

The subdirectory you're sharing. While the name attribute is a URI path segment, the path value is an actual subdirectory name. Notice that the value refers to a subdirectory, not an individual file or files. You can't share a single file by its file name, nor can you specify a subset of files using wildcards.

您必须为每个包含您需要内容URI的文件的目录指定一个子元素<paths> 。 例如，这些XML元素指定两个目录：

<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <files-path name="my_images" path="images/"/>
    <files-path name="my_docs" path="docs/"/>
</paths>

将<paths>元素及其子元素放入项目中的XML文件中。 例如，您可以将它们添加到名为res/xml/file_paths.xml的新文件。 要将此文件链接到FileProvider，请添加一个<meta-data>元素作为定义FileProvider的<provider>元素的子元素。 将<meta-data>元素的“android：name”属性设置为android.support.FILE_PROVIDER_PATHS 。 将元素的“android：resource”属性设置为@xml/file_paths （请注意，您不指定.xml扩展名）。 例如：

<provider
    android:name="android.support.v4.content.FileProvider"
    android:authorities="com.mydomain.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>

Generating the Content URI for a File

要使用内容URI与另一个应用程序共享文件，您的应用程序必须生成内容URI。 要生成内容URI，请为该文件创建一个新的File ，然后将该File传递给getUriForFile() 。 您可以发送URI返回由内容getUriForFile()在另一个应用程序Intent 。 接收内容URI的客户端应用程序可以通过调用ContentResolver.openFileDescriptor来打开文件并访问其内容，以获取ParcelFileDescriptor 。

例如，假设您的应用程序使用具有权限com.mydomain.fileprovider的FileProvider将文件提供给其他应用程序。 要在内部存储的images/子目录中获取文件default_image.jpg的内容URI，请添加以下代码：

File imagePath = new File(Context.getFilesDir(), "images");
File newFile = new File(imagePath, "default_image.jpg");
Uri contentUri = getUriForFile(getContext(), "com.mydomain.fileprovider", newFile);

Granting Temporary Permissions to a URI

• Call the method Context.grantUriPermission(package, Uri, mode_flags) for the content:// Uri, using the desired mode flags. This grants temporary access permission for the content URI to the specified package, according to the value of the the mode_flags parameter, which you can set to FLAG_GRANT_READ_URI_PERMISSION, FLAG_GRANT_WRITE_URI_PERMISSION or both. The permission remains in effect until you revoke it by calling revokeUriPermission() or until the device reboots.
• Put the content URI in an Intent by calling setData().
• Next, call the method Intent.setFlags() with either FLAG_GRANT_READ_URI_PERMISSION or FLAG_GRANT_WRITE_URI_PERMISSION or both.
• Finally, send the Intent to another app. Most often, you do this by calling setResult().

  在Intent授予的权限在接收Activity的堆栈处于活动状态时保持有效。 堆栈完成后，权限会自动删除。 授予客户端应用程序中一个Activity权限会自动扩展到该应用程序的其他组件。

Serving a Content URI to Another App

有多种方式可以将文件的内容URI提供给客户端应用程序。 一种常见的方式是客户端应用程序通过调用startActivityResult()启动您的应用程序，该应用程序向您的应用程序发送Intent以在您的应用程序中启动Activity 。 作为响应，您的应用程序可以立即将内容URI返回给客户端应用程序，或者呈现允许用户选择文件的用户界面。 在后一种情况下，一旦用户选择文件，您的应用可以返回其内容URI。 在这两种情况下，你的应用程序返回的内容URI Intent通过发送setResult() 。

您还可以将内容URI放入ClipData对象中，然后将该对象添加到发送给客户端应用程序的Intent 。 为此，请致电Intent.setClipData() 。 当您使用此方法时，可以将多个ClipData对象添加到Intent ，每个对象都有其自己的内容URI。 当您拨打Intent.setFlags()上的Intent来设置临时访问权限时，相同的权限将应用于所有内容URI。

注意： Intent.setClipData()方法仅在平台版本16（Android 4.1）及更高版本中可用。 如果您想保持与以前版本的兼容性，您应该一次发送一个内容URI在Intent 。 将操作设置为ACTION_SEND并通过调用setData()将URI置于数据中。

More Information

要了解有关FileProvider的更多信息，请参阅Android培训课程 Sharing Files Securely with URIs 。

Summary

Inherited constants

From interface android.content.ComponentCallbacks2 int TRIM_MEMORY_BACKGROUND 级别为 onTrimMemory(int) ：进程已经进入LRU列表。 int TRIM_MEMORY_COMPLETE 级别为 onTrimMemory(int) ：进程已接近后台LRU列表的末尾，并且如果更多的内存很快没有找到，它将被终止。 int TRIM_MEMORY_MODERATE 级别为onTrimMemory(int) ：进程位于后台LRU列表的中间; 释放内存可以帮助系统保留列表中稍后运行的其他进程，以获得更好的整体性能。 int TRIM_MEMORY_RUNNING_CRITICAL 级别为 onTrimMemory(int) ：该进程不是一个 onTrimMemory(int)后台进程，但设备运行内存极低，并且将不能保持任何后台进程的运行。 int TRIM_MEMORY_RUNNING_LOW 级别为 onTrimMemory(int) ：该过程不是可消耗的后台进程，但设备内存不足。 int TRIM_MEMORY_RUNNING_MODERATE 级别为 onTrimMemory(int) ：该进程不是一个 onTrimMemory(int)后台进程，但该设备在内存上的运行状况适中。 int TRIM_MEMORY_UI_HIDDEN 级别为 onTrimMemory(int) ：该过程已显示用户界面，并且不再这样做。

Inherited methods
From class android.content.ContentProvider ContentProviderResult[] applyBatch(ArrayList<ContentProviderOperation> operations) 重写此操作以处理执行一批操作的请求，或者默认实现将迭代操作并在每个操作上调用 apply(ContentProvider, ContentProviderResult[], int) 。 void attachInfo(Context context, ProviderInfo info) 在被实例化之后，这被称为告诉内容提供者自己。 int bulkInsert(Uri uri, ContentValues[] values) 重写此操作以处理插入一组新行的请求，或者默认实现将迭代值并在每个值上调用 insert(Uri, ContentValues) 。 Bundle call(String method, String arg, Bundle extras) 调用提供者定义的方法。 Uri canonicalize(Uri url) 实现这一点，以支持引用您的内容提供者的URI的标准化。 abstract int delete(Uri uri, String selection, String[] selectionArgs) 实现这个来处理删除一行或多行的请求。 void dump(FileDescriptor fd, PrintWriter writer, String[] args) 将提供者的状态打印到给定的流中。 final String getCallingPackage() 返回在当前线程上发起正在处理的请求的调用方的包名称。 final Context getContext() 检索此提供程序运行的上下文。 final PathPermission[] getPathPermissions() 返回对此内容提供者进行读取和/或写入访问所需的基于路径的权限。 final String getReadPermission() 将只读访问所需权限的名称返回给此内容提供者。 String[] getStreamTypes(Uri uri, String mimeTypeFilter) 由客户端调用以确定此内容提供程序支持的给定URI的数据流类型。 abstract String getType(Uri uri) 实现这个来处理给定URI处的数据的MIME类型请求。 final String getWritePermission() 将读取/写入权限所需的权限的名称返回给此内容提供者。 abstract Uri insert(Uri uri, ContentValues values) 实现这个来处理插入新行的请求。 boolean isTemporary() 如果此实例是临时内容提供者，则返回true。 void onConfigurationChanged(Configuration newConfig) 设备配置在组件运行时发生更改时由系统调用。 此方法始终在应用程序主线程上调用，并且不得执行冗长的操作。 abstract boolean onCreate() 在启动时实现这个以初始化您的内容提供者。 void onLowMemory() 这在整个系统内存不足时调用，并且主动运行的进程应该修剪内存使用情况。 此方法始终在应用程序主线程上调用，并且不得执行冗长的操作。 void onTrimMemory(int level) 当操作系统确定进程从其进程中删除不需要的内存是一个好时机时调用。 AssetFileDescriptor openAssetFile(Uri uri, String mode, CancellationSignal signal) 这类似于 openFile(Uri, String) ，但可以由需要能够返回文件的子部分的提供者实现，这些文件通常是.apk中的资源。 AssetFileDescriptor openAssetFile(Uri uri, String mode) 这类似于 openFile(Uri, String) ，但可以由需要能够返回文件子部分的提供者实现，这些文件通常是.apk内的资源。 ParcelFileDescriptor openFile(Uri uri, String mode, CancellationSignal signal) 重写这个来处理打开一个文件blob的请求。 ParcelFileDescriptor openFile(Uri uri, String mode) 重写这个来处理打开一个文件blob的请求。 final ParcelFileDescriptor openFileHelper(Uri uri, String mode) 方便希望实现 openFile(Uri, String)的子类，方法是在给定的URI处查找名为“ openFile(Uri, String) ”的列。 <T> ParcelFileDescriptor openPipeHelper(Uri uri, String mimeType, Bundle opts, T args, PipeDataWriter<T> func) 用于实现 openTypedAssetFile(Uri, String, Bundle)帮助程序函数，用于创建数据管道和后台线程，以便将生成的数据传输回客户端。 AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts) 由客户端调用以打开包含特定MIME类型数据的只读流。 AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal) 由客户端调用以打开包含特定MIME类型数据的只读流。 Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal) 实现这个来处理来自客户端的查询请求，并支持取消。 abstract Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) 实现这个来处理来自客户端的查询请求。 final void setPathPermissions(PathPermission[] permissions) 更改在内容提供者中读取和/或写入数据所需的基于路径的权限。 final void setReadPermission(String permission) 更改从内容提供者读取数据所需的权限。 final void setWritePermission(String permission) 更改在内容提供者中读取和写入数据所需的权限。 void shutdown() 实现这个关闭ContentProvider实例。 Uri uncanonicalize(Uri url) 从以前由 canonicalize(Uri)返回的规范化URI中删除规范化。 abstract int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) 实现这个来处理更新一行或多行的请求。
From class java.lang.Object Object clone() 创建并返回此对象的副本。 boolean equals(Object obj) 指示其他某个对象是否“等于”这一个。 void finalize() 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 final Class<?> getClass() 返回此 Object的运行时类。 int hashCode() 返回对象的哈希码值。 final void notify() 唤醒正在等待该对象监视器的单个线程。 final void notifyAll() 唤醒在该对象监视器上等待的所有线程。 String toString() 返回对象的字符串表示形式。 final void wait(long millis, int nanos) 导致当前线程等待，直到另一个线程为该对象调用 notify()方法或 notifyAll()方法，或者某个其他线程中断当前线程，或者经过一定的实时时间。 final void wait(long millis) 导致当前线程等待，直到另一个线程为此对象调用 notify()方法或 notifyAll()方法，或者经过指定的时间量。 final void wait() 导致当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法。
From interface android.content.ComponentCallbacks2 abstract void onTrimMemory(int level) 当操作系统确定进程从其进程中删除不需要的内存是一个好时机时调用。
From interface android.content.ComponentCallbacks abstract void onConfigurationChanged(Configuration newConfig) 设备配置在组件运行时发生更改时由系统调用。 abstract void onLowMemory() 这在整个系统内存不足时调用，并且主动运行的进程应该修剪内存使用情况。

Public constructors

FileProvider ()

Public methods

void attachInfo (Context context, 
                ProviderInfo info)

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

String getType (Uri uri)

Uri getUriForFile (Context context, 
                String authority, 
                File file)

Uri insert (Uri uri, 
                ContentValues values)

boolean onCreate ()

ParcelFileDescriptor openFile (Uri uri, 
                String mode)

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

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