FileProvider

Class Overview

FileProvider is a special subclass of ContentProvider that facilitates secure sharing of files associated with an app by creating a content:// Uri for a file instead of a file:/// Uri.

A content URI allows you to grant read and write access using temporary access permissions. When you create an Intent containing a content URI, in order to send the content URI to a client app, you can also call Intent.setFlags() to add permissions. These permissions are available to the client app for as long as the stack for a receiving Activity is active. For an Intent going to a Service, the permissions are available as long as the Service is running.

In comparison, to control access to a file:/// Uri you have to modify the file system permissions of the underlying file. The permissions you provide become available to any app, and remain in effect until you change them. This level of access is fundamentally insecure.

The increased level of file access security offered by a content URI makes FileProvider a key part of Android's security infrastructure.

This overview of FileProvider includes the following topics:

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

Since the default functionality of FileProvider includes content URI generation for files, you don't need to define a subclass in code. Instead, you can include a FileProvider in your app by specifying it entirely in XML. To specify the FileProvider component itself, add a <provider> element to your app manifest. Set the android:name attribute to android.support.v4.content.FileProvider. Set the android:authorities attribute to a URI authority based on a domain you control; for example, if you control the domain mydomain.com you should use the authority com.mydomain.fileprovider. Set the android:exported attribute to false; the FileProvider does not need to be public. Set the android:grantUriPermissions attribute to true, to allow you to grant temporary access to files. For example:

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

If you want to override any of the default behavior of FileProvider methods, extend the FileProvider class and use the fully-qualified class name in the android:name attribute of the <provider> element.

Specifying Available Files

A FileProvider can only generate a content URI for files in directories that you specify beforehand. To specify a directory, specify the its storage area and path in XML, using child elements of the <paths> element. For example, the following paths element tells FileProvider that you intend to request content URIs for the images/ subdirectory of your private file area.

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

The <paths> element must contain one or more of the following child elements:

<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 files in the root of your app's external storage area. The path Context.getExternalFilesDir() returns the files/ subdirectory of this this root.

<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().

These child elements all use the same attributes:

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.

You must specify a child element of <paths> for each directory that contains files for which you want content URIs. For example, these XML elements specify two directories:

<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>

Put the <paths> element and its children in an XML file in your project. For example, you can add them to a new file called res/xml/file_paths.xml. To link this file to the FileProvider, add a <meta-data> element as a child of the <provider> element that defines the FileProvider. Set the <meta-data> element's "android:name" attribute to android.support.FILE_PROVIDER_PATHS. Set the element's "android:resource" attribute to @xml/file_paths (notice that you don't specify the .xml extension). For example:

<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

To share a file with another app using a content URI, your app has to generate the content URI. To generate the content URI, create a new File for the file, then pass the File to getUriForFile(). You can send the content URI returned by getUriForFile() to another app in an Intent. The client app that receives the content URI can open the file and access its contents by calling ContentResolver.openFileDescriptor to get a ParcelFileDescriptor.

For example, suppose your app is offering files to other apps with a FileProvider that has the authority com.mydomain.fileprovider. To get a content URI for the file default_image.jpg in the images/ subdirectory of your internal storage add the following code:

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

As a result of the previous snippet, getUriForFile() returns the content URI content://com.mydomain.fileprovider/my_images/default_image.jpg.

Granting Temporary Permissions to a URI

To grant an access permission to a content URI returned from getUriForFile(), do one of the following:

• 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().

  Permissions granted in an Intent remain in effect while the stack of the receiving Activity is active. When the stack finishes, the permissions are automatically removed. Permissions granted to one Activity in a client app are automatically extended to other components of that app.

Serving a Content URI to Another App

There are a variety of ways to serve the content URI for a file to a client app. One common way is for the client app to start your app by calling startActivityResult(), which sends an Intent to your app to start an Activity in your app. In response, your app can immediately return a content URI to the client app or present a user interface that allows the user to pick a file. In the latter case, once the user picks the file your app can return its content URI. In both cases, your app returns the content URI in an Intent sent via setResult().

You can also put the content URI in a ClipData object and then add the object to an Intent you send to a client app. To do this, call Intent.setClipData(). When you use this approach, you can add multiple ClipData objects to the Intent, each with its own content URI. When you call Intent.setFlags() on the Intent to set temporary access permissions, the same permissions are applied to all of the content URIs.

Note: The Intent.setClipData() method is only available in platform version 16 (Android 4.1) and later. If you want to maintain compatibility with previous versions, you should send one content URI at a time in the Intent. Set the action to ACTION_SEND and put the URI in data by calling setData().

More Information

To learn more about FileProvider, see the Android training class Sharing Files Securely with URIs.

Summary

[Expand] Inherited Constants

From interface android.content.ComponentCallbacks2 int TRIM_MEMORY_BACKGROUND Level for onTrimMemory(int): the process has gone on to the LRU list. int TRIM_MEMORY_COMPLETE Level for onTrimMemory(int): the process is nearing the end of the background LRU list, and if more memory isn't found soon it will be killed. int TRIM_MEMORY_MODERATE Level for onTrimMemory(int): the process is around the middle of the background LRU list; freeing memory can help the system keep other processes running later in the list for better overall performance. int TRIM_MEMORY_RUNNING_CRITICAL Level for onTrimMemory(int): the process is not an expendable background process, but the device is running extremely low on memory and is about to not be able to keep any background processes running. int TRIM_MEMORY_RUNNING_LOW Level for onTrimMemory(int): the process is not an expendable background process, but the device is running low on memory. int TRIM_MEMORY_RUNNING_MODERATE Level for onTrimMemory(int): the process is not an expendable background process, but the device is running moderately low on memory. int TRIM_MEMORY_UI_HIDDEN Level for onTrimMemory(int): the process had been showing a user interface, and is no longer doing so.

Public Constructors
	FileProvider()

Public Methods
void	attachInfo(Context context, ProviderInfo info) After the FileProvider is instantiated, this method is called to provide the system with information about the provider.
int	delete(Uri uri, String selection, String[] selectionArgs) Deletes the file associated with the specified content URI, as returned by getUriForFile().
String	getType(Uri uri) Returns the MIME type of a content URI returned by getUriForFile().
static Uri	getUriForFile(Context context, String authority, File file) Return a content URI for a given File.
Uri	insert(Uri uri, ContentValues values) By default, this method throws an UnsupportedOperationException.
boolean	onCreate() The default FileProvider implementation does not need to be initialized.
ParcelFileDescriptor	openFile(Uri uri, String mode) By default, FileProvider automatically returns the ParcelFileDescriptor for a file associated with a content:// Uri.
Cursor	query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) Use a content URI returned by getUriForFile() to get information about a file managed by the FileProvider.
int	update(Uri uri, ContentValues values, String selection, String[] selectionArgs) By default, this method throws an UnsupportedOperationException.

[Expand] Inherited Methods
From class android.content.ContentProvider ContentProviderResult[] applyBatch(ArrayList<ContentProviderOperation> operations) Override this to handle requests to perform a batch of operations, or the default implementation will iterate over the operations and call apply(ContentProvider, ContentProviderResult[], int) on each of them. void attachInfo(Context context, ProviderInfo info) After being instantiated, this is called to tell the content provider about itself. int bulkInsert(Uri uri, ContentValues[] values) Override this to handle requests to insert a set of new rows, or the default implementation will iterate over the values and call insert(Uri, ContentValues) on each of them. Bundle call(String method, String arg, Bundle extras) Call a provider-defined method. Uri canonicalize(Uri url) Implement this to support canonicalization of URIs that refer to your content provider. abstract int delete(Uri uri, String selection, String[] selectionArgs) Implement this to handle requests to delete one or more rows. void dump(FileDescriptor fd, PrintWriter writer, String[] args) Print the Provider's state into the given stream. final String getCallingPackage() Return the package name of the caller that initiated the request being processed on the current thread. final Context getContext() Retrieves the Context this provider is running in. final PathPermission[] getPathPermissions() Return the path-based permissions required for read and/or write access to this content provider. final String getReadPermission() Return the name of the permission required for read-only access to this content provider. String[] getStreamTypes(Uri uri, String mimeTypeFilter) Called by a client to determine the types of data streams that this content provider supports for the given URI. abstract String getType(Uri uri) Implement this to handle requests for the MIME type of the data at the given URI. final String getWritePermission() Return the name of the permission required for read/write access to this content provider. abstract Uri insert(Uri uri, ContentValues values) Implement this to handle requests to insert a new row. boolean isTemporary() Returns true if this instance is a temporary content provider. void onConfigurationChanged(Configuration newConfig) Called by the system when the device configuration changes while your component is running. This method is always called on the application main thread, and must not perform lengthy operations. abstract boolean onCreate() Implement this to initialize your content provider on startup. void onLowMemory() This is called when the overall system is running low on memory, and actively running processes should trim their memory usage. This method is always called on the application main thread, and must not perform lengthy operations. void onTrimMemory(int level) Called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process. AssetFileDescriptor openAssetFile(Uri uri, String mode, CancellationSignal signal) This is like openFile(Uri, String), but can be implemented by providers that need to be able to return sub-sections of files, often assets inside of their .apk. AssetFileDescriptor openAssetFile(Uri uri, String mode) This is like openFile(Uri, String), but can be implemented by providers that need to be able to return sub-sections of files, often assets inside of their .apk. ParcelFileDescriptor openFile(Uri uri, String mode) Override this to handle requests to open a file blob. ParcelFileDescriptor openFile(Uri uri, String mode, CancellationSignal signal) Override this to handle requests to open a file blob. final ParcelFileDescriptor openFileHelper(Uri uri, String mode) Convenience for subclasses that wish to implement openFile(Uri, String) by looking up a column named "_data" at the given URI. <T> ParcelFileDescriptor openPipeHelper(Uri uri, String mimeType, Bundle opts, T args, PipeDataWriter<T> func) A helper function for implementing openTypedAssetFile(Uri, String, Bundle), for creating a data pipe and background thread allowing you to stream generated data back to the client. AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts) Called by a client to open a read-only stream containing data of a particular MIME type. AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal) Called by a client to open a read-only stream containing data of a particular MIME type. abstract Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) Implement this to handle query requests from clients. Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal) Implement this to handle query requests from clients with support for cancellation. final void setPathPermissions(PathPermission[] permissions) Change the path-based permission required to read and/or write data in the content provider. final void setReadPermission(String permission) Change the permission required to read data from the content provider. final void setWritePermission(String permission) Change the permission required to read and write data in the content provider. void shutdown() Implement this to shut down the ContentProvider instance. Uri uncanonicalize(Uri url) Remove canonicalization from canonical URIs previously returned by canonicalize(Uri). abstract int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) Implement this to handle requests to update one or more rows.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
From interface android.content.ComponentCallbacks abstract void onConfigurationChanged(Configuration newConfig) Called by the system when the device configuration changes while your component is running. abstract void onLowMemory() This is called when the overall system is running low on memory, and actively running processes should trim their memory usage.
From interface android.content.ComponentCallbacks2 abstract void onTrimMemory(int level) Called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process.