Setting Up File Sharing

To securely offer a file from your app to another app, you need to configure your app to offer a secure handle to the file, in the form of a content URI. The Android FileProvider component generates content URIs for files, based on specifications you provide in XML. This lesson shows you how to add the default implementation of FileProvider to your app, and how to specify the files you want to offer to other apps.

Note: The FileProvider class is part of the v4 Support Library. For information about including this library in your application, see Support Library Setup.

Specify the FileProvider

Defining a FileProvider for your app requires an entry in your manifest. This entry specifies the authority to use in generating content URIs, as well as the name of an XML file that specifies the directories your app can share.

The following snippet shows you how to add to your manifest the <provider> element that specifies the FileProvider class, the authority, and the XML file name:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">
    <application
        ...>
        <provider
            android:name="android.support.v4.content.FileProvider"
            android:authorities="com.example.myapp.fileprovider"
            android:grantUriPermissions="true"
            android:exported="false">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/filepaths" />
        </provider>
        ...
    </application>
</manifest>

In this example, the android:authorities attribute specifies the URI authority that you want to use for content URIs generated by the FileProvider. In the example, the authority is com.example.myapp.fileprovider. For your own app, specify an authority consisting of the app's android:package value with the string "fileprovider" appended to it. To learn more about the authority value, see the topic Content URIs and the documentation for the android:authorities attribute.

The <meta-data> child element of the <provider> points to an XML file that specifies the directories you want to share. The android:resource attribute is the path and name of the file, without the .xml extension.The contents of this file are described in the next section.

Specify Sharable Directories

Once you have added the FileProvider to your app manifest, you need to specify the directories that contain the files you want to share. To specify the directories, start by creating the file filepaths.xml in the res/xml/ subdirectory of your project. In this file, specify the directories by adding an XML element for each directory. The following snippet shows you an example of the contents of res/xml/filepaths.xml. The snippet also demonstrates how to share a subdirectory of the files/ directory in your internal storage area:

<paths>
    <files-path path="images/" name="myimages" />
</paths>

In this example, the <files-path> tag shares directories within the files/ directory of your app's internal storage. The path attribute shares the images/ subdirectory of files/. The name attribute tells the FileProvider to add the path segment myimages to content URIs for files in the files/images/ subdirectory.

The <paths> element can have multiple children, each specifying a different directory to share. In addition to the <files-path> element, you can use the <external-path> element to share directories in external storage, and the <cache-path> element to share directories in your internal cache directory. To learn more about the child elements that specify shared directories, see the FileProvider reference documentation.

Note: The XML file is the only way you can specify the directories you want to share; you can't programmatically add a directory.

You now have a complete specification of a FileProvider that generates content URIs for files in the files/ directory of your app's internal storage or for files in subdirectories of files/. When your app generates a content URI for a file, it contains the authority specified in the <provider> element (com.example.myapp.fileprovider), the path myimages/, and the name of the file.

For example, if you define a FileProvider according to the snippets in this lesson, and you request a content URI for the file default_image.jpg, FileProvider returns the following URI:

content://com.example.myapp.fileprovider/myimages/default_image.jpg