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 android.app.Activity} is active. For an {@link Intent} going to a * {@link android.app.Service}, the permissions are available as long as the * {@link android.app.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: *
*
* 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.
*
<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" /> **
files/ subdirectory of your app's internal storage
* area. This subdirectory is the same as the value returned by {@link Context#getFilesDir()
* Context.getFilesDir()}.
* *<external-path name="name" path="path" /> **
files/ subdirectory of this this root.
* *<cache-path name="name" path="path" /> **
* These child elements all use the same attributes: *
*name="name"
* path attribute.
* path="path"
* 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> **
* 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 android.content.Intent}. The client app that receives the content URI can open the file * and access its contents by calling * {@link android.content.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(), "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.
* 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.
* * Permissions granted in an {@link Intent} remain in effect while the stack of the receiving * {@link android.app.Activity} is active. When the stack finishes, the permissions are * automatically removed. Permissions granted to one {@link android.app.Activity} in a client * app are automatically extended to other components of that 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 android.app.Activity#startActivityForResult(Intent, int, Bundle) startActivityResult()}, * which sends an {@link Intent} to your app to start an {@link android.app.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 android.app.Activity#setResult(int, Intent) setResult()}. *
** You can also put the content URI in a {@link android.content.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 android.content.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()}. *
** 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 ATTR_NAME = "name"; private static final String ATTR_PATH = "path"; private static final File DEVICE_ROOT = new File("/"); // @GuardedBy("sCache") private static 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 <provider>} element in your app's manifest.
* @param file A {@link File} pointing to the filename for which you want a
* 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(Context context, String authority, File file) {
final PathStrategy strategy = getPathStrategy(context, authority);
return strategy.getUriForFile(file);
}
/**
* 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 android.provider.OpenableColumns}:
* application/octet-stream.
*/
@Override
public String getType(Uri uri) {
// ContentProvider has already checked granted permissions
final File file = mStrategy.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";
}
/**
* By default, this method throws an {@link java.lang.UnsupportedOperationException}. You must
* subclass FileProvider if you want to provide different functionality.
*/
@Override
public Uri insert(Uri uri, ContentValues values) {
throw new UnsupportedOperationException("No external inserts");
}
/**
* By default, this method throws an {@link java.lang.UnsupportedOperationException}. You must
* subclass FileProvider if you want to provide different functionality.
*/
@Override
public int update(Uri uri, ContentValues values, String selection, 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 java.io.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(Uri uri, String selection, String[] selectionArgs) {
// ContentProvider has already checked granted permissions
final File file = mStrategy.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 android.content.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.
*/
@Override
public ParcelFileDescriptor openFile(Uri uri, String mode) throws FileNotFoundException {
// ContentProvider has already checked granted permissions
final File file = mStrategy.getFileForUri(uri);
final int fileMode = modeToMode(mode);
return ParcelFileDescriptor.open(file, fileMode);
}
/**
* Return {@link PathStrategy} for given authority, either by parsing or
* returning from cache.
*/
private static PathStrategy getPathStrategy(Context context, String authority) {
PathStrategy strat;
synchronized (sCache) {
strat = sCache.get(authority);
if (strat == null) {
try {
strat = parsePathStrategy(context, authority);
} 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;
}
/**
* Parse and return {@link PathStrategy} for given authority as defined in
* {@link #META_DATA_FILE_PROVIDER_PATHS} {@code <meta-data>}.
*
* @see #getPathStrategy(Context, String)
*/
private static PathStrategy parsePathStrategy(Context context, String authority)
throws IOException, XmlPullParserException {
final SimplePathStrategy strat = new SimplePathStrategy(authority);
final ProviderInfo info = context.getPackageManager()
.resolveContentProvider(authority, PackageManager.GET_META_DATA);
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");
}
int type;
while ((type = in.next()) != END_DOCUMENT) {
if (type == START_TAG) {
final String tag = in.getName();
final String name = in.getAttributeValue(null, ATTR_NAME);
String path = in.getAttributeValue(null, ATTR_PATH);
File target = null;
if (TAG_ROOT_PATH.equals(tag)) {
target = buildPath(DEVICE_ROOT, path);
} else if (TAG_FILES_PATH.equals(tag)) {
target = buildPath(context.getFilesDir(), path);
} else if (TAG_CACHE_PATH.equals(tag)) {
target = buildPath(context.getCacheDir(), path);
} else if (TAG_EXTERNAL.equals(tag)) {
target = buildPath(Environment.getExternalStorageDirectory(), path);
}
if (target != null) {
strat.addRoot(name, target);
}
}
}
return strat;
}
/**
* Strategy for mapping between {@link File} and {@link Uri}.
* * 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}. */ public Uri getUriForFile(File file); /** * Return a {@link File} that represents the given {@link Uri}. */ public File getFileForUri(Uri uri); } /** * Strategy that provides access to files living under a narrow whitelist 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