file - sigma-rt

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.

Methods

(static) 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:

Name	Type	Description
`oldFilePath`	string	The path to the source file on the phone. (e.g., "/sdcard/test.txt").
`newFilePath`	string	The path to the destination file on the phone.
`overlay`	boolean	When the file exists in the destination folder, whether to overwrite the file, true is overwritten, false is not overwritten.

Returns:

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

Type: number

(static) 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:

Name	Type	Description
`filePath`	string	The path to a file or folder on your phone. (e.g., "/sdcard/test/test.txt").

Returns:

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

Type: number

(static) 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:

Name	Type	Attributes	Description
`from`	string		The file on the phone that needs to be downloaded. (e.g., "/sdcard/aa/test2.txt").
`to`	string		Target folder (folder in the computer). (e.g., "E:/File"). Must be a valid writable path.
`timeOut`	number	<optional>	Optional parameters, timeout (ms), default 60 seconds.

Returns:

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

Type: number

(static) 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:

Name	Type	Description
`oldFilePath`	string	The path to the source file on the phone. (e.g., "/sdcard/test.txt").
`newFilePath`	string	The path to the destination file on the phone. (e.g., "/sdcard/aa/123.txt").
`overlay`	boolean	Whether to overwrite the destination file if it already exists.

Returns:

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

Type: number

(static) 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:

Name	Type	Description
`filePath`	string	The full path of the file to read (e.g., "/sdcard/aa/test3.txt").

Returns:

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.

Type: number | null

(static) 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:

Name	Type	Description
`oldFilePath`	string	The path to the source file on the phone. (e.g., "/sdcard/aa/test2.txt").
`newFilePath`	string	The path to the destination file on the phone. (e.g., "/sdcard/aa/test3.txt").

Returns:

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

Type: number

(static) 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:

Name	Type	Description
`filePath`	string	Delete the folder. (e.g., "/sdcard/test/").

Returns:

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

Type: number

(static) 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:

Name	Type	Description
`filePath`	string	The file on the phone. (e.g., "/sdcard/aa/test3.txt").

Returns:

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

Type: number

(static) 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:

Name	Type	Attributes	Description
`from`	string		The file on the phone that needs to be downloaded. (e.g., "E:\File\testupload.txt").
`to`	string		Target folder (folder in the computer). (e.g., "/sdcard/aa/").
`timeOut`	number	<optional>	Optional parameters, timeout (ms), default 60 seconds.

Returns:

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

Type: number

(static) 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:

Name	Type	Attributes	Description
`filePath`	string		The file path on the phone. (e.g., "/sdcard/aa/test.txt").
`content`	string		Text content.
`offset`	number	<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.
`type`	number	<optional>	Optional parameters, Append mode, the default is 1. 0: Append the content after the line break; 1: Add content directly;

Returns:

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

Type: number