cordova-plugin-env

Download Activity	Travis CI	Snyk

A small Cordova plugin that exposes Android's Environment object.

This plugin defines a global Environment object, which provides access to the common directories and helper methods available on Android's Environment object. The Environment object is available from the navigator object after the deviceready event fires.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.Env);
}

Installation

From the Command line:

cordova plugin add cordova-plugin-env

Config.xml for PhoneGap Build:

<gap:plugin name="cordova-plugin-env" source="npm" />

These commands will install the plugin from npm. You can find this plugin up on npm here, or by searching for ecosystem:cordova in the npm registry like this.

Supported Platform

• Android

Env

The Env object provides a way to access the directories -- and some helper methods -- exposed by the Android Environment object.

Methods

Currently this plugin provides the following methods:

• isExternalStorageEmulated
• isExternalStorageRemovable
• isExternalStorageManager
• getExternalStorageState
• getDirectory
• getExternalStoragePublicDirectory (deprecated in Android API 29, but still available)

isExternalStorageEmulated

Parameters:

• successCallback: Callback that returns "true" if the external storage is emulated.
• errorCallback: Callback that executes if an error occurs during the call.

Example

if (navigator.Env) {
    console.log("Env object in navigator");
    navigator.Env.isExternalStorageEmulated(
        function (result) {
            if (result) {
                console.log("isExternalStorageEmulated returns: " + result);
            }
        },
        function (error) {
            console.log("isExternalStorageEmulated error: " + error);
        }
    );
} else {
    console.log("Plugin error: Env plugin not found (is it installed?)");
}

isExternalStorageRemovable

Parameters:

• successCallback: Callback that returns "true" if the external storage is removable.
• errorCallback: Callback that executes if an error occurs during the call.

Example

if (navigator.Env) {
    console.log("Env object in navigator");
    navigator.Env.isExternalStorageRemovable(
        function (result) {
            if (result) {
                console.log("isExternalStorageRemovable returns: " + result);
            }
        },
        function (error) {
            console.log("isExternalStorageRemovable error: " + error);
        }
    );
} else {
    console.log("Plugin error: Env plugin not found (is it installed?)");
}

isExternalStorageManager

Parameters:

• successCallback: Callback that returns "true" if the app has All Files Access.
• errorCallback: Callback that executes if an error occurs during the call.

Example

if (navigator.Env) {
    console.log("Env object in navigator");
    navigator.Env.isExternalStorageManager(
        function (result) {
            if (result) {
                console.log("isExternalStorageManager returns: " + result);
            }
        },
        function (error) {
            console.log("isExternalStorageRemovable error: " + error);
        }
    );
} else {
    console.log("Plugin error: Env plugin not found (is it installed?)");
}

getExternalStorageState

Parameters:

• successCallback: Callback that returns the string value of the External Storage State. See https://developer.android.com/reference/android/os/Environment.html#getExternalStorageState() for possible result values.
• errorCallback: Callback that executes if an error occurs during the call.

Example

if (navigator.Env) {
    console.log("Env object in navigator");
    navigator.Env.getExternalStorageState(
        function (state) {
            if (state) {
                console.log("External storage state: " + state);
            }
        },
        function (error) {
            console.log("getExternalStorageState error: " + error);
        }
    );
} else {
    console.log("Plugin error: Env plugin not found (is it installed?)");
}

getDirectory

Parameters:

• directory: (string) Special directory to look up (see "Directories" below).
• successCallback: Callback that returns the string name of the specified directory on this device.
• errorCallback: Callback that executes if an error occurs during the call.

Directories

Following are valid string values for the directory parameter above:

String value	Android directory
"Alarms"	DIRECTORY_ALARMS
"DCIM"	DIRECTORY_DCIM
"Documents"	DIRECTORY_DOCUMENTS
"Downloads"	DIRECTORY_DOWNLOADS
"Movies"	DIRECTORY_MOVIES
"Music"	DIRECTORY_MUSIC
"Notifications"	DIRECTORY_NOTIFICATIONS
"Pictures"	DIRECTORY_PICTURES
"Podcasts"	DIRECTORY_PODCASTS
"Ringtones"	DIRECTORY_RINGTONES

Example

if (navigator.Env) {
    console.log("Env object in navigator");
    navigator.Env.getDirectory("Documents", 
        function (path) {
            if (path) {
                console.log("getDirectory(Documents) returns: " + path);
            }
        },
        function (error) {
            console.log("getDirectory error: " + error);
        }
    );
} else {
    console.log("Plugin error: Env plugin not found (is it installed?)");
}

getExternalStoragePublicDirectory

DEPRECATION WARNING This method has been deprecated on Android API 29 and later.

Parameters:

• directory: (string) Directory to look up. This needs to be one of the strings returned by the getDirectory() call above.
• successCallback: Callback that returns the full path string of the specified directory on this device.
• errorCallback: Callback that executes if an error occurs during the call.

Example

if (navigator.Env) {
    console.log("Env object in navigator");
    // attempt to get Environment.DIRECTORY_DOWNLOADS
    navigator.Env.getDirectory("Downloads", 
        function (dirName) {
            if (dirName) {
                console.log("getDirectory(Downloads) returns: " + dirName);
                // success -- now try to get the full path for the shared Downloads directory
                navigator.Env.getExternalStoragePublicDirectory(dirName,
                    function(fullPath) {
                        console.log("getExternalStoragePublicDirectory(Downloads) returns: " + fullPath);
                    }, function (error) {
                        console.log("getExternalStoragePublicDirectory error: " + error);
                    }
                );
            }
        },
        function (error) {
            console.log("getDirectory error: " + error);
        }
    );
} else {
    console.log("Plugin error: Env plugin not found (is it installed?)");
}