Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0ba24ed6 authored by Jeff Sharkey's avatar Jeff Sharkey Committed by android-build-merger
Browse files

Merge "Improve developer docs for storage APIs." into oc-dev 

am: 05b52d8b

Change-Id: I282786d353e3dc406c7123daa00d3e7fe43de7bc
parents f734de79 05b52d8b

core/java/android/content/ContentProvider.java

+7 −0
Original line number Original line Diff line number Diff line
@@ -44,6 +44,7 @@ import android.os.ParcelFileDescriptor; 
import android.os.Process;

import android.os.Process;

import android.os.RemoteException;

import android.os.RemoteException;

import android.os.UserHandle;

import android.os.UserHandle;

import android.os.storage.StorageManager;

import android.text.TextUtils;

import android.text.TextUtils;

import android.util.Log;

import android.util.Log;

import android.util.MathUtils;

import android.util.MathUtils;
@@ -1376,6 +1377,12 @@ public abstract class ContentProvider implements ComponentCallbacks2 { 
     * android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener)},

     * android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener)},

     * {@link ParcelFileDescriptor#createReliablePipe()}, or

     * {@link ParcelFileDescriptor#createReliablePipe()}, or

     * {@link ParcelFileDescriptor#createReliableSocketPair()}.

     * {@link ParcelFileDescriptor#createReliableSocketPair()}.

     * <p>

     * If you need to return a large file that isn't backed by a real file on

     * disk, such as a file on a network share or cloud storage service,

     * consider using

     * {@link StorageManager#openProxyFileDescriptor(int, android.os.ProxyFileDescriptorCallback, android.os.Handler)}

     * which will let you to stream the content on-demand.

     *

     *

     * <p class="note">For use in Intents, you will want to implement {@link #getType}

     * <p class="note">For use in Intents, you will want to implement {@link #getType}

     * to return the appropriate MIME type for the data returned here with

     * to return the appropriate MIME type for the data returned here with

core/java/android/os/storage/StorageManager.java

+45 −8
Original line number Original line Diff line number Diff line
@@ -29,6 +29,7 @@ import android.annotation.SuppressLint; 
import android.annotation.SystemApi;

import android.annotation.SystemApi;

import android.annotation.SystemService;

import android.annotation.SystemService;

import android.annotation.WorkerThread;

import android.annotation.WorkerThread;

import android.app.Activity;

import android.app.ActivityThread;

import android.app.ActivityThread;

import android.content.ContentResolver;

import android.content.ContentResolver;

import android.content.Context;

import android.content.Context;
@@ -159,6 +160,12 @@ public class StorageManager { 
     * If the sending application has a specific storage device or allocation

     * If the sending application has a specific storage device or allocation

     * size in mind, they can optionally define {@link #EXTRA_UUID} or

     * size in mind, they can optionally define {@link #EXTRA_UUID} or

     * {@link #EXTRA_REQUESTED_BYTES}, respectively.

     * {@link #EXTRA_REQUESTED_BYTES}, respectively.

     * <p>

     * This intent should be launched using

     * {@link Activity#startActivityForResult(Intent, int)} so that the user

     * knows which app is requesting the storage space. The returned result will

     * be {@link Activity#RESULT_OK} if the requested space was made available,

     * or {@link Activity#RESULT_CANCELED} otherwise.

     */

     */

    @SdkConstant(SdkConstant.SdkConstantType.ACTIVITY_INTENT_ACTION)

    @SdkConstant(SdkConstant.SdkConstantType.ACTIVITY_INTENT_ACTION)

    public static final String ACTION_MANAGE_STORAGE = "android.os.storage.action.MANAGE_STORAGE";

    public static final String ACTION_MANAGE_STORAGE = "android.os.storage.action.MANAGE_STORAGE";
@@ -1476,15 +1483,26 @@ public class StorageManager { 
    }

    }





    /**

    /**

     * Opens seekable ParcelFileDescriptor that routes file operation requests to

     * Opens a seekable {@link ParcelFileDescriptor} that proxies all low-level

     * ProxyFileDescriptorCallback.

     * I/O requests back to the given {@link ProxyFileDescriptorCallback}.

     * <p>

     * This can be useful when you want to provide quick access to a large file

     * that isn't backed by a real file on disk, such as a file on a network

     * share, cloud storage service, etc. As an example, you could respond to a

     * {@link ContentResolver#openFileDescriptor(android.net.Uri, String)}

     * request by returning a {@link ParcelFileDescriptor} created with this

     * method, and then stream the content on-demand as requested.

     * <p>

     * Another useful example might be where you have an encrypted file that

     * you're willing to decrypt on-demand, but where you want to avoid

     * persisting the cleartext version.

     *

     *

     * @param mode The desired access mode, must be one of

     * @param mode The desired access mode, must be one of

     *            {@link ParcelFileDescriptor#MODE_READ_ONLY},

     *            {@link ParcelFileDescriptor#MODE_READ_ONLY},

     *            {@link ParcelFileDescriptor#MODE_WRITE_ONLY}, or

     *            {@link ParcelFileDescriptor#MODE_WRITE_ONLY}, or

     *            {@link ParcelFileDescriptor#MODE_READ_WRITE}

     *            {@link ParcelFileDescriptor#MODE_READ_WRITE}

     * @param callback Callback to process file operation requests issued on returned file

     * @param callback Callback to process file operation requests issued on

     *     descriptor.

     *            returned file descriptor.

     * @param handler Handler that invokes callback methods.

     * @param handler Handler that invokes callback methods.

     * @return Seekable ParcelFileDescriptor.

     * @return Seekable ParcelFileDescriptor.

     * @throws IOException

     * @throws IOException
@@ -1496,7 +1514,6 @@ public class StorageManager { 
        return openProxyFileDescriptor(mode, callback, handler, null);

        return openProxyFileDescriptor(mode, callback, handler, null);

    }

    }







    /** {@hide} */

    /** {@hide} */

    @VisibleForTesting

    @VisibleForTesting

    public int getProxyFileDescriptorMountPointId() {

    public int getProxyFileDescriptorMountPointId() {
@@ -1678,6 +1695,10 @@ public class StorageManager { 
     * persist, you can launch {@link #ACTION_MANAGE_STORAGE} with the

     * persist, you can launch {@link #ACTION_MANAGE_STORAGE} with the

     * {@link #EXTRA_UUID} and {@link #EXTRA_REQUESTED_BYTES} options to help

     * {@link #EXTRA_UUID} and {@link #EXTRA_REQUESTED_BYTES} options to help

     * involve the user in freeing up disk space.

     * involve the user in freeing up disk space.

     * <p>

     * If you're progressively allocating an unbounded amount of storage space

     * (such as when recording a video) you should avoid calling this method

     * more than once every 30 seconds.

     * <p class="note">

     * <p class="note">

     * Note: if your app uses the {@code android:sharedUserId} manifest feature,

     * Note: if your app uses the {@code android:sharedUserId} manifest feature,

     * then allocatable space for all packages in your shared UID is tracked

     * then allocatable space for all packages in your shared UID is tracked
@@ -1695,6 +1716,7 @@ public class StorageManager { 
     * @throws IOException when the storage device isn't present, or when it

     * @throws IOException when the storage device isn't present, or when it

     *             doesn't support allocating space.

     *             doesn't support allocating space.

     */

     */

    @WorkerThread

    public @BytesLong long getAllocatableBytes(@NonNull UUID storageUuid)

    public @BytesLong long getAllocatableBytes(@NonNull UUID storageUuid)

            throws IOException {

            throws IOException {

        return getAllocatableBytes(storageUuid, 0);

        return getAllocatableBytes(storageUuid, 0);
@@ -1702,6 +1724,7 @@ public class StorageManager { 




    /** @hide */

    /** @hide */

    @SystemApi

    @SystemApi

    @WorkerThread

    @SuppressLint("Doclava125")

    @SuppressLint("Doclava125")

    public long getAllocatableBytes(@NonNull UUID storageUuid,

    public long getAllocatableBytes(@NonNull UUID storageUuid,

            @RequiresPermission @AllocateFlags int flags) throws IOException {

            @RequiresPermission @AllocateFlags int flags) throws IOException {
@@ -1718,6 +1741,7 @@ public class StorageManager { 




    /** @removed */

    /** @removed */

    @Deprecated

    @Deprecated

    @WorkerThread

    @SuppressLint("Doclava125")

    @SuppressLint("Doclava125")

    public long getAllocatableBytes(@NonNull File path,

    public long getAllocatableBytes(@NonNull File path,

            @RequiresPermission @AllocateFlags int flags) throws IOException {

            @RequiresPermission @AllocateFlags int flags) throws IOException {
@@ -1736,6 +1760,10 @@ public class StorageManager { 
     * subject to race conditions. If possible, consider using

     * subject to race conditions. If possible, consider using

     * {@link #allocateBytes(FileDescriptor, long, int)} which will guarantee

     * {@link #allocateBytes(FileDescriptor, long, int)} which will guarantee

     * that bytes are allocated to an opened file.

     * that bytes are allocated to an opened file.

     * <p>

     * If you're progressively allocating an unbounded amount of storage space

     * (such as when recording a video) you should avoid calling this method

     * more than once every 60 seconds.

     *

     *

     * @param storageUuid the UUID of the storage volume where you'd like to

     * @param storageUuid the UUID of the storage volume where you'd like to

     *            allocate disk space. The UUID for a specific path can be

     *            allocate disk space. The UUID for a specific path can be
@@ -1746,6 +1774,7 @@ public class StorageManager { 
     *             trouble allocating the requested space.

     *             trouble allocating the requested space.

     * @see #getAllocatableBytes(UUID, int)

     * @see #getAllocatableBytes(UUID, int)

     */

     */

    @WorkerThread

    public void allocateBytes(@NonNull UUID storageUuid, @BytesLong long bytes)

    public void allocateBytes(@NonNull UUID storageUuid, @BytesLong long bytes)

            throws IOException {

            throws IOException {

        allocateBytes(storageUuid, bytes, 0);

        allocateBytes(storageUuid, bytes, 0);
@@ -1753,6 +1782,7 @@ public class StorageManager { 




    /** @hide */

    /** @hide */

    @SystemApi

    @SystemApi

    @WorkerThread

    @SuppressLint("Doclava125")

    @SuppressLint("Doclava125")

    public void allocateBytes(@NonNull UUID storageUuid, @BytesLong long bytes,

    public void allocateBytes(@NonNull UUID storageUuid, @BytesLong long bytes,

            @RequiresPermission @AllocateFlags int flags) throws IOException {

            @RequiresPermission @AllocateFlags int flags) throws IOException {
@@ -1768,6 +1798,7 @@ public class StorageManager { 




    /** @removed */

    /** @removed */

    @Deprecated

    @Deprecated

    @WorkerThread

    @SuppressLint("Doclava125")

    @SuppressLint("Doclava125")

    public void allocateBytes(@NonNull File path, @BytesLong long bytes,

    public void allocateBytes(@NonNull File path, @BytesLong long bytes,

            @RequiresPermission @AllocateFlags int flags) throws IOException {

            @RequiresPermission @AllocateFlags int flags) throws IOException {
@@ -1786,6 +1817,10 @@ public class StorageManager { 
     * otherwise it will throw if fast allocation is not possible. Fast

     * otherwise it will throw if fast allocation is not possible. Fast

     * allocation is typically only supported in private app data directories,

     * allocation is typically only supported in private app data directories,

     * and on shared/external storage devices which are emulated.

     * and on shared/external storage devices which are emulated.

     * <p>

     * If you're progressively allocating an unbounded amount of storage space

     * (such as when recording a video) you should avoid calling this method

     * more than once every 60 seconds.

     *

     *

     * @param fd the open file that you'd like to allocate disk space for.

     * @param fd the open file that you'd like to allocate disk space for.

     * @param bytes the number of bytes to allocate. This is the desired final

     * @param bytes the number of bytes to allocate. This is the desired final
@@ -1799,12 +1834,14 @@ public class StorageManager { 
     * @see #getAllocatableBytes(UUID, int)

     * @see #getAllocatableBytes(UUID, int)

     * @see Environment#isExternalStorageEmulated(File)

     * @see Environment#isExternalStorageEmulated(File)

     */

     */

    @WorkerThread

    public void allocateBytes(FileDescriptor fd, @BytesLong long bytes) throws IOException {

    public void allocateBytes(FileDescriptor fd, @BytesLong long bytes) throws IOException {

        allocateBytes(fd, bytes, 0);

        allocateBytes(fd, bytes, 0);

    }

    }





    /** @hide */

    /** @hide */

    @SystemApi

    @SystemApi

    @WorkerThread

    @SuppressLint("Doclava125")

    @SuppressLint("Doclava125")

    public void allocateBytes(FileDescriptor fd, @BytesLong long bytes,

    public void allocateBytes(FileDescriptor fd, @BytesLong long bytes,

            @RequiresPermission @AllocateFlags int flags) throws IOException {

            @RequiresPermission @AllocateFlags int flags) throws IOException {