How to use the new SD card access API presented for Android 5.0 (Lollipop)?

Background

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 problem

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.

The questions

I have a few questions about the new API:

1. How do you really use it?


2. According to the post, the OS will remember that the app was given a permission to access the files/folders. How do you check if you can access the files/folders? Is there a function that returns me the list of files/folders that I can access?


3. How do you handle this problem on Kitkat? Is it a part of the support library?


4. Is there a settings screen on the OS that shows which apps have access to which files/folders?


5. What happens if an app is installed for multiple users on the same device?


6. Is there any other documentation/tutorial about this new API?


7. Can the permissions be revoked? If so, is there an intent that's being sent to the app?



8. Would asking for the permission work recursively on a selected folder?


9. Would using the permission also allow to give the user a chance of multiple selection by user's choice? Or does the app need to specifically tell the intent which files/folders to allow?


10. Is there a way on the emulator to try the new API ? I mean, it has SD-card partition, but it works as the primary external storage, so all access to it is already given (using a simple permission).


11. What happens when the user replaces the SD card with another one?