voltmx.io.FileSystem Namespace
The voltmx.io.FileSystem namespace includes APIs to create, read, and navigate through the device file system.
Information about the voltmx.io.FileSystem namespace is presented in the following topic.
Functions
The voltmx.io.FileSystem namespace contains the following functions.
voltmx.io.FileSystem.browse
This API provides the ability to browse and select files from your local system.
Syntax
voltmx.io.FileSystem.browse(browseConfig,browseCallBack);
Input Parameters
Parameter | Description |
---|---|
browseConfig [String] - Mandatory | Configuration params which is a simple JSON object of key value pairs, that drive the possible options during the browse. Currently the following keys are supported in the configuration:selectMultipleFiles: (Boolean) - Default (true)filter: An array indicates what file Filters should be applied to the file selection dialog. The file Filters need to follow the conventions specified in the IANAMediaTypes specification. For more information, see https://www.iana.org/assignments/media-types/media-types.xhtml. |
browseCallBack [Object] - Mandatory |
Example
function selectBtn_onClick_seq0() { // Event on button click
var config = {
selectMultipleFiles: true,
filter: ["image/png", "image/jpeg"]
};
voltmx.io.FileSystem.browse(config, selectedFileCallback);
}
Return Values
None.
Platform Availability
- Desktop Web only
voltmx.io.FileSystem.copyBundledRawFileTo
This API copies a bundled file from the application binary to the specified destination path on the device. While copying the pre-bundled file, the destination file name can be different from the source.
Syntax
voltmx.io.FileSystem.copyBundledRawFileTo (String rawFileName, String destFilePath)
Input Parameters
Parameter | Description |
---|---|
rawFileName [String] | Specify the file name with the extension of a pre-bundled raw file that you want to copy. |
destFilePath [String] | Specify the absolute file path along with the file name and extension (if any) where you want to copy the pre-bundled file. In this parameter, the destination file name can be different from the source. |
Example
//The destination file name can be different from the source.
var destFilePath = voltmx.io.FileSystem.getDataDirectoryPath() + "/Destinationfile.pdf";
var fileObj = null;
try {
var file = new voltmx.io.File(destFilePath);
//copyBundledRawFileTo API overrides the destination file with new one.
//Hence check before copying
if (!file.exists()) {
var fileObj = voltmx.io.FileSystem.copyBundledRawFileTo(“Sourcefile.pdf”, destFilePath);
} else {
fileObj = file;
alert("File is already available");
return;
}
} catch (e) {
voltmx.print(“Exception“ + e);
}
Remarks
- When the app functionality is tested in functional preview application, the voltmx.io.FileSystem.copyBundledRawFileTo API looks for the file in the child app (Downloaded test application). If not found, searches for the same file in the parent app (Functional Preview application).
- The voltmx.io.FileSystem.copyBundledRawFileTo API overrides the destination file with new one if any file exists with the same name at the destination path.
For more information about bundling the files in the application binary, refer to the Pre bundling the Files topic.
Return Values
VoltMX.io.File returns a handle to the File object pointing to the destination file, if successful. If failure, then throws appropriate exception.
Exceptions
Error Code | Error Message |
---|---|
100 | Source file not found. |
100 | Invalid Destination. |
101 | Invalid number of arguments. |
106 | Unknown error. |
Platform Availability
- iOS
- Android
- Windows
voltmx.io.FileSystem.getAppGroupDirectoryPath
This API retrieves the root path of an app group.
Syntax
voltmx.io.FileSystem.getAppGroupDirectoryPath(appGroupID)
Parameters
Parameter | Description |
---|---|
appGroupID | Holds a string containing the unique ID of the app group. |
Example
var appGroupPath = voltmx.io.FileSystem.getAppGroupDirectoryPath("String");
Return Values
A string containing the fully-qualified path to the root directory of the app group.
Platform Availability
- iOS only
voltmx.io.FileSystem.getApplicationDirectoryPath
The getApplicationDirectoryPath API returns the application directory path.
Syntax
voltmx.io.FileSystem.getApplicationDirectoryPath()
Input Parameters
None
Example
var appDirectoryPath = voltmx.io.FileSystem.getApplicationDirectoryPath();
Return Values
String
Exceptions
None
Platform Availability
- iOS only
voltmx.io.FileSystem.getCacheDirectoryPath
The getCacheDirectoryPath API returns the application's cache directory path.
Syntax
voltmx.io.FileSystem.getCacheDirectoryPath()
Input Parameters
None
Example
var cacheDirectoryPath = voltmx.io.FileSystem.getCacheDirectoryPath();
Return Values
String
Exceptions
None
Platform Availability
- All native platforms
- Desktop Web
voltmx.io.FileSystem.getDatabaseDirectoryPath
This API returns the application's database directory path (from application's private file system) where voltmx.db APIs access the database files.
This API is useful in accessing the pre-bundled SQLite database file. You need to copy the pre-bundled database file to the directory path returned by the voltmx.io.FileSystem.getDatabaseDirectoryPath API, using the voltmx.io.FileSystem.copyBundledRawFileTo API. You can then use the voltmx.db.openDatabase API to open the SQLite database files after copying.
Syntax
voltmx.io.FileSystem.getDatabaseDirectoryPath()
Input Parameters
None
Example
//Example for opening the pre-bundled database
//The destination file name can be different from the source.
var destFilePath = voltmx.io.FileSystem.getDatabaseDirectoryPath() + ”test.db”;
var fileObj = null;
try {
var file = new voltmx.io.File(destFilePath);
//copyBundledRawFileTo API overrides the destination file with new one.
//Hence check before copying
if (!file.exists()) {
fileObj = voltmx.io.FileSystem.copyBundledRawFileTo(dbName, destFilePath);
} else {
fileObj = file;
alert("File is already available");
return;
}
} catch (e) {
voltmx.print(“Exception“ + e);
}
if (fileObj == null) {
voltmx.print(“Copy failed”);
} else {
voltmx.print(“Copy Success”);
}
dbObject = voltmx.db.openDatabase("test.db", "1.0", "Prebundled SQL Database", 5 * 1024 * 1024);
Return Values
Application's database directory path in the form of String.
Remarks
For Functional Preview, the path returned by the getDatabaseDirectoryPath API points to the child application on your device. This feature is available on iOS, Android, and Windows devices.
Exceptions
None
Platform Availability
- iOS
- Android
- Windows
voltmx.io.FileSystem.getDataDirectoryPath
This API returns the application’s data directory path.
Syntax
voltmx.io.FileSystem.getDataDirectoryPath()
Input Parameters
None
Example
var dataDirectoryPath = voltmx.io.FileSystem.getDataDirectoryPath();
Return Values
String
Remarks
For Functional Preview, the path returned by the getDataDirectoryPath API points to the child application on your device. This feature is available on iOS, Android, and Windows devices.
Exceptions
None
Platform Availability
- Applicable for all native platforms, except Desktop Web
voltmx.io.FileSystem.getExternalCacheDir
The getExternalCacheDir API returns the absolute path to the directory on the primary shared or external storage device where the application can store its cached files.
Syntax
voltmx.io.FileSystem.getExternalCacheDir();
Example
var dirPath = voltmx.io.FileSystem.getExternalCacheDir();
Return Values
String
Note: If the shared storage is not available, this API returns a
null
value.
Exceptions
None
Platform Availability
- Android
voltmx.io.FileSystem.getExternalCacheDirs
The getExternalCacheDirs API returns the absolute paths to the application-specific directories on all the shared or external storage devices where the application can store its cached files.
Syntax
voltmx.io.FileSystem.getExternalCacheDirs();
Example
var dirPath = voltmx.io.FileSystem.getExternalCacheDirs();
Return Values
Array of Strings
Note: If the shared storage is not available, this API returns a
null
value.
Exceptions
None
Platform Availability
- Android
Note: If your device runs on Android versions before Android KitKat, the voltmx.io.FileSystem.getExternalFilesDirs API returns the same result as the voltmx.io.FileSystem.getExternalFilesDir API.
voltmx.io.FileSystem.getExternalFilesDir
The getExternalFilesDir API returns the absolute path to the directory on the primary shared or external storage device where the application can store its persistent files.
Note: * From API level 29, apps do not require additional permissions to read and write files to this directory. * The files in this directory are internal to the application, and are deleted when you uninstall the app.
Syntax
voltmx.io.FileSystem.getExternalFilesDir([type](#type));
Input Parameters
Parameters | Description |
---|---|
type | The type of file directory to return. The type can have one of the following values:voltmx.io.FileSystem.DIRECTORY_MUSIC``voltmx.io.FileSystem.DIRECTORY_PODCASTS``voltmx.io.FileSystem.DIRECTORY_ALARMS``voltmx.io.FileSystem.DIRECTORY_RINGTONES``voltmx.io.FileSystem.DIRECTORY_NOTIFICATIONS``voltmx.io.FileSystem.DIRECTORY_PICTURES``voltmx.io.FileSystem.DIRECTORY_MOVIES > Note: If you provide null or invalid values for the type, the API returns the main directory path of the primary shared or external storage. |
Example
var dirPath = voltmx.io.FileSystem.getExternalFilesDir(voltmx.io.FileSystem.DIRECTORY_PICTURES);
Return Values
String
Note: If the shared storage is not available, this API returns a
null
value.
Exceptions
None
Platform Availability
- Android
voltmx.io.FileSystem.getExternalFilesDirs
The getExternalFilesDirs API returns the absolute paths to the application-specific directories on all the shared or external storage devices where the application can store its persistent files.
Note: * From API level 29, apps do not require additional permissions to read and write files to this directory. * The files in this directory are internal to the application, and are deleted when you uninstall the app.
Syntax
voltmx.io.FileSystem.getExternalFilesDirs([type](#type1));
Input Parameters
Parameters | Description |
---|---|
type | The type of file directory to return. The type can have one of the following values:voltmx.io.FileSystem.DIRECTORY_MUSIC``voltmx.io.FileSystem.DIRECTORY_PODCASTS``voltmx.io.FileSystem.DIRECTORY_ALARMS``voltmx.io.FileSystem.DIRECTORY_RINGTONES``voltmx.io.FileSystem.DIRECTORY_NOTIFICATIONS``voltmx.io.FileSystem.DIRECTORY_PICTURES``voltmx.io.FileSystem.DIRECTORY_MOVIES > Note: If you provide null or invalid values for the type, the API returns the main directory path of the primary shared or external storage. |
Example
var dirPath = voltmx.io.FileSystem.getExternalFilesDirs(voltmx.io.FileSystem.DIRECTORY_PICTURES);
Return Values
Array of Strings
Note: If the shared storage is not available, this API returns a
null
value.
Exceptions
None
Platform Availability
- Android
Note: If your device runs on Android versions before Android KitKat, the voltmx.io.FileSystem.getExternalFilesDirs API returns the same result as the voltmx.io.FileSystem.getExternalFilesDir API.
voltmx.io.FileSystem.getExternalStorageDirectoryPath
The getExternalStorageDirectoryPath API returns the path to the external storage, typically sdcard.
Syntax
voltmx.io.FileSystem.getExternalStorageDirectoryPath()
Input Parameters
None
Example
var mainLoc = voltmx.io.FileSystem.getExternalStorageDirectoryPath();
Return Values
String
Exceptions
None
Platform Availability
- Android
Note: If the targetSdk version used is above version 28, scoped storage is enabled by default, and the legacy Storage APIs (getExternalStorageDirectoryPath) will not work. You must use scoped Storage APIs such as getExternalFilesDir and getExternalFilesDirs on devices that run on Android version 11, and above.
voltmx.io.FileSystem.getExternalStorageState
The getExternalStorageState API returns the current state of the shared or external storage media at the specified path.
Syntax
voltmx.io.FileSystem.getExternalStorageState([path](#Path1));
Input Parameters
Parameters | Description |
---|---|
Path | Path to the file or directory. |
Example
var path = voltmx.io.FileSystem.getExternalFilesDir();
var stats = voltmx.io.FileSystem.getExternalStorageState(path);
Return Values
File System Constant
The File System Constant can have one of the following values:
voltmx.io.FileSystem.MEDIA_UNKNOWN
: Unknown storage state, such as when a path isn't backed by known storage media.
voltmx.io.FileSystem.MEDIA_REMOVED
: Storage state if the media is not present.
voltmx.io.FileSystem.MEDIA_UNMOUNTED
: Storage state if the media is present but not mounted.
voltmx.io.FileSystem.MEDIA_CHECKING
: Storage state if the media is present and the disk is being checked.
voltmx.io.FileSystem.MEDIA_NOFS
: Storage state if the media is present but is blank or is using an unsupported filesystem.
voltmx.io.FileSystem.MEDIA_MOUNTED
: Storage state if the media is present and mounted at its mount point with read/write access.
voltmx.io.FileSystem.MEDIA_MOUNTED_READ_ONLY
: Storage state if the media is present and mounted at its mount point with read/write access.
voltmx.io.FileSystem.MEDIA_SHARED
: Storage state if the media is present not mounted, and shared via USB mass storage.
voltmx.io.FileSystem.MEDIA_BAD_REMOVAL
: Storage state if the media was removed before it was unmounted.
voltmx.io.FileSystem.MEDIA_UNMOUNTABLE
: Storage state if the media is present but cannot be mounted. Typically, this happens if the file system on the media is corrupted.
voltmx.io.FileSystem.MEDIA_EJECTING
: Storage state if the media is in the process of being ejected.
Exceptions
None
Platform Availability
- Android
voltmx.io.FileSystem.getFile
The getFile API returns a voltmx.io.File object representing the file for the given path. It returns a voltmx.io.File object for the specified file path. getFile API does not create a File.
Syntax
voltmx.io.FileSystem.getFile(string path)