content:// {@link Uri} for a file
+ * instead of a file:/// {@link Uri}.
+ * + * A content URI allows you to grant read and write access using + * temporary access permissions. When you create an {@link Intent} containing + * a content URI, in order to send the content URI + * to a client app, you can also call {@link Intent#setFlags(int) Intent.setFlags()} to add + * permissions. These permissions are available to the client app for as long as the stack for + * a receiving {@link Activity} is active. For an {@link Intent} going to a + * {@link Service}, the permissions are available as long as the + * {@link Service} is running. + *
+ * In comparison, to control access to a file:/// {@link 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: + *
+ *+ * Defining a FileProvider + *
+ * Extend FileProvider with a default constructor, and call super with an XML resource file that + * specifies the available files (see below for the structure of the XML file): + *
+ * public class MyFileProvider extends FileProvider {
+ * public MyFileProvider() {
+ * super(R.xml.file_paths)
+ * }
+ * }
+ *
+ * Add a
+ * <provider>
+ * element to your app manifest. Set the android:name attribute to the FileProvider you
+ * created. 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="com.sample.MyFileProvider" + * android:authorities="com.mydomain.fileprovider" + * android:exported="false" + * android:grantUriPermissions="true"> + * ... + * </provider> + * ... + * </application> + * </manifest>+ *
+ * It is possible to use FileProvider directly instead of extending it. However, this is not + * reliable and will causes crashes on some devices. + *
+ * Specifying Available Files + *
+ * A FileProvider can only generate a content URI for files in directories that you specify
+ * beforehand. To specify a directory, specify 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 {@link Context#getFilesDir()
+ * Context.getFilesDir()}.
+ * <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 {@link Context#getCacheDir() + * getCacheDir()}. + *
<external-path name="name" path="path" />+ * Represents files in the root of the external storage area. The root path of this subdirectory + * is the same as the value returned by + * {@link Environment#getExternalStorageDirectory() Environment.getExternalStorageDirectory()}. + *
<external-files-path name="name" path="path" + * />+ * Represents files in the root of your app's external storage area. The root path of this + * subdirectory is the same as the value returned by + * {@link Context#getExternalFilesDir(String) Context.getExternalFilesDir(null)}. + *
<external-cache-path name="name" path="path" + * />+ * Represents files in the root of your app's external cache area. The root path of this + * subdirectory is the same as the value returned by + * {@link Context#getExternalCacheDir() Context.getExternalCacheDir()}. + *
<external-media-path name="name" path="path" + * />+ * Represents files in the root of your app's external media area. The root path of this + * subdirectory is the same as the value returned by the first result of + * {@link Context#getExternalMediaDirs() Context.getExternalMediaDirs()}. + *
Note: this directory is only available on API 21+ devices.
+ *+ * 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, pass it to super() in the constructor for the
+ * FileProvider you defined above, 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="com.sample.MyFileProvider" + * 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 {@link File} for the file, then pass the {@link File} + * to {@link #getUriForFile(Context, String, File) getUriForFile()}. You can send the content URI + * returned by {@link #getUriForFile(Context, String, File) getUriForFile()} to another app in an + * {@link Intent}. The client app that receives the content URI can open the file + * and access its contents by calling + * {@link ContentResolver#openFileDescriptor(Uri, String) + * ContentResolver.openFileDescriptor} to get a {@link 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(), "my_images"); + * File newFile = new File(imagePath, "default_image.jpg"); + * Uri contentUri = getUriForFile(getContext(), "com.mydomain.fileprovider", newFile); + *+ * As a result of the previous snippet, + * {@link #getUriForFile(Context, String, File) 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 + * {@link #getUriForFile(Context, String, File) getUriForFile()}, you can either grant the + * permission to a specific package or include the permission in an intent, as shown in the + * following sections. + *
+ * Call the method
+ * {@link Context#grantUriPermission(String, Uri, int)
+ * Context.grantUriPermission(package, Uri, mode_flags)} for the content://
+ * {@link 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
+ * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION}, {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION}
+ * or both. The permission remains in effect until you revoke it by calling
+ * {@link Context#revokeUriPermission(Uri, int) revokeUriPermission()} or until the device
+ * reboots.
+ *
+ * To allow the user to choose which app receives the intent, and the permission to access the + * content, do the following: + *
+ *+ * Call the method {@link Intent#setFlags(int) Intent.setFlags()} with either + * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION} or + * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION} or both. + *
+ *
+ * To support devices that run a version between Android 4.1 (API level 16) and Android 5.1
+ * (API level 22) inclusive, create a {@link ClipData} object from the content
+ * URI, and set the access permissions on the ClipData object:
+ *
+ * shareContentIntent.setClipData(ClipData.newRawUri("", contentUri));
+ * shareContentIntent.addFlags(
+ * Intent.FLAG_GRANT_READ_URI_PERMISSION | Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
+ *
+ * + * Permissions granted in an {@link Intent} remain in effect while the stack of the receiving + * {@link Activity} is active. When the stack finishes, the permissions are + * automatically removed. Permissions granted to one {@link 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 + * {@link Activity#startActivityForResult(Intent, int, Bundle) startActivityResult()}, + * which sends an {@link Intent} to your app to start an {@link 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 + * {@link Intent} sent via {@link Activity#setResult(int, Intent) setResult()}. + *
+ *+ * You can also put the content URI in a {@link ClipData} object and then add the + * object to an {@link Intent} you send to a client app. To do this, call + * {@link Intent#setClipData(ClipData) Intent.setClipData()}. When you use this approach, you can + * add multiple {@link ClipData} objects to the {@link Intent}, each with its own + * content URI. When you call {@link Intent#setFlags(int) Intent.setFlags()} on the {@link Intent} + * to set temporary access permissions, the same permissions are applied to all of the content + * URIs. + *
+ *+ * Note: The {@link Intent#setClipData(ClipData) 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 + * {@link Intent}. Set the action to {@link Intent#ACTION_SEND} and put the URI in data by calling + * {@link Intent#setData setData()}. + *
+ * More Information + *+ * To learn more about FileProvider, see the Android training class + * Sharing Files Securely with + * URIs. + *
+ */ +public class FileProvider extends ContentProvider { + private static final String[] COLUMNS = { + OpenableColumns.DISPLAY_NAME, OpenableColumns.SIZE }; + + private static final String + META_DATA_FILE_PROVIDER_PATHS = "android.support.FILE_PROVIDER_PATHS"; + + private static final String TAG_ROOT_PATH = "root-path"; + private static final String TAG_FILES_PATH = "files-path"; + private static final String TAG_CACHE_PATH = "cache-path"; + private static final String TAG_EXTERNAL = "external-path"; + private static final String TAG_EXTERNAL_FILES = "external-files-path"; + private static final String TAG_EXTERNAL_CACHE = "external-cache-path"; + private static final String TAG_EXTERNAL_MEDIA = "external-media-path"; + + private static final String ATTR_NAME = "name"; + private static final String ATTR_PATH = "path"; + + private static final String DISPLAYNAME_FIELD = "displayName"; + + private static final File DEVICE_ROOT = new File("/"); + + @GuardedBy("sCache") + private static final HashMapcontent {@link Uri} for file paths defined in their <paths>
+ * meta-data element. See the Class Overview for more information.
+ *
+ * @param context A {@link Context} for the current component.
+ * @param authority The authority of a {@link FileProvider} defined in a
+ * {@code content {@link Uri}.
+ * @return A content URI for the file.
+ * @throws IllegalArgumentException When the given {@link File} is outside
+ * the paths supported by the provider.
+ */
+ public static Uri getUriForFile(@NonNull Context context, @NonNull String authority,
+ @NonNull File file) {
+ final PathStrategy strategy = getPathStrategy(context, authority, 0);
+ return strategy.getUriForFile(file);
+ }
+
+ /**
+ * Return a content URI for a given {@link File}. Specific temporary
+ * permissions for the content URI can be set with
+ * {@link Context#grantUriPermission(String, Uri, int)}, or added
+ * to an {@link Intent} by calling {@link Intent#setData(Uri) setData()} and then
+ * {@link Intent#setFlags(int) setFlags()}; in both cases, the applicable flags are
+ * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION} and
+ * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION}. A FileProvider can only return a
+ * content {@link Uri} for file paths defined in their <paths>
+ * meta-data element. See the Class Overview for more information.
+ *
+ * @param context A {@link Context} for the current component.
+ * @param authority The authority of a {@link FileProvider} defined in a
+ * {@code content {@link Uri}.
+ * @param displayName The filename to be displayed. This can be used if the original filename
+ * is undesirable.
+ * @return A content URI for the file.
+ * @throws IllegalArgumentException When the given {@link File} is outside
+ * the paths supported by the provider.
+ */
+ @SuppressLint("StreamFiles")
+ @NonNull
+ public static Uri getUriForFile(@NonNull Context context, @NonNull String authority,
+ @NonNull File file, @NonNull String displayName) {
+ Uri uri = getUriForFile(context, authority, file);
+ return uri.buildUpon().appendQueryParameter(DISPLAYNAME_FIELD, displayName).build();
+ }
+
+ /**
+ * Use a content URI returned by
+ * {@link #getUriForFile(Context, String, File) getUriForFile()} to get information about a file
+ * managed by the FileProvider.
+ * FileProvider reports the column names defined in {@link OpenableColumns}:
+ * application/octet-stream.
+ */
+ @Nullable
+ @Override
+ public String getType(@NonNull Uri uri) {
+ // ContentProvider has already checked granted permissions
+ final File file = getLocalPathStrategy().getFileForUri(uri);
+
+ final int lastDot = file.getName().lastIndexOf('.');
+ if (lastDot >= 0) {
+ final String extension = file.getName().substring(lastDot + 1);
+ final String mime = MimeTypeMap.getSingleton().getMimeTypeFromExtension(extension);
+ if (mime != null) {
+ return mime;
+ }
+ }
+
+ return "application/octet-stream";
+ }
+
+ /**
+ * Unrestricted version of getType
+ * called, when caller does not have corresponding permissions
+ */
+ //@Override
+ @SuppressWarnings("MissingOverride")
+ @Nullable
+ public String getTypeAnonymous(@NonNull Uri uri) {
+ return "application/octet-stream";
+ }
+
+ /**
+ * By default, this method throws an {@link UnsupportedOperationException}. You must
+ * subclass FileProvider if you want to provide different functionality.
+ */
+ @Override
+ public Uri insert(@NonNull Uri uri, @NonNull ContentValues values) {
+ throw new UnsupportedOperationException("No external inserts");
+ }
+
+ /**
+ * By default, this method throws an {@link UnsupportedOperationException}. You must
+ * subclass FileProvider if you want to provide different functionality.
+ */
+ @Override
+ public int update(@NonNull Uri uri, @NonNull ContentValues values, @Nullable String selection,
+ @Nullable String[] selectionArgs) {
+ throw new UnsupportedOperationException("No external updates");
+ }
+
+ /**
+ * Deletes the file associated with the specified content URI, as
+ * returned by {@link #getUriForFile(Context, String, File) getUriForFile()}. Notice that this
+ * method does not throw an {@link IOException}; you must check its return value.
+ *
+ * @param uri A content URI for a file, as returned by
+ * {@link #getUriForFile(Context, String, File) getUriForFile()}.
+ * @param selection Ignored. Set to {@code null}.
+ * @param selectionArgs Ignored. Set to {@code null}.
+ * @return 1 if the delete succeeds; otherwise, 0.
+ */
+ @Override
+ public int delete(@NonNull Uri uri, @Nullable String selection,
+ @Nullable String[] selectionArgs) {
+ // ContentProvider has already checked granted permissions
+ final File file = getLocalPathStrategy().getFileForUri(uri);
+ return file.delete() ? 1 : 0;
+ }
+
+ /**
+ * By default, FileProvider automatically returns the
+ * {@link ParcelFileDescriptor} for a file associated with a content://
+ * {@link Uri}. To get the {@link ParcelFileDescriptor}, call
+ * {@link ContentResolver#openFileDescriptor(Uri, String)
+ * ContentResolver.openFileDescriptor}.
+ *
+ * To override this method, you must provide your own subclass of FileProvider.
+ *
+ * @param uri A content URI associated with a file, as returned by
+ * {@link #getUriForFile(Context, String, File) getUriForFile()}.
+ * @param mode Access mode for the file. May be "r" for read-only access, "rw" for read and
+ * write access, or "rwt" for read and write access that truncates any existing file.
+ * @return A new {@link ParcelFileDescriptor} with which you can access the file.
+ */
+ @SuppressLint("UnknownNullness") // b/171012356
+ @Override
+ public ParcelFileDescriptor openFile(@NonNull Uri uri, @NonNull String mode)
+ throws FileNotFoundException {
+ // ContentProvider has already checked granted permissions
+ final File file = getLocalPathStrategy().getFileForUri(uri);
+ final int fileMode = modeToMode(mode);
+ return ParcelFileDescriptor.open(file, fileMode);
+ }
+
+ /** Return the local {@link PathStrategy}, creating it if necessary. */
+ private PathStrategy getLocalPathStrategy() {
+ synchronized (this) {
+ if (mLocalPathStrategy == null) {
+ mLocalPathStrategy = getPathStrategy(getContext(), mAuthority, mResourceId);
+ }
+
+ return mLocalPathStrategy;
+ }
+ }
+
+ /**
+ * Return {@link PathStrategy} for given authority, either by parsing or
+ * returning from cache.
+ */
+ private static PathStrategy getPathStrategy(Context context, String authority, int resourceId) {
+ PathStrategy strat;
+ synchronized (sCache) {
+ strat = sCache.get(authority);
+ if (strat == null) {
+ try {
+ strat = parsePathStrategy(context, authority, resourceId);
+ } catch (IOException e) {
+ throw new IllegalArgumentException(
+ "Failed to parse " + META_DATA_FILE_PROVIDER_PATHS + " meta-data", e);
+ } catch (XmlPullParserException e) {
+ throw new IllegalArgumentException(
+ "Failed to parse " + META_DATA_FILE_PROVIDER_PATHS + " meta-data", e);
+ }
+ sCache.put(authority, strat);
+ }
+ }
+ return strat;
+ }
+
+ @VisibleForTesting
+ static XmlResourceParser getFileProviderPathsMetaData(Context context, String authority,
+ @Nullable ProviderInfo info,
+ int resourceId) {
+ if (info == null) {
+ throw new IllegalArgumentException(
+ "Couldn't find meta-data for provider with authority " + authority);
+ }
+
+ if (info.metaData == null && resourceId != 0) {
+ info.metaData = new Bundle(1);
+ info.metaData.putInt(META_DATA_FILE_PROVIDER_PATHS, resourceId);
+ }
+
+ final XmlResourceParser in = info.loadXmlMetaData(
+ context.getPackageManager(), META_DATA_FILE_PROVIDER_PATHS);
+ if (in == null) {
+ throw new IllegalArgumentException(
+ "Missing " + META_DATA_FILE_PROVIDER_PATHS + " meta-data");
+ }
+
+ return in;
+ }
+
+ /**
+ * Parse and return {@link PathStrategy} for given authority as defined in
+ * {@link #META_DATA_FILE_PROVIDER_PATHS} {@code + * Strategies must be symmetric so that mapping a {@link File} to a + * {@link Uri} and then back to a {@link File} points at the original + * target. + *
+ * Strategies must remain consistent across app launches, and not rely on + * dynamic state. This ensures that any generated {@link Uri} can still be + * resolved if your process is killed and later restarted. + * + * @see SimplePathStrategy + */ + interface PathStrategy { + /** + * Return a {@link Uri} that represents the given {@link File}. + */ + Uri getUriForFile(File file); + + /** + * Return a {@link File} that represents the given {@link Uri}. + */ + File getFileForUri(Uri uri); + } + + /** + * Strategy that provides access to files living under a narrow allowed list + * of filesystem roots. It will throw {@link SecurityException} if callers try + * accessing files outside the configured roots. + *
+ * For example, if configured with
+ * {@code addRoot("myfiles", context.getFilesDir())}, then
+ * {@code context.getFileStreamPath("foo.txt")} would map to
+ * {@code content://myauthority/myfiles/foo.txt}.
+ */
+ static class SimplePathStrategy implements PathStrategy {
+ private final String mAuthority;
+ private final HashMap