Skip to content

Most visited

Recently visited

navigation

StorageManager

public class StorageManager
extends Object

java.lang.Object
   ↳ android.os.storage.StorageManager


StorageManager is the interface to the systems storage service. The storage manager handles storage-related items such as Opaque Binary Blobs (OBBs).

OBBs contain a filesystem that maybe be encrypted on disk and mounted on-demand from an application. OBBs are a good way of providing large amounts of binary assets without packaging them into APKs as they may be multiple gigabytes in size. However, due to their size, they're most likely stored in a shared storage pool accessible from all programs. The system does not guarantee the security of the OBB file itself: if any program modifies the OBB, there is no guarantee that a read from that OBB will produce the expected output.

Get an instance of this class by calling getSystemService(java.lang.String) with an argument of STORAGE_SERVICE.

Summary

Constants

String ACTION_MANAGE_STORAGE

Activity Action: Allows the user to manage their storage.

int FLAG_ALLOCATE_AGGRESSIVE

Flag indicating that a disk space allocation request should operate in an aggressive mode.

Public methods

void allocateBytes(File path, long bytes, int flags)

Allocate the requested number of bytes for your application to use at the given path.

void allocateBytes(FileDescriptor fd, long bytes, int flags)

Allocate the requested number of bytes for your application to use in the given open file.

long getAllocatableBytes(File path, int flags)

Return the maximum number of new bytes that your app can allocate for itself using allocateBytes(File, long, int) at the given path.

long getCacheQuotaBytes(File path)

Return quota size in bytes for all cached data belonging to the calling app on the filesystem that hosts the given path.

long getCacheSizeBytes(File path)

Return total size in bytes of all cached data belonging to the calling app on the filesystem that hosts the given path.

String getMountedObbPath(String rawPath)

Check the mounted path of an Opaque Binary Blob (OBB) file.

StorageVolume getPrimaryStorageVolume()

Return the primary shared/external storage volume available to the current user.

StorageVolume getStorageVolume(File file)

Return the StorageVolume that contains the given file, or null if none.

List<StorageVolume> getStorageVolumes()

Return the list of shared/external storage volumes available to the current user.

boolean isCacheBehaviorAtomic(File path)

Read the current value set by setCacheBehaviorAtomic(File, boolean).

boolean isCacheBehaviorTombstone(File path)

Read the current value set by setCacheBehaviorTombstone(File, boolean).

boolean isEncrypted(File file)

Return if data stored at or under the given path will be encrypted while at rest.

boolean isObbMounted(String rawPath)

Check whether an Opaque Binary Blob (OBB) is mounted or not.

boolean mountObb(String rawPath, String key, OnObbStateChangeListener listener)

Mount an Opaque Binary Blob (OBB) file.

ParcelFileDescriptor openProxyFileDescriptor(int mode, ProxyFileDescriptorCallback callback)

Opens seekable ParcelFileDescriptor that routes file operation requests to ProxyFileDescriptorCallback.

void setCacheBehaviorAtomic(File path, boolean atomic)

Enable or disable special cache behavior that treats this directory and its contents as an atomic unit.

void setCacheBehaviorTombstone(File path, boolean tombstone)

Enable or disable special cache behavior that leaves deleted cache files intact as tombstones.

boolean unmountObb(String rawPath, boolean force, OnObbStateChangeListener listener)

Unmount an Opaque Binary Blob (OBB) file asynchronously.

Inherited methods

From class java.lang.Object

Constants

ACTION_MANAGE_STORAGE

added in API level 25
String ACTION_MANAGE_STORAGE

Activity Action: Allows the user to manage their storage. This activity provides the ability to free up space on the device by deleting data such as apps.

Input: Nothing.

Output: Nothing.

Constant Value: "android.os.storage.action.MANAGE_STORAGE"

FLAG_ALLOCATE_AGGRESSIVE

int FLAG_ALLOCATE_AGGRESSIVE

Flag indicating that a disk space allocation request should operate in an aggressive mode. This flag should only be rarely used in situations that are critical to system health or security.

When set, the system is more aggressive about the data that it considers for possible deletion when allocating disk space.

Note: your app must hold the ALLOCATE_AGGRESSIVE permission for this flag to take effect.

See also:

Constant Value: 1 (0x00000001)

Public methods

allocateBytes

void allocateBytes (File path, 
                long bytes, 
                int flags)

Allocate the requested number of bytes for your application to use at the given path. This will cause the system to delete any cached files necessary to satisfy your request.

Attempts to allocate disk space beyond the value returned by getAllocatableBytes(File, int) will fail.

Since multiple apps can be running simultaneously, this method may be subject to race conditions. If possible, consider using allocateBytes(FileDescriptor, long, int) which will guarantee that bytes are allocated to an opened file.

Parameters
path File: the path where you'd like to allocate disk space.
bytes long: the number of bytes to allocate.
flags int: to apply to the request.
Throws
IOException

See also:

allocateBytes

void allocateBytes (FileDescriptor fd, 
                long bytes, 
                int flags)

Allocate the requested number of bytes for your application to use in the given open file. This will cause the system to delete any cached files necessary to satisfy your request.

Attempts to allocate disk space beyond the value returned by getAllocatableBytes(File, int) will fail.

This method guarantees that bytes have been allocated to the opened file, otherwise it will throw if fast allocation is not possible. Fast allocation is typically only supported in private app data directories, and on shared/external storage devices which are emulated.

Parameters
fd FileDescriptor: the open file that you'd like to allocate disk space for.
bytes long: the number of bytes to allocate. This is the desired final size of the open file.
flags int: to apply to the request.
Throws
IOException

See also:

getAllocatableBytes

long getAllocatableBytes (File path, 
                int flags)

Return the maximum number of new bytes that your app can allocate for itself using allocateBytes(File, long, int) at the given path. This value is typically larger than getUsableSpace(), since the system may be willing to delete cached files to satisfy an allocation request.

This method is best used as a pre-flight check, such as deciding if there is enough space to store an entire music album before you allocate space for each audio file in the album. Attempts to allocate disk space beyond the returned value will fail.

Note: if your app uses the android:sharedUserId manifest feature, then allocatable space for all packages in your shared UID is tracked together as a single unit.

Parameters
path File: the path where you're considering allocating disk space, since allocatable space can vary widely depending on the underlying storage device.
flags int: to apply to the request.
Returns
long the maximum number of new bytes that the calling app can allocate using allocateBytes(File, long, int).
Throws
IOException

getCacheQuotaBytes

long getCacheQuotaBytes (File path)

Return quota size in bytes for all cached data belonging to the calling app on the filesystem that hosts the given path.

If your app goes above this quota, your cached files will be some of the first to be deleted when additional disk space is needed. Conversely, if your app stays under this quota, your cached files will be some of the last to be deleted when additional disk space is needed.

This quota will change over time depending on how frequently the user interacts with your app, and depending on how much disk space is used.

Note: if your app uses the android:sharedUserId manifest feature, then cached data for all packages in your shared UID is tracked together as a single unit.

Parameters
path File
Returns
long

See also:

getCacheSizeBytes

long getCacheSizeBytes (File path)

Return total size in bytes of all cached data belonging to the calling app on the filesystem that hosts the given path.

Cached data tracked by this method always includes getCacheDir() and getCodeCacheDir(), and it also includes getExternalCacheDir() if the primary shared/external storage is hosted on the same storage device as your private data.

Note: if your app uses the android:sharedUserId manifest feature, then cached data for all packages in your shared UID is tracked together as a single unit.

Parameters
path File
Returns
long

See also:

getMountedObbPath

added in API level 9
String getMountedObbPath (String rawPath)

Check the mounted path of an Opaque Binary Blob (OBB) file. This will give you the path to where you can obtain access to the internals of the OBB.

Parameters
rawPath String: path to OBB image
Returns
String absolute path to mounted OBB image data or null if not mounted or exception encountered trying to read status

getPrimaryStorageVolume

added in API level 24
StorageVolume getPrimaryStorageVolume ()

Return the primary shared/external storage volume available to the current user. This volume is the same storage device returned by getExternalStorageDirectory() and getExternalFilesDir(String).

Returns
StorageVolume

getStorageVolume

added in API level 24
StorageVolume getStorageVolume (File file)

Return the StorageVolume that contains the given file, or null if none.

Parameters
file File
Returns
StorageVolume

getStorageVolumes

added in API level 24
List<StorageVolume> getStorageVolumes ()

Return the list of shared/external storage volumes available to the current user. This includes both the primary shared storage device and any attached external volumes including SD cards and USB drives.

Returns
List<StorageVolume>

See also:

isCacheBehaviorAtomic

boolean isCacheBehaviorAtomic (File path)

Read the current value set by setCacheBehaviorAtomic(File, boolean).

Parameters
path File
Returns
boolean
Throws
IOException

isCacheBehaviorTombstone

boolean isCacheBehaviorTombstone (File path)

Read the current value set by setCacheBehaviorTombstone(File, boolean).

Parameters
path File
Returns
boolean
Throws
IOException

isEncrypted

added in API level 24
boolean isEncrypted (File file)

Return if data stored at or under the given path will be encrypted while at rest. This can help apps avoid the overhead of double-encrypting data.

Parameters
file File
Returns
boolean

isObbMounted

added in API level 9
boolean isObbMounted (String rawPath)

Check whether an Opaque Binary Blob (OBB) is mounted or not.

Parameters
rawPath String: path to OBB image
Returns
boolean true if OBB is mounted; false if not mounted or on error

mountObb

added in API level 9
boolean mountObb (String rawPath, 
                String key, 
                OnObbStateChangeListener listener)

Mount an Opaque Binary Blob (OBB) file. If a key is specified, it is supplied to the mounting process to be used in any encryption used in the OBB.

The OBB will remain mounted for as long as the StorageManager reference is held by the application. As soon as this reference is lost, the OBBs in use will be unmounted. The OnObbStateChangeListener registered with this call will receive the success or failure of this operation.

Note: you can only mount OBB files for which the OBB tag on the file matches a package ID that is owned by the calling program's UID. That is, shared UID applications can attempt to mount any other application's OBB that shares its UID.

Parameters
rawPath String: the path to the OBB file
key String: secret used to encrypt the OBB; may be null if no encryption was used on the OBB.
listener OnObbStateChangeListener: will receive the success or failure of the operation
Returns
boolean whether the mount call was successfully queued or not

openProxyFileDescriptor

ParcelFileDescriptor openProxyFileDescriptor (int mode, 
                ProxyFileDescriptorCallback callback)

Opens seekable ParcelFileDescriptor that routes file operation requests to ProxyFileDescriptorCallback.

Parameters
mode int: The desired access mode, must be one of MODE_READ_ONLY, MODE_WRITE_ONLY, or MODE_READ_WRITE
callback ProxyFileDescriptorCallback: Callback to process file operation requests issued on returned file descriptor. The callback is invoked on a thread managed by the framework.
Returns
ParcelFileDescriptor Seekable ParcelFileDescriptor.
Throws
IOException

setCacheBehaviorAtomic

void setCacheBehaviorAtomic (File path, 
                boolean atomic)

Enable or disable special cache behavior that treats this directory and its contents as an atomic unit.

When enabled and this directory is considered for automatic deletion by the OS, all contained files will either be deleted together, or not at all. This is useful when you have a directory that contains several related metadata files that depend on each other, such as movie file and a subtitle file.

When enabled, the newest lastModified() value of any contained files is considered the modified time of the entire directory.

This behavior can only be set on a directory, and it applies recursively to all contained files and directories.

Parameters
path File
atomic boolean
Throws
IOException

setCacheBehaviorTombstone

void setCacheBehaviorTombstone (File path, 
                boolean tombstone)

Enable or disable special cache behavior that leaves deleted cache files intact as tombstones.

When enabled and a file contained in this directory is automatically deleted by the OS, the file will be truncated to have a length of 0 bytes instead of being fully deleted. This is useful if you need to distinguish between a file that was deleted versus one that never existed.

This behavior can only be set on a directory, and it applies recursively to all contained files and directories.

Note: this behavior is ignored completely if the user explicitly requests that all cached data be cleared.

Parameters
path File
tombstone boolean
Throws
IOException

unmountObb

added in API level 9
boolean unmountObb (String rawPath, 
                boolean force, 
                OnObbStateChangeListener listener)

Unmount an Opaque Binary Blob (OBB) file asynchronously. If the force flag is true, it will kill any application needed to unmount the given OBB (even the calling application).

The OnObbStateChangeListener registered with this call will receive the success or failure of this operation.

Note: you can only mount OBB files for which the OBB tag on the file matches a package ID that is owned by the calling program's UID. That is, shared UID applications can obtain access to any other application's OBB that shares its UID.

Parameters
rawPath String: path to the OBB file
force boolean: whether to kill any programs using this in order to unmount it
listener OnObbStateChangeListener: will receive the success or failure of the operation
Returns
boolean whether the unmount call was successfully queued or not
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.