On Android 4.4 (KitKat), Google has made access to the SD card quite restricted.
As of Android Lollipop (5.0), developers can use a new API that asks the user to confirm to allow access to specific folders, as written on the this Google-Groups post .
The post directs you to visit two websites:
This looks like an inner example (perhaps to be shown on the API demos later), but it's quite hard to understand what's going on.
This is the official documentation of the new API, but it doesn't tell enough details about how to use it.
Here's what it tells you:
If you really do need full access to an entire subtree of documents, start by launching ACTION_OPEN_DOCUMENT_TREE to let the user pick a directory. Then pass the resulting getData() into fromTreeUri(Context, Uri) to start working with the user selected tree.
As you navigate the tree of DocumentFile instances, you can always use getUri() to obtain the Uri representing the underlying document for that object, for use with openInputStream(Uri), etc.
To simplify your code on devices running KITKAT or earlier, you can use fromFile(File) which emulates the behavior of a DocumentsProvider.
I have a few questions about the new API:
Lots of good questions, let's dig in. :)
Here's a great tutorial for interacting with the Storage Access Framework in KitKat:
https://developer.android.com/guide/topics/providers/document-provider.html#client
Interacting with the new APIs in Lollipop is very similar. To prompt the user to pick a directory tree, you can launch an intent like this:
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);
startActivityForResult(intent, 42);
Then in your onActivityResult(), you can pass the user-picked Uri to the new DocumentFile helper class. Here's a quick example that lists the files in the picked directory, and then creates a new file:
public void onActivityResult(int requestCode, int resultCode, Intent resultData) {
if (resultCode == RESULT_OK) {
Uri treeUri = resultData.getData();
DocumentFile pickedDir = DocumentFile.fromTreeUri(this, treeUri);
// List all existing files inside picked directory
for (DocumentFile file : pickedDir.listFiles()) {
Log.d(TAG, "Found file " + file.getName() + " with size " + file.length());
}
// Create a new file and write into it
DocumentFile newFile = pickedDir.createFile("text/plain", "My Novel");
OutputStream out = getContentResolver().openOutputStream(newFile.getUri());
out.write("A long time ago...".getBytes());
out.close();
}
}
The Uri returned by DocumentFile.getUri()
is flexible enough to use with may different platform APIs. For example, you could share it using Intent.setData()
with Intent.FLAG_GRANT_READ_URI_PERMISSION
.
If you want to access that Uri from native code, you can call ContentResolver.openFileDescriptor()
and then use ParcelFileDescriptor.getFd()
or detachFd()
to obtain a traditional POSIX file descriptor integer.
By default, the Uris returned through Storage Access Frameworks intents are not persisted across reboots. The platform "offers" the ability to persist the permission, but you still need to "take" the permission if you want it. In our example above, you'd call:
getContentResolver().takePersistableUriPermission(treeUri,
Intent.FLAG_GRANT_READ_URI_PERMISSION |
Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
You can always figure out what persisted grants your app has access to through the ContentResolver.getPersistedUriPermissions()
API. If you no longer need access to a persisted Uri, you can release it with ContentResolver.releasePersistableUriPermission()
.
No, we can't retroactively add new functionality to older versions of the platform.
There's currently no UI that shows this, but you can find the details in the "Granted Uri Permissions" section of adb shell dumpsys activity providers
output.
Uri permission grants are isolated on a per-user basis, just like all other multi-user platform functionality. That is, the same app running under two different users has no overlaping or shared Uri permission grants.
The backing DocumentProvider can revoke permission at any time, such as when a cloud-based document is deleted. The most common way to discover these revoked permissions is when they disappear from ContentResolver.getPersistedUriPermissions()
mentioned above.
Permissions are also revoked whenever app data is cleared for either app involved in the grant.
Yep, the ACTION_OPEN_DOCUMENT_TREE
intent gives you recursive access to both existing and newly created files and directories.
Yep, multiple selection has been supported since KitKat, and you can allow it by setting EXTRA_ALLOW_MULTIPLE
when starting your ACTION_OPEN_DOCUMENT
intent. You can use Intent.setType()
or EXTRA_MIME_TYPES
to narrow the types of files that can be picked:
http://developer.android.com/reference/android/content/Intent.html#ACTION_OPEN_DOCUMENT
Yep, the primary shared storage device should appear in the picker, even on the emulator. If your app only uses the Storage Access Framework for accessing shared storage, you no longer need the READ/WRITE_EXTERNAL_STORAGE
permissions at all and can remove them or use the android:maxSdkVersion
feature to only request them on older platform versions.
When physical media is involved, the UUID (such as FAT serial number) of the underlying media is always burned into the returned Uri. The system uses this to connect you to the media that the user originally selected, even if the user swaps the media around between multiple slots.
If the user swaps in a second card, you'll need to prompt to gain access to the new card. Since the system remembers grants on a per-UUID basis, you'll continue to have previously-granted access to the original card if the user reinserts it later.