Utility Functions

Overview

Compression and Decompression

utils.zip Compress

• Compress multiple files into one zip file
• @param zipFile Path to the target zip file
• @param passwd Zip file password; empty means no password
• @param files Files or folders to compress as an array, e.g. ["/sdcard/a.txt","/sdcard/bb/"]
• @return {bool} true on success, false on failure

1
function main() {
2
    zipFile = "/sdcard/a.zip"
3
    // Compress files
4
    let passwd = "123";
5
    let files = ["D:/test.json", "D:/gifshow"]
6
    let re = utils.zip(zipFile, passwd, files);
7
    logd("compress result: " + re);
8

9
    let ure = utils.unzip(zipFile, passwd, "D:/test111/");
10
    logd("unzip result: " + ure);
11

12

13
    let data = utils.readFileInZip("D:/a.zip", passwd, "test.json")
14
    logd("read data result: " + data);
15
}
16

17
main()

utils.unzipWithEncode Unzip with Encoding

• Unzip files
• Extract a zip file into a folder
• Requires EC iOS 6.460+
• @param zipFile Path to the target zip file
• @param passwd Zip file password
• @param destDir Target folder to extract into
• @param fileNameEncode Filename encoding; use GBK for Windows-created zips, UTF-8 on other platforms
• @return {bool} true on success, false on failure

1
function main() {
2
    let zipFile = "C:/a.zip"
3
    let ure = utils.unzipWithEncode(zipFile, "", "/sdcard/test111/", "GBK");
4
    logd("unzip result: " + ure);
5
}
6

7
main()

utils.unzip Unzip

• Extract a zip file into a folder
• Requires EC 5.17.0+
• @param zipFile Path to the target zip file
• @param passwd Zip file password
• @param destDir Target folder to extract into
• @return {bool} true on success, false on failure

1
function main() {
2
    zipFile = "C:/a.zip"
3
    // Compress files
4
    let passwd = "123";
5
    let files = ["D:/test.json", "D:/gifshow"]
6
    let re = utils.zip(zipFile, passwd, files);
7
    logd("compress result: " + re);
8

9
    let ure = utils.unzip(zipFile, passwd, "D:/test111/");
10
    logd("unzip result: " + ure);
11

12

13
    let data = utils.readFileInZip("D:/a.zip", passwd, "test.json")
14
    logd("read data result: " + data);
15
}
16

17
main()

utils.readFileInZip Read from ZIP

• Read data from a zip file
• Requires EC 5.17.0+
• @param zipFile Path to the zip file
• @param passwd Zip file password
• @param filePathInZip Path of the file inside the zip, e.g. a/b.txt
• @return {string} Parsed string content

1
function main() {
2

3
    zipFile = "/sdcard/a.zip"
4
    // Compress files
5
    let passwd = "123";
6
    let files = ["D:/test.json", "D:/gifshow"]
7
    let re = utils.zip(zipFile, passwd, files);
8
    logd("compress result: " + re);
9

10
    let ure = utils.unzip(zipFile, passwd, "D:/test111/");
11
    logd("unzip result: " + ure);
12

13

14
    let data = utils.readFileInZip("D:/a.zip", passwd, "test.json")
15
    logd("read data result: " + data);
16
}
17

18
main()

utils.getRatio Get Ratio

• Get a ratio; e.g. parameter 10 returns a 10% probability. Returns true if the random ratio succeeds, false otherwise
• @param ratio Float from 1–100
• @return true or false

1
function main() {
2
    var ratio = utils.getRatio(20);
3
    logd(ratio);
4
}
5

6
main();

utils.getRangeInt Get Random Value in Range

• Get a random integer within a range
• @param min Minimum value
• @param max Maximum value
• @return Value between min and max, inclusive of both

1
function main() {
2
    var value = utils.getRangeInt(1, 100);
3
    logd(value);
4
}
5

6
main();

MD5

utils.fileMd5 File MD5

• Compute MD5 of a file
• @param file File path
• @return File MD5 string or null

1
function main() {
2
    var md5 = utils.fileMd5("D:/a.txt");
3
}
4

5
main();

utils.dataMd5 Data MD5

• Compute MD5 of data
• @param data Data string
• @return Data MD5 string or null

1
function main() {
2
    var md5 = utils.dataMd5("data");
3
}
4

5
main();

Random

utils.randomInt Random Integer

• Generate a random integer
• @param length Number of digits for the random integer
• @return Integer

1
function main() {
2
    var r = utils.randomInt(2);
3
}
4

5
main();

utils.randomCharNumber Random Alphanumeric String

• Get a random string of letters and digits
• @param length Length
• @return Mixed alphanumeric string

1
function main() {
2
    var r = utils.randomCharNumber(2);
3
}
4

5
main();

Audio

utils.playMp3 Play MP3

• Play an MP3 file
• Requires EC USB 7.16.0+
• @param path File path to an MP3 on the PC
• @param volume Volume level 0–100
• @param queue Queue mode; false = play immediately
• @param stopWhenScriptEnd Stop playback when the script ends
• @return boolean true on success, false on failure

1
function main() {
2
    // To bundle MP3 in the script, put the file in the res directory
3
    saveResToFile("a.mp3", "d:/a.mp3")
4
    let r = utils.playMp3("d:/a.mp3", 100, false, false);
5
    sleep(10000)
6
    utils.stopMp3();
7
}
8

9
main();

utils.stopMp3 Stop MP3 Playback

• Stop MP3 playback
• Requires EC USB 7.16.0+
• @return boolean true on success, false on failure

1
function main() {
2
    // To bundle MP3 in the script, put the file in the res directory
3
    saveResToFile("a.mp3", "d:/a.mp3")
4
    let r = utils.playMp3("d:/a.mp3", 100, false, false);
5
    sleep(10000)
6
    utils.stopMp3();
7
}
8

9
main();

Photo Library

utils.requestPhotoAuthorization Request Photo Library Permission

• Request photo library permission
• First request shows a permission dialog — allow it, or go to Settings → scroll to the bottom → EC app → enable Photos
• Note: These are async; ignore return values to avoid blocking simulated taps
• Requires EC 7.18.0+
• @return {bool} true on success, false on failure

1
function main() {
2
    let rx = utils.requestPhotoAuthorization()
3
    logd("r " + rx)
4
    // Then call delete functions
5
    let a = utils.deleteAllPhotos()
6
    logd("a " + a)
7

8
}
9

10
main();

utils.deleteAllPhotos Delete All Photos

• Delete all photos in the library
• A confirmation dialog appears — simulate tapping Delete
• Note: These are async; ignore return values to avoid blocking simulated taps
• Requires EC 7.18.0+
• @return {bool} true on success, false on failure

1
function main() {
2
    let rx = utils.requestPhotoAuthorization()
3
    logd("r " + rx)
4
    // Then call delete functions
5
    let a = utils.deleteAllPhotos()
6
    logd("a " + a)
7
}
8

9
main();

utils.deleteAllVideos Delete All Videos

• Delete all videos in the library
• A confirmation dialog appears — simulate tapping Delete
• Note: These are async; ignore return values to avoid blocking simulated taps
• Requires EC 7.18.0+
• @return {bool} true on success, false on failure

1
function main() {
2
    let rx = utils.requestPhotoAuthorization()
3
    logd("r " + rx)
4
    // Then call delete functions
5
    let a = utils.deleteAllVideos()
6
    logd("a " + a)
7
}
8

9
main();

Agent File Operations

utils.uploadAgentFile Upload File to Agent

• Upload a file to the agent runner storage directory
• @param filePath Local file path
• @param fileName Saved file name
• @return {string} Remote file path after upload

1
function main() {
2
  let recFilePath = utils.uploadAgentFile("/Volumes/dev/ch_PP-OCRv5_rec_mobile_infer.onnx", "rec.txt")
3
  logd("custom recFilePath " + recFilePath)
4
}
5

6
main();

utils.uploadToAutoImage Upload Image to Agent

• Upload an image to the remote agent and convert it to an AutoImage object
• The object lives on the device; use only imageAgent, ocrAgent, or yoloAgent modules to operate on it
• @param filePath File path
• @return {AutoImage|null}

1
function main() {
2
  let r = utils.uploadToAutoImage("/Volumes/aa.png")
3
  logd("AutoImage " + r)
4
}
5

6
main();

utils.deleteAgentFile Delete Agent Internal File

• Delete a file from agent IPA internal storage
• @param filePath File path
• @return {boolean} true on success

1
function main() {
2
  let recFilePath = utils.uploadAgentFile("/Volumes/dev/ch_PP-OCRv5_rec_mobile_infer.onnx", "rec.txt")
3
  let res = utils.deleteAgentFile(recFilePath)
4
  logd("delete result " + res)
5
}
6

7
main();

Other

utils.getPCIps Get PC IP Addresses

• Get this PC’s IP addresses; multiple addresses are comma-separated
• @return {null|string} IP address string

1
function main() {
2
    let ips = utils.getPCIps();
3
    if (_isEmpty(ips)) {
4
        logd("PC IP not found")
5
        return false;
6
    }
7
    logd("PC IP: {}", ips)
8
}
9

10
main();