diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml index 5629ddd48d7ee..7d7282db5fd0c 100644 --- a/docs/html/_redirects.yaml +++ b/docs/html/_redirects.yaml @@ -1214,3 +1214,5 @@ redirects: to: /training/tv/tif/content-recording.html - from: /preview/features/direct-boot.html to: /training/articles/direct-boot.html +- from: /preview/features/scoped-folder-access.html + to: /training/articles/scoped-directory-access.html diff --git a/docs/html/guide/topics/data/data-storage.jd b/docs/html/guide/topics/data/data-storage.jd index a745d00f5e39c..770340be2e003 100644 --- a/docs/html/guide/topics/data/data-storage.jd +++ b/docs/html/guide/topics/data/data-storage.jd @@ -252,6 +252,17 @@ external storage on a computer or removes the media, and there's no security enf save to the external storage. All applications can read and write files placed on the external storage and the user can remove them.

+

Using Scoped Directory Access

+ +On Android 7.0 or later, if you need access to a specific directory on +external storage, use scoped directory access. Scoped directory access +simplifies how your application accesses standard external storage directories, +such as the Pictures directory, and provides a simple +permissions UI that clearly details what directory the application is +requesting access to. For more details on scoped directory access, see +Using +Scoped Directory Access. +

Getting access to external storage

In order to read or write files on the external storage, your app must acquire the diff --git a/docs/html/images/android-7.0/scoped-directory-access-dont-ask.png b/docs/html/images/android-7.0/scoped-directory-access-dont-ask.png new file mode 100644 index 0000000000000..66829484f2aba Binary files /dev/null and b/docs/html/images/android-7.0/scoped-directory-access-dont-ask.png differ diff --git a/docs/html/images/android-7.0/scoped-directory-access-dont-ask_2x.png b/docs/html/images/android-7.0/scoped-directory-access-dont-ask_2x.png new file mode 100644 index 0000000000000..be717f96ac0aa Binary files /dev/null and b/docs/html/images/android-7.0/scoped-directory-access-dont-ask_2x.png differ diff --git a/docs/html/images/android-7.0/scoped-directory-access-framed.png b/docs/html/images/android-7.0/scoped-directory-access-framed.png new file mode 100644 index 0000000000000..e4d619ad1d8b4 Binary files /dev/null and b/docs/html/images/android-7.0/scoped-directory-access-framed.png differ diff --git a/docs/html/images/android-7.0/scoped-directory-access-framed_2x.png b/docs/html/images/android-7.0/scoped-directory-access-framed_2x.png new file mode 100644 index 0000000000000..fe17bce12b0c3 Binary files /dev/null and b/docs/html/images/android-7.0/scoped-directory-access-framed_2x.png differ diff --git a/docs/html/preview/images/scoped-folder-access-dont-ask.png b/docs/html/preview/images/scoped-folder-access-dont-ask.png deleted file mode 100644 index 5c505d956f5e7..0000000000000 Binary files a/docs/html/preview/images/scoped-folder-access-dont-ask.png and /dev/null differ diff --git a/docs/html/preview/images/scoped-folder-access-dont-ask_2x.png b/docs/html/preview/images/scoped-folder-access-dont-ask_2x.png deleted file mode 100644 index 612b69f8926fc..0000000000000 Binary files a/docs/html/preview/images/scoped-folder-access-dont-ask_2x.png and /dev/null differ diff --git a/docs/html/preview/images/scoped-folder-access-framed.png b/docs/html/preview/images/scoped-folder-access-framed.png deleted file mode 100644 index 0169e4196aff5..0000000000000 Binary files a/docs/html/preview/images/scoped-folder-access-framed.png and /dev/null differ diff --git a/docs/html/preview/images/scoped-folder-access-framed_2x.png b/docs/html/preview/images/scoped-folder-access-framed_2x.png deleted file mode 100644 index fd59ef17d94ce..0000000000000 Binary files a/docs/html/preview/images/scoped-folder-access-framed_2x.png and /dev/null differ diff --git a/docs/html/training/_book.yaml b/docs/html/training/_book.yaml index ccc4a7f9d79e7..23d9c9e20ea15 100644 --- a/docs/html/training/_book.yaml +++ b/docs/html/training/_book.yaml @@ -1397,6 +1397,11 @@ toc: path_attributes: - name: description value: How use device encrypted storage during Direct Boot mode. + - title: Using Scoped Directory Access + path: /training/articles/scoped-directory-access.html + path_attributes: + - name: description + value: How to use scoped directory access to request access to external storage directories. - title: Best Practices for Permissions & Identifiers path: /training/best-permissions-ids.html diff --git a/docs/html/preview/features/scoped-folder-access.jd b/docs/html/training/articles/scoped-directory-access.jd similarity index 60% rename from docs/html/preview/features/scoped-folder-access.jd rename to docs/html/training/articles/scoped-directory-access.jd index 06dd6652677de..1e0bf39fc5940 100644 --- a/docs/html/preview/features/scoped-folder-access.jd +++ b/docs/html/training/articles/scoped-directory-access.jd @@ -1,11 +1,10 @@ -page.title=Scoped Directory Access -page.keywords=preview,sdk,scoped directory access -page.tags=androidn +page.title=Using Scoped Directory Access +page.keywords=scoped directory access @jd:body -

-
+
+

In this document

  1. Accessing an External Storage Directory
    2. @@ -32,29 +31,37 @@ via a system UI, which is unnecessary if your app always accesses the same external directory. -

    Android N provides a new simplified API to access -common external storage directories.

    +

    Android 7.0 provides a simplified API to access common external storage +directories.

    Accessing an External Storage Directory

    -

    Use the StorageManager class to get the appropriate -StorageVolume instance. Then, create an intent by calling the -StorageVolume.createAccessIntent() method of that instance. +

    Use the {@link android.os.storage.StorageManager} class to get the +appropriate {@link android.os.storage.StorageVolume} instance. Then, create +an intent by calling the +{@link android.os.storage.StorageVolume#createAccessIntent +StorageVolume.createAccessIntent()} method of that instance. Use this intent to access external storage directories. To get a list of -all available volumes, including removable media volumes, use -StorageManager.getVolumesList().

    +all available volumes, including removable media +volumes, use {@link android.os.storage.StorageManager#getStorageVolumes +StorageManager.getStorageVolumes()}.

    If you have information about a specific file, use -StorageManager.getStorageVolume(File) to get the -StorageVolume that contains the file. Call -createAccessIntent() on this StorageVolume to access +{@link android.os.storage.StorageManager#getStorageVolume +StorageManager.getStorageVolume(File)} to get the +{@link android.os.storage.StorageVolume} that contains the file. Call +{@link android.os.storage.StorageVolume#createAccessIntent +createAccessIntent()} on this +{@link android.os.storage.StorageVolume} to access the external storage directory for the file.

    On secondary volumes, such as external SD cards, pass in null when calling -StorageVolume.createAccessIntent() to request access to the entire +{@link android.os.storage.StorageVolume#createAccessIntent +createAccessIntent()} to request access to the entire volume, instead of a specific directory. -StorageVolume.createAccessIntent() returns null if you pass in +{@link android.os.storage.StorageVolume#createAccessIntent +createAccessIntent()} returns null if you pass in null to the primary volume, or if you pass in an invalid directory name.

    @@ -63,7 +70,7 @@ null to the primary volume, or if you pass in an invalid directory name. 
     StorageManager sm = (StorageManager)getSystemService(Context.STORAGE_SERVICE);
-StorageVolume volume = sm.getPrimaryVolume();
+StorageVolume volume = sm.getPrimaryStorageVolume();
 Intent intent = volume.createAccessIntent(Environment.DIRECTORY_PICTURES);
 startActivityForResult(intent, request_code);
    @@ -71,25 +78,27 @@ startActivityForResult(intent, request_code);

    The system attempts to grant access to the external directory, and if necessary confirms access with the user using a simplified UI:

    - +

    Figure 1. An application requesting access to the Pictures directory.

    If the user grants access, the system calls your -onActivityResult() override with a result code of -Activity.RESULT_OK, and intent data that contains the URI. Use +{@link android.app.Activity#onActivityResult onActivityResult()} override +with a result code of {@link android.app.Activity#RESULT_OK +RESULT_OK}, and intent data that contains the URI. Use the provided URI to access directory information, similar to using URIs returned by the Storage Access Framework.

    If the user doesn't grant access, the system calls your -onActivityResult() override with a result code of -Activity.RESULT_CANCELED, and null intent data.

    +{@link android.app.Activity#onActivityResult onActivityResult()} override +with a result code of {@link android.app.Activity#RESULT_CANCELED +RESULT_CANCELED}, and null intent data.

    -

    Note: Getting access to a specific external directory +

    Getting access to a specific external directory also gains access to subdirectories within that directory.

    Accessing a Directory on Removable Media

    @@ -112,9 +121,9 @@ first add a {@link android.content.BroadcastReceiver} that listens for the

    When the user mounts removable media, like an SD card, the system sends a {@link android.os.Environment#MEDIA_MOUNTED} notification. This notification -provides a StorageVolume object in the intent data that you can -use to access directories on the removable media. The following example -accesses the Pictures directory on removable media:

    +provides a {@link android.os.storage.StorageVolume} object in the intent data +that you can use to access directories on the removable media. The following +example accesses the Pictures directory on removable media:

     // BroadcastReceiver has already cached the MEDIA_MOUNTED
@@ -129,19 +138,22 @@ startActivityForResult(intent, request_code);
 
 
    Where possible, persist the external directory access URI so you don't have
 to repeatedly ask the user for access. Once the user has granted access, call
-getContentResolver().takePersistableUriPermssion() with the
-directory access URI. The system will persist the URI and subsequent access
-requests will return RESULT_OK and not show confirmation UI to the
-user.
    
+{@link android.content.Context#getContentResolver getContentResolver()} and
+with the returned {@link android.content.ContentResolver} call
+{@link android.content.ContentResolver#takePersistableUriPermission
+takePersistableUriPermission()} with the directory access URI. The system will
+persist the URI and subsequent access requests will return
+{@link android.app.Activity#RESULT_OK RESULT_OK} and not show confirmation
+UI to the user.
    
 
 
    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. If a request is denied by the user, and the app requests access
 again, the UI displays a Don't ask again checkbox:
    
 
-
+
 
    Figure 1. An application making a
 second request for access to removable media.