Skip to content

voltmx.io.File Namespace

The voltmx.io.File namespace provides functions and properties for doing various operations related on files, such as copying them, renaming them , deleting them, and so on.

Overview

Your app can create a File object to represent files in the device's file system and perform common operations on them. To create a new File object , your app calls the voltmx.io.File function. Alternatively, it can use the voltmx.io.FileSystem.getFile function to get an instance of a File object.


var myfile = new voltmx.io.File("myfile.txt");  
or  
var myfile = voltmx.io.FileSystem.getFile("myfile.txt")
File Properties:Name Description
name: [type: String, ReadOnly] Name of the file or directory
fullPath: [type: String, ReadOnly] Full absolute path of the file or directory
parent: [type:voltmx.io.File, ReadOnly] Returns the parent directory of this file. This property may return nil or a File object which can neither Readable or Writable, especially in case of Folders which are not accessible by the given Application context
readable: [type: Boolean, ReadOnly] Returns true if this file is readable
writable: [type: Boolean, ReadOnly] Returns true if this file is writable
modificationTime: [type:Number, ReadOnly] Returns the last modification time of the file in UTC
size: [type:Number, ReadOnly Returns the size of a file in number of bytes.

The following function is often used in conjunction with the RawBytes object to read data of type RawBytes.

Functions

The voltmx.io.File namespace contains these functions: To use the copyTo, moveTo, remove, rename, createFile, createDirectory, read, and write File APIs, your app needs runtime permission from the end-user (to perform any of the action correspondent to a file). If you call any API without obtaining the permission, platforms automatically pops up a system permission dialog box with "Allow" and "Deny" options, asking the end-user to grant permission. This is applicable only for the Android platform.

If the end-user taps the "Allow" option, platform proceeds to access the underlying OS API. If the end-user taps the "Deny" option, the PermissionError exception is thrown with the 2300 error code, that means permission is denied.

voltmx.io.File.copyTo

copyTo API copies a file to the given destination path.

Syntax


voltmx.io.File.copyTo(String path, String newName)

Input Parameters

Parameter Description
Path path to the destination directory.
newName (optional) New name of the file/directory. Defaults to current name if unspecified.

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var copyToLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir1";
var newFile = new voltmx.io.File(origFileLoc).copyTo(copyToLoc, "NewNameForCopy.txt");

Return Values

VoltMX.io.File returns a handle to the File object pointing to the destination file, if successful. If failure, then returns null.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.createDirectory

The createDirectory API creates a directory on the file system represented by this file object.

Note:
    For Android below permissions are required in IRIS project setting -> Native-> Android Mobile/Tablet -> Tags (Child tag entries under < manifest > tag) depending on the target version
    If target version is 33 and above below media permissions are required.
  • < uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
    • If target version is 34 and above below permission must be added along with other media permissions.
  • < uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED"/>
    • For more information about Android 14 behavioral change click here, also for understanding other media permissions please refer Android 13.

Syntax


voltmx.io.File.createDirectory()

Input Parameters

None

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var dirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir1";
var myDir = new voltmx.io.File(dirLoc).createDirectory();

Return Values

Boolean – true if the creation of directory is successful. False if directory already exists or could not be created.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.createFile

The createFile API creates a file on the file system represented by this file object.

Syntax


voltmx.io.File.createFile()

Input Parameters

None

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var fileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToCopy.txt";
var myFile = new voltmx.io.File(fileLoc).createFile();

Return Values

Boolean – true if the creation of file is successful. False if file already exists or could not be created.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.exists

The exist API checks, if the file or directory exists on the file system represented by this file object.

Syntax


voltmx.io.File.exists()

Input Parameters

None

Example


var copiedFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR +
    "myDir1" + constants.FILE_PATH_SEPARATOR +
    "NewNameForCopy.txt";
if (new voltmx.io.File(copiedFileLoc).exists()) {
    voltmx.print("copy of file was successful");
} else {
    voltmx.print("copy of file failed");
}

Return Values

Boolean – true if the file or directory exists on file system.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.getFilesList

The getFilesList API returns voltmx.io.FileList object representing the files and directories available under this file object directory.

Note:
    For Android below permissions are required in IRIS project setting -> Native-> Android Mobile/Tablet -> Tags (Child tag entries under < manifest > tag) depending on the target version
    If target version is 33 and above below media permissions are required.
  • < uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
    • If target version is 34 and above below permission must be added along with other media permissions.
  • < uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED"/>
    • For more information about Android 14 behavioral change click here, also for understanding other media permissions please refer Android 13.

Syntax


voltmx.io.File.getFilesList()

Input Parameters

None

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var myDirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir416";
var myDirName = new voltmx.io.File(myDirLoc);
var createDir = myDirName.createDirectory();
var fileListLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir416";
var filesList = new voltmx.io.File(fileListLoc).getFilesList();
if (filesList.length === 0) {
    voltmx.print("getFilesList successful for zero files");
} else {
    voltmx.print("getFilesList failed for zero files");
}

Return Values

voltmx.io.FileList – FileList object or null if this File is not identified as a directory.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.isDirectory

The isDirectory API checks, if this object represents a directory file on the file system.

Syntax


voltmx.io.File.isDirectory()

Input Parameters

None

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var dirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir765";
var myDir = new voltmx.io.File(dirLoc);
try {
    var isDirec = new voltmx.io.File(dirLoc).isDirectory();
    if (isDirec) {
        voltmx.print("isDirectory True for nonExistent Directory");
    }
} catch (err) {
    voltmx.print("isDirec doesn't work over nonExistent directory");
}

Return Values

Boolean – true, if this file object represents a directory, false otherwise.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.isFile

The isFile API checks, if this object represents a typical file on the file system but not a directory.

Syntax


voltmx.io.File.isFile()

Input Parameters

None

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFile244.txt";
var myFileName = new voltmx.io.File(myFileLoc);
try {
    var isFileThere = new voltmx.io.File(myFileLoc).isFile();
    if (isFileThere) {
        voltmx.print("isFile true for nonExistent File");
    } else {
        voltmx.print("isFile false for nonExistent File");
    }
} catch (err) {
    voltmx.print("isFile doesn't work on non-existent files");
}

Return Values

Boolean – true if this file object represents a file, false otherwise.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.moveTo

The moveTo API moves a file to the given destination path.

Syntax


voltmx.io.File.moveTo(String path, String newname)

Input Parameters

Parameter Description
Path path to the destination directory.
newName (optional) New name of the file/directory. Defaults to current name, if unspecified.

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var dirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir25";
var myDir = new voltmx.io.File(dirLoc).createDirectory();
var fileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToMove25.txt";
var myFile = new voltmx.io.File(fileLoc).createFile();
var newFile = new voltmx.io.File(fileLoc).moveTo(mainLoc);
if (newFile !== null) {
    voltmx.print("moving to same loc with same name was successful");
} else {
    voltmx.print(" can't move to same loc with same name");
}

Return Values

VoltMX.io.File – returns a handle to File object pointing to destination file on success. Returns null on failure.

Exceptions

None

Platform Availability

Available to iOS, Android, and Windows platforms.

voltmx.io.File.read

The read API returns the voltmx.types.RawBytes of this file.

Syntax


voltmx.io.File.read()

Input Parameters

None

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFile313.txt";
var myFileName = new voltmx.io.File(myFileLoc);
try {
    var reading = new voltmx.io.File(myFileLoc).read();
    voltmx.print(reading);
    if (reading === null) {
        voltmx.print("null is coming from reading i.e can't be done");
    } else {
        voltmx.print("reading can be done on NonExistentFile");
    }
} catch (err) {
    voltmx.print("can't try read on nonExistent File causes Error");
}

Return Values

voltmx.types.RawBytes – rawbytes representing the content of the file.Returns null in case of non existent file.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

Note: RawBytes will hold a handle of File object that it represents. The file content is not actually loaded into memory.

voltmx.io.File.remove

The remove API deletes a file or a directory.

Note:
    For Android below permissions are required in IRIS project setting -> Native-> Android Mobile/Tablet -> Tags (Child tag entries under < manifest > tag) depending on the target version
    If target version is 33 and above below media permissions are required.
  • < uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
    • If target version is 34 and above below permission must be added along with other media permissions.
  • < uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED"/>
    • For more information about Android 14 behavioral change click here, also for understanding other media permissions please refer Android 13.

Syntax


remove(boolean, deleteRecursive)

Input Parameters

Parameter Description
boolean By default, this is false.True - deletes the folder and all its content recursively.False - if the directory is empty it shall be removed.
deleteRecursive (optional) Ignored in case of a file.

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToMove12.txt";
var myFile = new voltmx.io.File(myFileLoc);
myFile.createFile();
myFile.remove(true);
if (new voltmx.io.File(myFileLoc).exists()) {
    voltmx.print("removing file failed");
} else {
    voltmx.print("removing file was successful");
}

Return Values

None

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.rename

The rename API renames a file or a directory.

Note:
    For Android below permissions are required in IRIS project setting -> Native-> Android Mobile/Tablet -> Tags (Child tag entries under < manifest > tag) depending on the target version
    If target version is 33 and above below media permissions are required.
  • < uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
  • < uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
    • If target version is 34 and above below permission must be added along with other media permissions.
  • < uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED"/>
    • For more information about Android 14 behavioral change click here, also for understanding other media permissions please refer Android 13.

Syntax


voltmx.io.File.rename(String newname)

Input Parameters

Parameter Description
newname new name for a file or a directory.

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToReName7578.txt";
var myFile = new voltmx.io.File(myFileLoc).createFile();
var newFile = new voltmx.io.File(myFileLoc).rename("myFileToReName7577");
if (newFile) {
    voltmx.print("renaming file with name successfull with extension");
} else {
    voltmx.print("renaming file failed for name without Extension");
}

Return Values

Boolean – If successful, then boolean value is true,. Boolean value is false, if invalid file name or if the destination is a different directory than the current file.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

voltmx.io.File.write

The write API writes the given content into the file.

Syntax


voltmx.io.File.write(rawbytes/string, append)

Input Parameters

Parameter Description
Rawbytes/string data to write of type text string or voltmx.types.RawBytes
Append (optional) true to append the data. Default is false, that means overrides the content.

Example


var mainLoc = voltmx.io.FileSystem.getDataDirectoryPath();
var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFile376.txt";
var myFileName = new voltmx.io.File(myFileLoc).createFile();
try {
    var writing = new voltmx.io.File(myFileLoc).write("How are you?");
    if (writing !== null) {
        voltmx.print("writing can be done on Non Existing Files");
    } else {
        voltmx.print("writing on nonExisting file returns null");
    }
} catch (err) {
    voltmx.print("can't try write on NonExistingFile, causes Error");
}

Return Values

Boolean – true if success, false otherwise.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.