public final class StorageVolume extends Object implements Parcelable
A device always has one (and one only) primary storage volume, but it could have extra volumes, like SD cards and USB drives. This object represents the logical view of a storage volume for a specific user: different users might have different views for the same physical volume (for example, if the volume is a built-in emulated storage).
The storage volume is not necessarily mounted, applications should use getState()
to
verify its state.
Applications willing to read or write to this storage volume needs to get a permission from the user first, which can be achieved in the following ways:
Environment.DIRECTORY_PICTURES
), they
can use the createAccessIntent(String)
. This is the recommend way, since it provides a
simpler API and narrows the access to the given directory (and its descendants).
Intent.ACTION_OPEN_DOCUMENT
and
Intent.ACTION_OPEN_DOCUMENT_TREE
, although these APIs do not guarantee the user will
select this specific volume.
android.Manifest.permission#READ_EXTERNAL_STORAGE
and
android.Manifest.permission#WRITE_EXTERNAL_STORAGE
permissions respectively, with the
latter including the former. This approach is discouraged, since users may be hesitant to grant
broad access to all files contained on a storage device.
It can be obtained through StorageManager.getStorageVolumes()
and
StorageManager.getPrimaryStorageVolume()
and also as an extra in some broadcasts
(see EXTRA_STORAGE_VOLUME
).
See Environment.getExternalStorageDirectory()
for more info about shared/external
storage semantics.
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static Parcelable.Creator<StorageVolume> |
CREATOR |
static String |
EXTRA_DIRECTORY_NAME
Name of the String extra used by
createAccessIntent . |
static String |
EXTRA_STORAGE_VOLUME
Name of the
Parcelable extra in the Intent.ACTION_MEDIA_REMOVED ,
Intent.ACTION_MEDIA_UNMOUNTED , Intent.ACTION_MEDIA_CHECKING ,
Intent.ACTION_MEDIA_NOFS , Intent.ACTION_MEDIA_MOUNTED ,
Intent.ACTION_MEDIA_SHARED , Intent.ACTION_MEDIA_BAD_REMOVAL ,
Intent.ACTION_MEDIA_UNMOUNTABLE , and Intent.ACTION_MEDIA_EJECT broadcast that
contains a StorageVolume . |
static int |
STORAGE_ID_INVALID |
static int |
STORAGE_ID_PRIMARY |
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_ELIDE_DUPLICATES, PARCELABLE_WRITE_RETURN_VALUE
Constructor and Description |
---|
StorageVolume(String id,
int storageId,
File path,
String description,
boolean primary,
boolean removable,
boolean emulated,
long mtpReserveSize,
boolean allowMassStorage,
long maxFileSize,
UserHandle owner,
String fsUuid,
String state) |
Modifier and Type | Method and Description |
---|---|
boolean |
allowMassStorage()
Returns true if this volume can be shared via USB mass storage.
|
Intent |
createAccessIntent(String directoryName)
Builds an intent to give access to a standard storage directory or entire volume after
obtaining the user's approval.
|
int |
describeContents()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation.
|
String |
dump() |
void |
dump(IndentingPrintWriter pw) |
boolean |
equals(Object obj)
Indicates whether some other object is "equal to" this one.
|
String |
getDescription(Context context)
Returns a user-visible description of the volume.
|
int |
getFatVolumeId()
Parse and return volume UUID as FAT volume ID, or return -1 if unable to
parse or UUID is unknown.
|
String |
getId() |
long |
getMaxFileSize()
Returns maximum file size for the volume, or zero if it is unbounded.
|
int |
getMtpReserveSpace()
Number of megabytes of space to leave unallocated by MTP.
|
UserHandle |
getOwner() |
String |
getPath()
Returns the mount path for the volume.
|
File |
getPathFile() |
String |
getState()
Returns the current state of the volume.
|
int |
getStorageId()
Returns the MTP storage ID for the volume.
|
String |
getUserLabel() |
String |
getUuid()
Gets the volume UUID, if any.
|
int |
hashCode()
Returns a hash code value for the object.
|
boolean |
isEmulated()
Returns true if the volume is emulated.
|
boolean |
isPrimary()
Returns true if the volume is the primary shared/external storage, which is the volume
backed by
Environment.getExternalStorageDirectory() . |
boolean |
isRemovable()
Returns true if the volume is removable.
|
String |
toString()
Returns a string representation of the object.
|
void |
writeToParcel(Parcel parcel,
int flags)
Flatten this object in to a Parcel.
|
public static final String EXTRA_STORAGE_VOLUME
Parcelable
extra in the Intent.ACTION_MEDIA_REMOVED
,
Intent.ACTION_MEDIA_UNMOUNTED
, Intent.ACTION_MEDIA_CHECKING
,
Intent.ACTION_MEDIA_NOFS
, Intent.ACTION_MEDIA_MOUNTED
,
Intent.ACTION_MEDIA_SHARED
, Intent.ACTION_MEDIA_BAD_REMOVAL
,
Intent.ACTION_MEDIA_UNMOUNTABLE
, and Intent.ACTION_MEDIA_EJECT
broadcast that
contains a StorageVolume
.public static final String EXTRA_DIRECTORY_NAME
createAccessIntent
.public static final int STORAGE_ID_INVALID
public static final int STORAGE_ID_PRIMARY
public static final Parcelable.Creator<StorageVolume> CREATOR
public String getId()
public String getPath()
public File getPathFile()
public String getDescription(Context context)
public boolean isPrimary()
Environment.getExternalStorageDirectory()
.public boolean isRemovable()
public boolean isEmulated()
public int getStorageId()
public int getMtpReserveSpace()
public boolean allowMassStorage()
public long getMaxFileSize()
public UserHandle getOwner()
public String getUuid()
public int getFatVolumeId()
public String getUserLabel()
public String getState()
Environment.MEDIA_UNKNOWN
, Environment.MEDIA_REMOVED
,
Environment.MEDIA_UNMOUNTED
, Environment.MEDIA_CHECKING
,
Environment.MEDIA_NOFS
, Environment.MEDIA_MOUNTED
,
Environment.MEDIA_MOUNTED_READ_ONLY
, Environment.MEDIA_SHARED
,
Environment.MEDIA_BAD_REMOVAL
, or Environment.MEDIA_UNMOUNTABLE
.public Intent createAccessIntent(String directoryName)
When invoked, the system will ask the user to grant access to the requested directory (and
its descendants). The result of the request will be returned to the activity through the
onActivityResult
method.
To gain access to descendants (child, grandchild, etc) documents, use
DocumentsContract.buildDocumentUriUsingTree(Uri, String)
, or
DocumentsContract.buildChildDocumentsUriUsingTree(Uri, String)
with the returned URI.
If your application only needs to store internal data, consider using
Context.getExternalFilesDirs
,
Context.getExternalCacheDirs()
, or Context.getExternalMediaDirs()
, which
require no permissions to read or write.
Access to the entire volume is only available for non-primary volumes (for the primary
volume, apps can use the android.Manifest.permission#READ_EXTERNAL_STORAGE
and
android.Manifest.permission#WRITE_EXTERNAL_STORAGE
permissions) and should be used
with caution, since users are more likely to deny access when asked for entire volume access
rather than specific directories.
directoryName
- must be one of Environment.DIRECTORY_MUSIC
,
Environment.DIRECTORY_PODCASTS
, Environment.DIRECTORY_RINGTONES
,
Environment.DIRECTORY_ALARMS
, Environment.DIRECTORY_NOTIFICATIONS
,
Environment.DIRECTORY_PICTURES
, Environment.DIRECTORY_MOVIES
,
Environment.DIRECTORY_DOWNLOADS
, Environment.DIRECTORY_DCIM
, or
Environment.DIRECTORY_DOCUMENTS
, or {code null} to request access to the
entire volume.null
if the requested directory is invalid for
that volume.DocumentsContract
public boolean equals(Object obj)
Object
The equals
method implements an equivalence relation
on non-null object references:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
x
and y
, multiple invocations of
x.equals(y)
consistently return true
or consistently return false
, provided no
information used in equals
comparisons on the
objects is modified.
x
,
x.equals(null)
should return false
.
The equals
method for class Object
implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x
and
y
, this method returns true
if and only
if x
and y
refer to the same object
(x == y
has the value true
).
Note that it is generally necessary to override the hashCode
method whenever this method is overridden, so as to maintain the
general contract for the hashCode
method, which states
that equal objects must have equal hash codes.
equals
in class Object
obj
- the reference object with which to compare.true
if this object is the same as the obj
argument; false
otherwise.Object.hashCode()
,
HashMap
public int hashCode()
Object
HashMap
.
The general contract of hashCode
is:
hashCode
method
must consistently return the same integer, provided no information
used in equals
comparisons on the object is modified.
This integer need not remain consistent from one execution of an
application to another execution of the same application.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
Object.equals(java.lang.Object)
method, then calling the hashCode
method on each of the
two objects must produce distinct integer results. However, the
programmer should be aware that producing distinct integer results
for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by
class Object
does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
JavaTM programming language.)
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
public String dump()
public void dump(IndentingPrintWriter pw)
public int describeContents()
Parcelable
Parcelable.writeToParcel(Parcel, int)
,
the return value of this method must include the
Parcelable.CONTENTS_FILE_DESCRIPTOR
bit.describeContents
in interface Parcelable
Parcelable.CONTENTS_FILE_DESCRIPTOR
public void writeToParcel(Parcel parcel, int flags)
Parcelable
writeToParcel
in interface Parcelable
parcel
- The Parcel in which the object should be written.flags
- Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE
.