mobicontrol.io.ZipFile(pathName)

This class represents a Zip file.

new ZipFile(pathName)

Construct an instance of the ZipFile class.

Note: The construction of a ZipFile class instance doesn't create the corresponding zip file on the disk.

Parameters:
Name Type Description
pathName string The file path.
Since:

Extends

Members

readonly, nullable exists :boolean

true if the file exists.

This property is false if the file doesn't exist, and is null if the file existence cannot be determined.

Since:
Inherited From:

readonly, nullable isDirectory :boolean

true if the file is a directory.

This property is false if this file doesn't exist or isn't a directory, and is null if it cannot be determined whether this file exists or whether it is a directory.

Since:
Inherited From:
Example
var dir = new mobicontrol.io.File('/sdcard');
if (dir.isDirectory) {
    mobicontrol.log.info('Directory: ' + dir.path);
} else {
    mobicontrol.log.info('Not a directory: ' + dir.path);
}

readonly, nullable isNormalFile :boolean

true if the file is a normal file.

This property is false if this file doesn't exist or isn't a normal file, and is null if it cannot be determined whether this file exists or whether it is a normal file.
A file is considered "normal" if it is not a directory.

Since:
Inherited From:

readonly, nullable isReadable :boolean

true if the agent can read the file.

This property is false if this file doesn't exist or the agent cannot read it, and is null if it cannot be determined whether this file exists or whether the agent can read it.

Since:
Inherited From:
Example
var file = new mobicontrol.io.File('/sdcard/some_file.txt');
if (file.isReadable) {
    mobicontrol.log.info('File is readable!');
} else {
    mobicontrol.log.info('File is not readable!');
}

readonly, nullable isWritable :boolean

true if the agent can write into the file.

This property is false if this file doesn't exist or the agent cannot write into it, and is null if it cannot be determined whether this file exists or whether the agent can write into it.

Since:
Inherited From:

readonly, nullable lastModified :Date

Last modification date.

The date this file was last modified.
This property is null if this file doesn't exist or if its last modification date cannot be determined.

Since:
Inherited From:
Example
purgeOldFiles('sdcard/dirToPurge');

// Purge directory of any files which were not touched in the last 30 days
function purgeOldFiles(dirPath) {
     var dir = new mobicontrol.io.File(dirPath);
     var today = new Date();
     var oldestDate = new Date(today.setDate(today.getDate() - 30));

     dir.listFiles().forEach(file => {
         if (file.lastModified < oldestDate) {
             file.delete();
         }
     });
}

readonly path :string

File path.

The path of this file; for example, "/sdcard/package/app.apk".

Since:
Inherited From:

readonly, nullable size :number

The size of the file in bytes.

This property is null if this file is not a normal file, doesn't exist, or isn't accessible.

Since:
Inherited From:
Example
var file = new mobicontrol.io.File('/sdcard/example.txt');
mobicontrol.log.info('File size: ' + file.size);

Methods

contentEquals(file) → nullable {boolean}

Compare the contents of two files.

Compare the content of this file with the content of a file provided in a parameter. The contents of two non-existent files are considered to be different. Directories are compared recursively.

Parameters:
Name Type Description
file mobicontrol.io.File A file to compare this file with.
Returns:
boolean - true if the contents of two files are identical, false if not, and null if it cannot be determined whether the contents of two files are identical.
Since:
Inherited From:
Example
var file1 = new mobicontrol.io.File('/sdcard/one_file.txt');
var file2 = new mobicontrol.io.File('/sdcard/another_file.txt');
var isEqual = file1.contentEquals(file2);
mobicontrol.log.info('Content equals: ' + isEqual);

copyTo(destination)

Copy the file.

Copy this file to the provided destination. If this file is a directory, copy the directory content recursively.

Parameters:
Name Type Description
destination mobicontrol.io.File The destination file path.
Throws:
mobicontrol.io.IoError
Since:
Inherited From:
Example
var source = new mobicontrol.io.File('/sdcard/image.png');
var destination = new mobicontrol.io.File('/sdcard/copied_image.png');
source.copyTo(destination);

createDirectory() → {boolean}

Create the directory.

Create an empty directory named by this path if this directory does not exist yet.
If a file with this path already exists:

Throws:
mobicontrol.io.IoError
Returns:
boolean - true if this directory had not existed and was successfully created, false if this directory already existed.
Since:
Inherited From:
Example
new mobicontrol.io.File('/exampleDir').createDirectory();

createFile() → {boolean}

Create the file.

Create a normal empty file named by this path if this file does not exist yet.
If a file with this path already exists:

Throws:
mobicontrol.io.IoError
Returns:
boolean - true if this normal file had not existed and was successfully created, false if this normal file already existed.
Since:
Inherited From:
Example
new mobicontrol.io.File('/example_file.txt').createFile();

delete() → {boolean}

Delete the file.

Delete this file. If the file is a directory, this directory must be empty to be deleted.

Returns:
boolean - true if this file was deleted, false otherwise.
Since:
Inherited From:
Example
var file = new mobicontrol.io.File('/sdcard/example_file.txt');
var fileWasDeleted = file.delete();
mobicontrol.log.info(fileWasDeleted);

listFiles() → {Array.<mobicontrol.io.File>}

List files in the directory.

Return an array of files this directory contains. The files in the array appear in no specific order.
If this file is not a directory, throw mobicontrol.io.IoError.

Throws:
mobicontrol.io.IoError
Returns:
Array.<mobicontrol.io.File> - An array of files contained by this directory.
Since:
Inherited From:
Example
var dir = new mobicontrol.io.File('/sdcard/some_directory');
var files = dir.listFiles();
var concatenatedFilePaths = '';
files.forEach(concatenateFilePath);
mobicontrol.log.info(concatenatedFilePaths);

function concatenateFilePath(value, index, array) {
    concatenatedFilePaths += value.path + ' ';
}

readText() → {string}

Read text from the file.

Read content of the text file. If this is not a UTF-8 text file, or if the file size exceeds 2MB, throw mobicontrol.io.IoError.

Throws:
mobicontrol.io.IoError
Returns:
string - The content of the text file.
Since:
Inherited From:
Example
var file = new mobicontrol.io.File('/sdcard/some_file.txt');
var text = file.readText();
mobicontrol.log.info(text);

renameTo(destination)

Rename the file.
Parameters:
Name Type Description
destination mobicontrol.io.File The destination file path. File with this path should not exist.
Throws:
mobicontrol.io.IoError
Since:
Inherited From:
Example
var source = new mobicontrol.io.File('/sdcard/image.png');
var destination = new mobicontrol.io.File('/sdcard/renamed_image.png');
source.renameTo(destination);

async unzip(destination, callbackFunctionopt, invocationTimeoutInMillisopt)

Extract this ZIP archive to the specified destination.

Parameters:
Name Type Attributes Default Description
destination mobicontrol.io.File The folder where the content of this ZIP file will be extracted into.
callbackFunction mobicontrol.io.ZipFile.unzipCallback <optional>
 JavaScript function which is called when the unzipping completes.
invocationTimeoutInMillis number <optional>
 10000 Invocation timeout in milliseconds. If the callback function isn't invoked before the timeout expires, it will be called with the timed-out result.
Since:
Example
var internalDataDirectory = mobicontrol.storage.internal.dataDirectory;

var zipFile = new mobicontrol.io.ZipFile(internalDataDirectory + "/some_file.zip");
var targetFolder = new mobicontrol.io.File(internalDataDirectory + "/folder");
zipFile.unzip(targetFolder, onUnzipComplete);

function onUnzipComplete(result) {
    if (result.isSuccessful) {
        var targetSubfolder = new mobicontrol.io.File(internalDataDirectory + "/folder");
        mobicontrol.log.info(
            "Unzip of " + result.zipFile.path + " finished; " +
            "Number of files in " + targetSubfolder.path + " is " + targetSubfolder.listFiles().length
         );
     }
}

writeContent(uri)

Write the content from the specified URI to the file.

Replace the content of this file with the content from the specified URI. If this file does not exist, create it. The URI should have one of the following schemes:

  • content
  • file
  • android.resource
Parameters:
Name Type Description
uri mobicontrol.android.Uri The URI whose content to write to this file.
Throws:
mobicontrol.io.IoError
Since:
Inherited From:
Example
var file = new mobicontrol.io.File('/sdcard/some_file.txt');
var contentUri = mobicontrol.android.createUri('content://com.example/document/example.txt');
file.writeContent(contentUri);

writeText(text)

Write the text to the file.

Replace the content of this file with the provided text. If this file does not exist, create it.

Parameters:
Name Type Description
text string The text to write to this file.
Throws:
mobicontrol.io.IoError
Since:
Inherited From:
Example
var file = new mobicontrol.io.File('/sdcard/some_file.txt');
file.writeText('Lorem ipsum dolor sit amet, consectetur adipiscing elit...');

async zip(files, callbackFunctionopt, invocationTimeoutInMillisopt)

Create or append to an existing ZIP archive from the specified list of files.

Parameters:
Name Type Attributes Default Description
files Array.<mobicontrol.io.File> A list of files to be zipped. If any of the files is a directory - its content is zipped recursively.

If the target ZIP archive doesn't exist - it is created, otherwise the files are appended to the existing ZIP archive.
callbackFunction mobicontrol.io.ZipFile.zipCallback <optional>
 JavaScript function which is called when the zipping completes.
invocationTimeoutInMillis number <optional>
 10000 Invocation timeout in milliseconds. If the callback function isn't invoked before the timeout expires, it will be called with the timed-out result.
Since:
Example
var internalDataDirectory = mobicontrol.storage.internal.dataDirectory;
var zipFile = new mobicontrol.io.ZipFile(internalDataDirectory + "/some_file.zip");
zipFile.zip([
        new mobicontrol.io.File(internalDataDirectory + "/file1.txt"),
        new mobicontrol.io.File(internalDataDirectory + "/folder")
    ],
    onZipComplete
);

function onZipComplete(result) {
    if (result.isSuccessful) {
        mobicontrol.log.info(
            "Zip finished; " +
            "The size of " + result.zipFile.path + " is " + result.zipFile.size + " bytes"
        );
    }
}

Type Definitions

unzipCallback(result)

Callback function for mobicontrol.io.ZipFile.unzip.
Parameters:
Name Type Description
result object Result of the ZIP archive extraction.
Properties
Name Type Description
zipFile mobicontrol.io.ZipFile The file that is being zipped.
error mobicontrol.io.IoError Detailed error conditions in case of failure.

This value is null when the callback is successful or when there is a timeout.
isSuccessful boolean Success status of the callback.

true if the callback completed successfully, false otherwise.
isTimedOut boolean Timeout status of the callback.

true if the callback was timed out, false otherwise.

Note: A timeout is considered a failure, so if the timeout status is true, failure status is true as well, and success status is false.
isFailed boolean Failure status of the callback.

true if the callback failed, false otherwise.
Since:

zipCallback(result)

Callback function for mobicontrol.io.ZipFile.zip.
Parameters:
Name Type Description
result object Result of the ZIP archive creation.
Properties
Name Type Description
zipFile mobicontrol.io.ZipFile The file that is being zipped.
error mobicontrol.io.IoError Detailed error conditions in case of failure.

This value is null when the callback is successful or when there is a timeout.
isSuccessful boolean Success status of the callback.

true if the callback completed successfully, false otherwise.
isTimedOut boolean Timeout status of the callback.

true if the callback was timed out, false otherwise.

Note: A timeout is considered a failure, so if the timeout status is true, failure status is true as well, and success status is false.
isFailed boolean Failure status of the callback.

true if the callback failed, false otherwise.
Since: