1page.title=Setting Up File Sharing
2trainingnavtop=true
3@jd:body
4
5
6<div id="tb-wrapper">
7<div id="tb">
8
9<!-- table of contents -->
10<h2>This lesson teaches you to</h2>
11<ol>
12  <li><a href="#DefineProvider">Specify the FileProvider</a></li>
13  <li><a href="#DefineMetaData">Specify Sharable Directories</a></li>
14</ol>
15
16<h2>You should also read</h2>
17<ul>
18  <li><a href="{@docRoot}guide/topics/data/data-storage.html">Storage Options</a></li>
19  <li><a href="{@docRoot}training/basics/data-storage/files.html">Saving Files</a>
20</ul>
21
22</div>
23</div>
24
25<p>
26    To securely offer a file from your app to another app, you need to configure your app to offer
27    a secure handle to the file, in the form of a content URI. The Android
28    {@link android.support.v4.content.FileProvider} component generates content URIs for
29    files, based on specifications you provide in XML. This lesson shows you how to add the default
30    implementation of {@link android.support.v4.content.FileProvider} to your app, and how to
31    specify the files you want to offer to other apps.
32</p>
33
34<p class="note">
35  <strong>Note:</strong> The {@link android.support.v4.content.FileProvider} class is part of the
36  <a href="{@docRoot}tools/support-library/features.html#v4">v4 Support Library</a>. For information
37  about including this library in your application, see
38  <a href="{@docRoot}tools/support-library/setup.html">Support Library Setup</a>.
39</p>
40
41<h2 id="DefineProvider">Specify the FileProvider</h2>
42<p>
43    Defining a {@link android.support.v4.content.FileProvider} for your app requires an entry in
44    your manifest. This entry specifies the authority to use in generating content URIs, as well as
45    the name of an XML file that specifies the directories your app can share.
46</p>
47<p>
48    The following snippet shows you how to add to your manifest the
49    <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"
50    >&lt;provider&gt;</a></code> element that specifies the
51    {@link android.support.v4.content.FileProvider} class, the authority, and the
52    XML file name:
53</p>
54<pre>
55&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
56    package="com.example.myapp"&gt;
57    &lt;application
58        ...&gt;
59        &lt;provider
60            android:name="android.support.v4.content.FileProvider"
61            android:authorities="com.example.myapp.fileprovider"
62            android:grantUriPermissions="true"
63            android:exported="false"&gt;
64            &lt;meta-data
65                android:name="android.support.FILE_PROVIDER_PATHS"
66                android:resource="&#64;xml/filepaths" /&gt;
67        &lt;/provider&gt;
68        ...
69    &lt;/application&gt;
70&lt;/manifest&gt;</pre>
71<p>
72    In this example, the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#auth"
73    >android:authorities</a></code> attribute specifies the URI authority
74    that you want to use for content URIs generated by the
75    {@link android.support.v4.content.FileProvider}.
76    In the example, the authority is <code>com.example.myapp.fileprovider</code>. For your own
77    app, specify an authority consisting of the app's
78    <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package"
79    >android:package</a></code> value with the string "fileprovider" appended to it. To learn more
80    about the authority value, see the topic
81    <a href="{@docRoot}guide/topics/providers/content-provider-basics.html#ContentURIs"
82    >Content URIs</a> and the documentation for the
83    <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#auth"
84    >android:authorities</a></code> attribute.
85</p>
86<p>
87    The <code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"
88    >&lt;meta-data&gt;</a></code> child element of the
89    <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"
90    >&lt;provider&gt;</a></code> points to an XML file that specifies the directories you want to
91    share. The <code>android:resource</code> attribute is the path and name of the file, without
92    the <code>.xml</code> extension.The contents of this file are described in the next section.
93</p>
94<h2 id="DefineMetaData">Specify Sharable Directories</h2>
95<p>
96    Once you have added the {@link android.support.v4.content.FileProvider} to your app manifest,
97    you need to specify the directories that contain the files you want to share. To specify the
98    directories, start by creating the file <code>filepaths.xml</code> in the <code>res/xml/</code>
99    subdirectory of your project. In this file, specify the directories by adding an XML element for
100    each directory. The following snippet shows you an example of the contents of
101    <code>res/xml/filepaths.xml</code>. The snippet also demonstrates how to share a subdirectory
102    of the <code>files/</code> directory in your internal storage area:
103</p>
104<pre>
105&lt;paths&gt;
106    &lt;files-path path="images/" name="myimages" /&gt;
107&lt;/paths&gt;</pre>
108<p>
109    In this example, the <code>&lt;files-path&gt;</code> tag shares directories within the
110    <code>files/</code> directory of your app's internal storage. The <code>path</code> attribute
111    shares the <code>images/</code> subdirectory of <code>files/</code>.  The <code>name</code>
112    attribute tells the {@link android.support.v4.content.FileProvider} to add the path segment
113    <code>myimages</code> to content URIs for files in the <code>files/images/</code> subdirectory.
114</p>
115<p>
116    The <code>&lt;paths&gt;</code> element can have multiple children, each specifying a different
117    directory to share. In addition to the <code>&lt;files-path&gt;</code> element, you can
118    use the <code>&lt;external-path&gt;</code> element to share directories in external storage, and
119    the <code>&lt;cache-path&gt;</code> element to share directories in your internal cache
120    directory. To learn more about the child elements that specify shared directories, see the
121    {@link android.support.v4.content.FileProvider} reference documentation.
122</p>
123<p class="note">
124    <strong>Note:</strong> The XML file is the only way you can specify the directories you want to
125    share; you can't programmatically add a directory.
126</p>
127<p>
128    You now have a complete specification of a {@link android.support.v4.content.FileProvider}
129    that generates content URIs for files in the <code>files/</code> directory of your app's
130    internal storage or for files in subdirectories of <code>files/</code>. When your app generates
131    a content URI for a file, it contains the authority specified in the
132    <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"
133    >&lt;provider&gt;</a></code> element (<code>com.example.myapp.fileprovider</code>),
134    the path <code>myimages/</code>, and the name of the file.
135</p>
136<p>
137    For example, if you define a {@link android.support.v4.content.FileProvider} according to the
138    snippets in this lesson, and you request a content URI for the file
139    <code>default_image.jpg</code>, {@link android.support.v4.content.FileProvider} returns the
140    following URI:
141</p>
142<pre>
143content://com.example.myapp.fileprovider/myimages/default_image.jpg</pre>
144
145