title: How to use the new SD card access API presented for Android 5.0 (Lollipop)?
body: <h2>Background</h2>
  
  <p>On <a href="https://en.wikipedia.org/wiki/Android_version_history#Android_4.4_KitKat_.28API_level_19.29" rel="noreferrer">Android 4.4</a> (KitKat), Google has made access to the SD card quite restricted.</p>
  
  <p>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 <a href="https://code.google.com/p/android/issues/detail?id=67570#c4444" rel="noreferrer"><strong>this Google-Groups post</strong></a> .</p>
  
  <h2>The problem</h2>
  
  <p>The post directs you to visit two websites:</p>
  
  <ul>
  <li><a href="https://android.googlesource.com/platform/development/+/android-5.0.0_r2/samples/Vault/src/com/example/android/vault/VaultProvider.java#258" rel="noreferrer">https://android.googlesource.com/platform/development/+/android-5.0.0_r2/samples/Vault/src/com/example/android/vault/VaultProvider.java#258</a></li>
  </ul>
  
  <p>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.</p>
  
  <ul>
  <li><a href="http://developer.android.com/reference/android/support/v4/provider/DocumentFile.html" rel="noreferrer">http://developer.android.com/reference/android/support/v4/provider/DocumentFile.html</a></li>
  </ul>
  
  <p>This is the official documentation of the new API, but it doesn't tell enough details about how to use it.</p>
  
  <p>Here's what it tells you:</p>
  
  <blockquote>
    <p>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.</p>
    
    <p>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.</p>
    
    <p>To simplify your code on devices running KITKAT or earlier, you can
    use fromFile(File) which emulates the behavior of a DocumentsProvider.</p>
  </blockquote>
  
  <h2>The questions</h2>
  
  <p>I have a few questions about the new API:</p>
  
  <ol>
  <li>How do you really use it?</li>
  <li>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?</li>
  <li>How do you handle this problem on Kitkat? Is it a part of the support library?</li>
  <li>Is there a settings screen on the OS that shows which apps have access to which files/folders?</li>
  <li>What happens if an app is installed for multiple users on the same device?</li>
  <li>Is there any other documentation/tutorial about this new API?</li>
  <li>Can the permissions be revoked? If so, is there an intent that's being sent to the app?</li>
  <li>Would asking for the permission work recursively on a selected folder?</li>
  <li>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?</li>
  <li>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).</li>
  <li>What happens when the user replaces the SD card with another one?</li>
  </ol>