fr.maxcom.os.storage

Class VolumeManager

java.lang.Object

fr.maxcom.os.storage.VolumeManager

public class VolumeManager
extends Object

A volume manager.

The purpose of a volume manager is to access the external Storage Units of an Android device, as any other part of the file system. For each plugged-in unit, you get a Volume object.

Emulation mode

When developing on a device without any USB connector or with a fewer number of connectors than the expected target, you can fake one or more existing ordinary internal directory as an additional Storage Container hosting emulated USB devices, with addEmulatedStorageContainer().

In that directory, normal files are ignored but each directory simulates a mount point for a volume.

Since:

3.1 - Is not backwards compatible and supersedes previous versions.

Examples

Here is a possible tree for one emulated Storage Container having two USB devices:

/mnt/sdcard/Movies/
                  |_ usb-emu1/
                  |          |_ .libmedia
                  |          |_ myVideo.mp4
                  |_ usb-emu2/
                             |_ myOtherVideo.mp4
 

Here is a partial sample of usage in an application:

VolumeManager volumeManager = new VolumeManager();
volumeManager.addEmulatedStorageContainer("/mnt/sdcard/Movies");
List<Volume> volumes = volumeManager.getVolumes();
for (Volume v: volumes) {
        Log.d(TAG, "volume label: " + v.getLabel());
}
 

Suppose there is a USB stick labeled Android and that the .libmedia file contains MyLabel, here is the potential output:

volume label: Android
volume label: MyLabel
volume label: usb-emu2
 

Constructor Summary

Constructors

Constructor and Description
VolumeManager() Default constructor.

Method Summary

Modifier and Type	Method and Description
boolean	addEmulatedStorageContainer(File directory) Adds an emulated storage container where looking for volumes.
boolean	addEmulatedStorageContainer(String pathname) Adds an emulated storage container where looking for volumes.
String[]	getDebugReport() Builds a debug report.
static Intent	getStorageAccessIntent() Returns an intent to spin up the Storage Access Framework picker UI and select a directory subtree.
List<Volume>	getVolumes() Returns the list of currently available volumes.
void	logDebugReport() Writes the lines from getDebugReport() to the log.
static void	onStorageAccessResult(Intent resultData) Persists the authorization to access the tree selected by the Storage Access Framework picker UI.
static void	postponeStorageAccessFrameworkUntilMarshmallow() Postpones the usage of Storage Access Framework until Marshmallow (6.0) version.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VolumeManager

public VolumeManager()

Default constructor.

Method Detail

postponeStorageAccessFrameworkUntilMarshmallow

public static void postponeStorageAccessFrameworkUntilMarshmallow()

Postpones the usage of Storage Access Framework until Marshmallow (6.0) version. By default, this class uses SAF as of Lollipop (5.0).

Staying with the default is recommended.

getStorageAccessIntent

public static Intent getStorageAccessIntent()

Returns an intent to spin up the Storage Access Framework picker UI and select a directory subtree. A null is returned in case SAF is not available or not involved (refer to postponeStorageAccessFrameworkUntilMarshmallow()

Returns:

The intent or null.

onStorageAccessResult

public static void onStorageAccessResult(Intent resultData)

Persists the authorization to access the tree selected by the Storage Access Framework picker UI. Call this method from onActivityResult(), for the matching startActivityForResult() fired with the intent from getStorageAccessIntent() and when resultCode is RESULT_OK.

Parameters:

resultData - What is returned by onActivityResult().

addEmulatedStorageContainer

public boolean addEmulatedStorageContainer(String pathname)

Adds an emulated storage container where looking for volumes. May be called more than once and is fine even if the directory is already registered.

Parameters:

pathname - The pathname to a directory hosting emulated volumes.

Returns:

true if the pathname designates an existing entry and this entry is a directory.

See Also:

Emulation mode

addEmulatedStorageContainer

public boolean addEmulatedStorageContainer(File directory)

Adds an emulated storage container where looking for volumes. May be called more than once and is fine even if the directory is already registered.

Parameters:

directory - The directory hosting emulated volumes.

Returns:

true if the argument designates an existing entry and this entry is a directory.

See Also:

Emulation mode

getVolumes

public List<Volume> getVolumes()

Returns the list of currently available volumes. A volume may be physical or emulated.

Returns:

A list of volumes, possibly empty.

logDebugReport

public void logDebugReport()

Writes the lines from getDebugReport() to the log. Logging is done with the Debug level.

getDebugReport

public String[] getDebugReport()

Builds a debug report. Because of the so broad range of device hardwares, there may be some cases where the exposed Volumes are not exactly what is expected. To help in the resolution, you may provide to the user of your application a way to report this lack. This method will collect public informations about the environment. It is not intended to be displayed to the user, neither to be understood by the developer of the app. How the data is exported from the app is up to you. Finally, it has to be attached to a request for support to Libmedia team for analysis.

Returns:

The report lines.