file

Device file management module for Android devices in the Total Control scripting system.

This module provides a high-level file I/O interface for managing files and folders
on connected Android devices, as well as transferring files between the device and
the host computer. All functions are exposed as Java-layer extensions to the
Device object so they can be invoked via device.cpFile(), device.readFile(),
etc.

Features

  • Copy and move files with optional overwrite
  • Rename files or relocate them atomically
  • Check whether a file or directory exists on the device
  • Read text content from a file
  • Write/append text to a file with optional offset and append mode
  • Delete files and remove directories
  • Upload files from PC → device and download files from device → PC with timeout control

Usage Example

const { Device } = require("sigma/device");
const file = require("sigma/file"); // methods are attached to Device.prototype

const device = Device.getMain();

// Copy a file and rename it
let ret = device.cpFile("/sdcard/test.txt", "/sdcard/aa/test2.txt", true);
if (ret === 0) print("Copy OK");

// Write then read a file
ret = device.writeFile("/sdcard/aa/hello.txt", "Hello, Amy!");
if (ret === 0) {
  const text = device.readFile("/sdcard/aa/hello.txt");
  print("Content: " + text);
}

// Download to PC
ret = device.download("/sdcard/aa/hello.txt", "E:/File", 60000);
if (ret !== 0) print("Download failed: " + lastError());

Integration

  • Methods are automatically bound to Device.prototype and DeviceArray.prototype
    via attachMethodJavaFn.
  • Exported API names:
    cpFile, doesExist, download, mvFile, readFile,
    renameFile, rmDir, rmFile, upload, writeFile.

(inner) cpFile(oldFilePath, newFilePath, overlay) → {number}

Copy the file. copy a file from oldFilePath to newFilePath.

Example
// Example 1: Copy and rename the file
// Copy the file test.txt to /sdcard/aa/ and rename it to test2.txt
const { cpFile } = require("sigma/file");
device = Device.getMain();
const ret = device.cpFile("/sdcard/test.txt", "/sdcard/aa/test2.txt", true);
if (ret != 0) {
    print(lastError());
} else {
    print("copy file successfully!");
}


// Example 2: Copy the file without renaming
// Copy the file test.txt to /sdcard/aa/test.txt (same name)
const { cpFile } = require("sigma/file");
device = Device.getMain();
const ret = device.cpFile("/sdcard/test.txt", "/sdcard/aa/test.txt", true);
if (ret != 0) {
    print(lastError());
} else {
    print("copy file successfully!");
}

// Operation Result:
// If it executes successfully, it will print:
"copy file successfully!"
Parameters:
string oldFilePath

The path to the source file on the phone. (e.g., "/sdcard/test.txt").
string newFilePath

The path to the destination file on the phone.
boolean overlay

When the file exists in the destination folder, whether to overwrite the file, true is overwritten, false is not overwritten.
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) doesExist(filePath) → {number}

Determines if the specified file or folder exists.

Example
const { doesExist } = require("sigma/file");
// Check if the file or directory exists
device = Device.getMain();
const ret = device.doesExist("/sdcard/test/test.txt");
if (ret != 0) {
    print("File or directory does not exist: " + lastError());
} else {
    print("File or directory exist");
}

// Operation Result:
// If it executes successfully and the file exists, it will print:
"File or directory exist"
Parameters:
string filePath

The path to a file or folder on your phone. (e.g., "/sdcard/test/test.txt").
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) download(from, to, timeOutopt) → {number}

Download the files from your phone to your computer.

Example
const { doesExist } = require("sigma/file");
// Download a file from the device to the PC
device = Device.getMain();
if (device != null) {
    const ret = device.download("/sdcard/aa/test2.txt", "E:/File");
    if (ret == 0) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

// Operation Result:
// If it executes successfully, it will print:
Congratulations, this API executes successfully.
Return value: 0
Parameters:
string from

The file on the phone that needs to be downloaded. (e.g., "/sdcard/aa/test2.txt").
string to

Target folder (folder in the computer). (e.g., "E:/File"). Must be a valid writable path.
number timeOut <optional>

Optional parameters, timeout (ms), default 60 seconds.
Returns:
number

Returns 0 if successful; otherwise, returns a non-zero error code. Use lastError() to get the detailed error message.

(inner) mvFile(oldFilePath, newFilePath, overlay) → {number}

Move files on your phone, move files from one directory to another, or move files from one directory to another and rename them.

Example
const { mvFile } = require("sigma/file");
// Move and rename a file
device = Device.getMain();
var ret = device.mvFile("/sdcard/test.txt", "/sdcard/aa/123.txt", true);
if (ret != 0) {
    print(lastError());
} else {
    print("File moved successfully!");
}

// Operation Result:
// If it executes successfully, it will print:
File moved successfully!
Parameters:
string oldFilePath

The path to the source file on the phone. (e.g., "/sdcard/test.txt").
string newFilePath

The path to the destination file on the phone. (e.g., "/sdcard/aa/123.txt").
boolean overlay

Whether to overwrite the destination file if it already exists.
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) readFile(filePath) → {number|null}

Read the contents of the specified file.

Example
const { readFile } = require("sigma/file");
// Read content from a file on the device
device = Device.getMain();
if (device != null) {
    const ret = device.readFile("/sdcard/aa/test3.txt");
    if (ret != null) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

// Operation Result:
// If it executes successfully and the file contains "Hello, Amy!", it will print:
Congratulations, this API executes successfully.
Return value: Hello, Amy!
Parameters:
string filePath

The full path of the file to read (e.g., "/sdcard/aa/test3.txt").
Returns:
number | null

This function returns the contents of the specified file on success or null on failure. Specific error information can be obtained by the lastError() function.

(inner) renameFile(oldFilePath, newFilePath) → {number}

Rename a file or move it to a new path on the device.

Example
const { renameFile } = require("sigma/file");
// Rename a file from test2.txt to test3.txt
device = Device.getMain();
if (device != null) {
    const ret = device.renameFile("/sdcard/aa/test2.txt", "/sdcard/aa/test3.txt");
    if (ret == 0) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

// Operation Result:
// If it executes successfully, it will print:
Congratulations, this API executes successfully.
Return value: 0
Parameters:
string oldFilePath

The path to the source file on the phone. (e.g., "/sdcard/aa/test2.txt").
string newFilePath

The path to the destination file on the phone. (e.g., "/sdcard/aa/test3.txt").
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) rmDir(filePath) → {number}

Delete the folder.

Example
const { rmDir } = require("sigma/file");
// Delete a directory on the device
device = Device.getMain();
if (device != null) {
    const ret = device.rmDir("/sdcard/test/");
    if (ret == 0) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

// Operation Result:
// If it executes successfully, it will print:
Congratulations, this API executes successfully.
Return value: 0
Parameters:
string filePath

Delete the folder. (e.g., "/sdcard/test/").
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) rmFile(filePath) → {number}

Delete the file.

Example
const { rmFile } = require("sigma/file");
// Delete a file from the device
var device = Device.getMain();
var ret = device.rmFile("/sdcard/aa/test3.txt");
if (ret == 0) {
    print("Successfully delete the specified file");
} else {
    print(lastError());
}

// Operation Result:
// If it executes successfully, it will print:
Successfully delete the specified file
Parameters:
string filePath

The file on the phone. (e.g., "/sdcard/aa/test3.txt").
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) upload(from, to, timeOutopt) → {number}

Upload a file from the PC to the device.

Example
const { upload } = require("sigma/file");
// Upload a file from PC to the device
device = Device.getMain();
if (device != null) {
    const ret = device.upload("E:\\File\\testupload.txt", "/sdcard/aa/", 5000);
    if (ret == 0) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

// Operation Result:
// If it executes successfully, it will print:
Congratulations, this API executes successfully.
Return value: 0
Parameters:
string from

The file on the phone that needs to be downloaded. (e.g., "E:\File\testupload.txt").
string to

Target folder (folder in the computer). (e.g., "/sdcard/aa/").
number timeOut <optional>

Optional parameters, timeout (ms), default 60 seconds.
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) writeFile(filePath, content, offsetopt, typeopt) → {number}

Write text content to the specified file.

Example
// Example 1: Write content to a file (overwrite mode by default)
const { writeFile } = require("sigma/file");
device = Device.getMain();
if (device != null) {
    const ret = device.writeFile("/sdcard/aa/test.txt", "1. Hi, Amy!");
    if (ret == 0) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}


// Example 2: Write content at specific offset with overwrite mode
const { writeFile } = require("sigma/file");
device = Device.getMain();
if (device != null) {
    const ret = device.writeFile("/sdcard/aa/test.txt", "1. Hi, Amy!", 9, 0);
    if (ret == 0) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

// Operation Result:
// If it executes successfully, it will print:
Congratulations, this API executes successfully.
Return value: 0
Parameters:
string filePath

The file path on the phone. (e.g., "/sdcard/aa/test.txt").
string content

Text content.
number offset <optional>

Optional parameters, offset, relative to the end of the file offset. The default is 0, which means appending content at the end of the original file.
number type <optional>

Optional parameters, Append mode, the default is 1.

  • 0: Append the content after the line break;
  • 1: Add content directly;
Returns:
number

This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.