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)</