Merge "docs: Updating Scoped Directory Access preview docs for DP2" into mnc-mr-docs

am: bc90f38

* commit 'bc90f38e8fdc1eb9041b1dc0f725c3496cd6f0fd':
  docs: Updating Scoped Directory Access preview docs for DP2

Change-Id: I10cbf525e4247de7503085286d3fa7135c753813

docs/html/preview/_book.yaml

@@ -70,6 +70,8 @@ toc:
     path: /preview/j8-jack.html
   - title: Android for Work Updates
     path: /preview/features/afw.html
+  - title: Scoped Directory Access
+    path: /preview/features/scoped-folder-access.html
 
 - title: Samples
   path: /preview/samples.html

docs/html/preview/features/scoped-folder-access.jd

@@ -44,6 +44,14 @@ Use this intent to access external storage directories. To get a list of
 all available volumes, including removable media volumes, use
 <code>StorageManager.getVolumesList()</code>.</p>
 
+<p>
+On secondary volumes, such as external SD cards, pass in null when calling
+<code>StorageVolume.createAccessIntent()</code> to request access to the entire
+volume, instead of a specific directory.
+<code>StorageVolume.createAccessIntent()</code> returns null if you pass in
+null to the primary volume, or if you pass in an invalid directory name.
+</p>
+
 <p>The following code snippet is an example of how to open the
 <code>Pictures</code> directory in the primary shared storage:</p>
 
@@ -122,4 +130,15 @@ user.</p>
 
 <p>If the user denies access to an external directory, do not immediately
 request access again. Repeatedly insisting on access results in a poor user
-experience.</p>
+experience. If a request is denied by the user, and the app requests access
+again, the UI displays a <b>Don't ask again</b> checkbox:</p>
+
+<img src="{@docRoot}preview/images/scoped-folder-access-dont-ask.png"
+srcset="{@docRoot}preview/images/scoped-folder-access-dont-ask.png 1x,
+{@docRoot}preview/images/scoped-folder-access-dont-ask_2x.png 2x" />
+<p class="img-caption"><strong>Figure 1.</strong> An application making a
+second request for access to removable media.</p>
+
+<p>If the user selects <b>Don't ask again</b> and denies the request, all
+future requests for the given directory from your app will be automatically
+denied, and no request UI will be presented to the user.</p>

docs/html/preview/preview_toc.cs

@@ -88,6 +88,9 @@
 
         <li><a href="<?cs var:toroot ?>preview/features/afw.html"
         >Android for Work Updates</a></li>
+
+        <li><a href="<?cs var:toroot ?>preview/features/scoped-folder-access.html"
+        >Scoped Directory Access</a></li>
       </ul>
   </li>