blob: 8c8fa0ff6cc1274e093a1eb3f0255886fd70e688 [file] [log] [blame]
page.title=Setting Up File Sharing
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<li><a href="#DefineProvider">Specify the FileProvider</a></li>
<li><a href="#DefineMetaData">Specify Sharable Directories</a></li>
<h2>You should also read</h2>
<li><a href="{@docRoot}guide/topics/data/data-storage.html">Storage Options</a></li>
<li><a href="{@docRoot}training/basics/data-storage/files.html">Saving Files</a>
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
{@link} component generates content URIs for
files, based on specifications you provide in XML. This lesson shows you how to add the default
implementation of {@link} to your app, and how to
specify the files you want to offer to other apps.
<p class="note">
<strong>Note:</strong> The {@link} class is part of the
<a href="{@docRoot}tools/support-library/features.html#v4">v4 Support Library</a>. For information
about including this library in your application, see
<a href="{@docRoot}tools/support-library/setup.html">Support Library Setup</a>.
<h2 id="DefineProvider">Specify the FileProvider</h2>
Defining a {@link} 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
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"
>&lt;provider&gt;</a></code> element that specifies the
{@link} class, the authority, and the
XML file name:
&lt;manifest xmlns:android=""
android:resource="&#64;xml/filepaths" /&gt;
In this example, the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#auth"
>android:authorities</a></code> attribute specifies the URI authority
that you want to use for content URIs generated by the
In the example, the authority is <code>com.example.myapp.fileprovider</code>. For your own
app, specify an authority consisting of the app's
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package"
>android:package</a></code> value with the string "fileprovider" appended to it. To learn more
about the authority value, see the topic
<a href="{@docRoot}guide/topics/providers/content-provider-basics.html#ContentURIs"
>Content URIs</a> and the documentation for the
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#auth"
>android:authorities</a></code> attribute.
The <code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"
>&lt;meta-data&gt;</a></code> child element of the
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"
>&lt;provider&gt;</a></code> points to an XML file that specifies the directories you want to
share. The <code>android:resource</code> attribute is the path and name of the file, without
the <code>.xml</code> extension.The contents of this file are described in the next section.
<h2 id="DefineMetaData">Specify Sharable Directories</h2>
Once you have added the {@link} 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 <code>filepaths.xml</code> in the <code>res/xml/</code>
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
<code>res/xml/filepaths.xml</code>. The snippet also demonstrates how to share a subdirectory
of the <code>files/</code> directory in your internal storage area:
&lt;files-path path="images/" name="myimages" /&gt;
In this example, the <code>&lt;files-path&gt;</code> tag shares directories within the
<code>files/</code> directory of your app's internal storage. The <code>path</code> attribute
shares the <code>images/</code> subdirectory of <code>files/</code>. The <code>name</code>
attribute tells the {@link} to add the path segment
<code>myimages</code> to content URIs for files in the <code>files/images/</code> subdirectory.
The <code>&lt;paths&gt;</code> element can have multiple children, each specifying a different
directory to share. In addition to the <code>&lt;files-path&gt;</code> element, you can
use the <code>&lt;external-path&gt;</code> element to share directories in external storage, and
the <code>&lt;cache-path&gt;</code> element to share directories in your internal cache
directory. To learn more about the child elements that specify shared directories, see the
{@link} reference documentation.
<p class="note">
<strong>Note:</strong> 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 {@link}
that generates content URIs for files in the <code>files/</code> directory of your app's
internal storage or for files in subdirectories of <code>files/</code>. When your app generates
a content URI for a file, it contains the authority specified in the
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"
>&lt;provider&gt;</a></code> element (<code>com.example.myapp.fileprovider</code>),
the path <code>myimages/</code>, and the name of the file.
For example, if you define a {@link} according to the
snippets in this lesson, and you request a content URI for the file
<code>default_image.jpg</code>, {@link} returns the
following URI: