
-- XXT 主路径
XXT_HOME_PATH = "<XXT_HOME_PATH>"

-- XXT 执行文件根路径
XXT_SYSTEM_PATH = "<XXT_SYSTEM_PATH>"

-- XXT 服务程序路径
XXT_EXE_PATH = XXT_SYSTEM_PATH .. "/<XXT_EXE_NAME>"

-- XXT 资源路径
XXT_RES_PATH = XXT_HOME_PATH .. "/res"

-- XXT Lua 模块路径
XXT_LUA_PATH = XXT_HOME_PATH .. "/lua"

-- XXT 脚本路径
XXT_SCRIPTS_PATH = XXT_HOME_PATH .. "/lua/scripts"

-- XXT C 库路径
XXT_LIB_PATH = XXT_LUA_PATH .. "/lib"

-- XXT 日志路径
XXT_LOG_PATH = XXT_HOME_PATH .. "/log"

-- XXT 额外守护脚本路径
XXT_DAEMONS_PATH = XXT_HOME_PATH .. "/daemons"

-- XXT Tesseract 语言数据路径
XXT_TESSDATA_PATH = XXT_HOME_PATH.."/tessdata"

-- XXT 模型数据路径
XXT_MODELS_PATH = XXT_HOME_PATH.."/models"

-- XXT 是否为 TrollStore 版本
IS_TROLLSTORE_EDITION = "<IS_TROLLSTORE_EDITION>"

--- 输出日志到开发工具
--- @param argA any
--- @param argB any
---
---[查看文档](https://xxtouch.app/docs/handbook/develop-helper/nLog)
---
function nLog(argA, argB, ...) end

--------------------------------------------------------------------------------
-- 开发辅助模块
--------------------------------------------------------------------------------

--- 获取当前脚本已执行的毫秒数
---@return integer elapsedMs 已执行毫秒数
---
---[查看文档](https://xxtouch.app/docs/handbook/develop-helper/get_elapsed_ms)
---
function get_elapsed_ms() end

--- 获取系统根路径对应的越狱根路径
---@param systemPath? string 系统根路径
---@return string jailbreakPath 越狱根路径
---
---[查看文档](https://xxtouch.app/docs/handbook/develop-helper/jbroot)
---
function jbroot(systemPath) end

--- 获取越狱根路径对应的系统根路径
---@param jailbreakPath? string 越狱根路径
---@return string systemPath 系统根路径
---
---[查看文档](https://xxtouch.app/docs/handbook/develop-helper/rootfs)
---
function rootfs(jailbreakPath) end

---@class print*
---@field out fun():string 缓冲区内容
print = {}

--- 打印内容到缓冲区
---@param ... any 可变参数
---
---[查看文档](https://xxtouch.app/docs/handbook/develop-helper/print)
---
function print(...) end

--- 将打印缓冲区的内容提出来
---@return string buffer 缓冲区内容
---
---[查看文档](https://xxtouch.app/docs/handbook/develop-helper/print.out)
---
function print.out() end

--- 创建一个进程执行 Lua 代码，阻塞当前 thread
---@param luacode string 需要执行的 Lua 代码，这个环境没有 thread 模块可用
---@param timeout_ms? integer 超时毫秒数，默认 0 表示运行没有限制
---@return string? 标准输出内容
---@return boolean? 是否执行成功（结束状态为 0）
---@return string? 结束状态文本描述
---@return integer? 结束状态代码
---@return string? 标准错误内容
function fork_dostring(luacode, timeout_ms) end

--------------------------------------------------------------------------------
-- 控制流程模块
--------------------------------------------------------------------------------

--- 注册脚本退出时执行的回调
--- 使用相同的 `name` 会覆盖已注册的回调；`callback` 传入 nil 表示取消注册
--- 该函数自 2025-07-05 版本起提供
---@param name string 回调标识
---@param callback? function 在脚本退出时执行的函数
---@return function? originalCallback 之前已注册的同名回调
---
---[查看文档](https://xxtouch.app/docs/handbook/control-flow/register_atexit)
---
function register_atexit(name, callback) end

os = os or {}

--- 重启当前脚本或跳转到指定脚本文件
--- 当传入脚本路径时可能返回错误；若调用成功则函数不会返回
---@param scriptPath? string 脚本文件路径
---@return boolean? ok 操作成败（仅在失败或传入路径时返回）
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/control-flow/os.restart)
---
function os.restart(scriptPath) end

--------------------------------------------------------------------------------
-- 模拟加速计模块
--------------------------------------------------------------------------------

---@class accelerometer*
accelerometer = {}

--- 模拟摇一摇
function accelerometer.shake() end

--- 重力方向向上
function accelerometer.rotate_home_on_top() end

--- 重力方向向左
function accelerometer.rotate_home_on_left() end

--- 重力方向向下
function accelerometer.rotate_home_on_bottom() end

--- 重力方向向右
function accelerometer.rotate_home_on_right() end


--------------------------------------------------------------------------------
-- 应用程序模块
--------------------------------------------------------------------------------

---@class app*
app = {}

---@alias app_permission_operation "get"|"set"|"reset"

---@class app_notification_permissions_info*
---@field allowsNotifications? boolean 是否允许通知
---@field showsInNotificationCenter? boolean 是否显示在通知中心
---@field showsInLockScreen? boolean 是否显示在锁定屏幕
---@field showsOnExternalDevices? boolean 是否显示在外部设备
---@field showsMessagePreview? boolean 是否显示消息预览
---@field alertType? integer 提醒样式
---@field pushSettings? integer 推送设置
---@field authorizationStatus? integer 授权状态
---@field displayName? string 显示名称
---@field appName? string App 名称

---@class app_local_network_permissions_info*
---@field bundleIdentifier? string App 标识符
---@field allowsLocalNetwork? boolean 是否允许访问本地网络
---@field authorizationStatus? integer 授权状态，0 表示未决定，1 表示拒绝，2 表示允许
---@field denyMulticast? boolean 是否拒绝本地网络访问
---@field multicastPreferenceSet? boolean 用户偏好是否已经确定
---@field wifiBehavior? integer Wi-Fi 行为
---@field cellularBehavior? integer 蜂窝网络行为

--- 获取 App 的捆绑包路径
---@param appID string 标识符
---@return string? 捆绑包路径
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.bundle_path)
---
function app.bundle_path(appID) end

--- 获取 App 的数据容器路径
---@param appID string 标识符
---@return string? 数据容器路径
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.data_path)
---
function app.data_path(appID) end

--- 获取 App 的分组信息
---@param appID string 标识符
---@return table 分组信息，是这样形式的键值对 {group_id = data_path, ...}
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.group_info)
---
function app.group_info(appID) end

--- 获取 App 的插件信息
---@param appID string 标识符
---@return table 插件信息，是这样形式的列表 {{bid = "xxx", bundle_path= "xxx", data_path = "xxx"}, ...}
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.plugin_info)
---
function app.plugin_info(appID) end

--- 获取 App 的 TEAM ID
---@param appID string 标识符
---@return string? TEAM ID
function app.team_id(appID) end

--- 设置 App 的 TCC 权限
---@param appID string 标识符
---@param service string 服务标识
---@param state integer 状态值
---@return boolean operationSucceed 操作成败
---@return integer originalState 原状态值
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.set_tcc)
---
function app.set_tcc(appID, service, state) end

--- 获取、设置或重置 App 的通知权限信息
--- 该函数在 20260529 以后版本方可使用，iOS 14 以上可用
---@param appID string 标识符
---@param operation? app_permission_operation 操作类型，默认 "get"
---@param info? app_notification_permissions_info* 权限信息，仅用于 "set" 操作
---@return app_notification_permissions_info*? info "get" 操作返回权限信息，没有记录时返回 nil；"set" / "reset" 操作不返回值
function app.notification_permissions(appID, operation, info) end

--- 获取、设置或重置 App 的本地网络权限信息
--- 该函数在 20260529 以后版本方可使用，iOS 14 以上可用
---@param appID string 标识符
---@param operation? app_permission_operation 操作类型，默认 "get"
---@param value? boolean|integer|app_local_network_permissions_info* 是否允许访问本地网络或权限信息，仅用于 "set" 操作
---@return app_local_network_permissions_info*|boolean|nil result "get" 操作返回权限信息或 nil；"set" / "reset" 操作返回是否成功
function app.local_network_permissions(appID, operation, value) end

--- 弹出一个 App 通知
---@param appID string 标识符
---@param title string 通知标题
---@param content string 通知内容
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.pop_banner)
---
function app.pop_banner(appID, title, content) end

--- 运行 App
---@param appID string 标识符
---@return integer 运行状态
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.run)
---
function app.run(appID) end

--- 关闭 App
---@param appID string|integer 标识符或进程号
---@return integer 关闭状态
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.close)
---
function app.close(appID) end

--- 模拟使用上划退出 App
---@param appID string 标识符
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.quit)
---
function app.quit(appID) end

--- 检测 App 是否正在运行
---@param appID string 标识符
---@return boolean 运行状态
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.is_running)
---
function app.is_running(appID) end

--- 获取 App 打开的文件描述符及套接字信息
---@param identifier string | integer 标识符或进程号
---@return table? fileInfo 打开文件列表
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.lsof)
---
function app.lsof(identifier) end

--- 获取 App 的本地化名字
---@param appID string 标识符
---@return string? 本地化名字
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.localized_name)
---
function app.localized_name(appID) end

--- 获取 App 的图标数据
---@param appID string 标识符
---@return string? PNG图片数据
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.png_data_for_bid)
---
function app.png_data_for_bid(appID) end

--- 获取正在运行 App 的进程号
---@param appID string 标识符
---@return integer 进程号
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.pid_for_bid)
---
function app.pid_for_bid(appID) end

--- 获取 App 当前内存消耗
---@param appID string|integer 标识符或进程号
---@return number 内存占用
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.used_memory)
---
function app.used_memory(appID) end

--- 获取前台 App 的标识符
---@return string? 标识符
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.front_bid)
---
function app.front_bid() end

--- 获取前台 App 的进程号
---@return integer 进程号
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.front_pid)
---
function app.front_pid() end

--- 前台打开一个 URL
---@param URL string URL
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.open_url)
---
function app.open_url(URL) end

--- 使用某 App 前台打开一个 URL
---@param bid string App 标识符
---@param URL string URL
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.open_url)
---
function app.open_url(bid, URL) end

--- 获取 App 标识符列表
---@return table 标识符数组
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.bundles)
---
function app.bundles() end

--- 获取进程列表
---@return table 进程列表
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.all_procs)
---
function app.all_procs() end

--- 安装 IPA
---@param ipaPath string 文件路径
---@return boolean operationSucceed 操作成败
---@return string? failureReason 失败原因
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.install)
---
function app.install(ipaPath) end

--- 卸载一个 App
---@param appID string 标识符
---@return boolean operationSucceed 操作成败
---@return string? failureReason 失败原因
---
---[查看文档](https://xxtouch.app/docs/handbook/app/app.uninstall)
---
function app.uninstall(appID) end

--- 向前台 App 中输入文字，该函数因需要注入 App 进程已弃用
---@param text string 文本内容
function app.input_text(text) end

--------------------------------------------------------------------------------
-- 清理模块
--------------------------------------------------------------------------------

---@class clear*
clear = {}

--- 清理某个或某组钥匙串信息
---@param teamid string App 的 Team ID
---
---[查看文档](https://xxtouch.app/docs/handbook/clear/clear.keychain)
---
function clear.keychain(teamid) end

--- 清理所有 App 的钥匙串信息
---
---[查看文档](https://xxtouch.app/docs/handbook/clear/clear.all_keychain)
---
function clear.all_keychain() end

--- 清理剪贴板
function clear.pasteboard() end

--- 清理浏览器 Cookies
---
---[查看文档](https://xxtouch.app/docs/handbook/clear/clear.cookies)
---
function clear.cookies() end

--- 清理系统缓存
---
---[查看文档](https://xxtouch.app/docs/handbook/clear/clear.caches)
---
function clear.caches() end

--- 清除相册中所有本地照片
---
---[查看文档](https://xxtouch.app/docs/handbook/clear/clear.all_photos)
---
function clear.all_photos() end

--- 清理某个应用的存档数据
---@param appID string 标识符
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/clear/clear.app_data)
---
function clear.app_data(appID) end

--- 清理 IDFA/V
---@param newIDFAs? string|table 新IDFA或IDFAV列表
---@return boolean operationSucceed 操作成败
---@return table? oldTab 旧IDFAV表
---
---[查看文档](https://xxtouch.app/docs/handbook/clear/clear.idfav)
---
function clear.idfav(newIDFAs) end


--------------------------------------------------------------------------------
-- 设备模块
--------------------------------------------------------------------------------

---@class device*
device = {}

--- 重置自动锁屏倒计时
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.reset_idle)
---
function device.reset_idle() end

--- 设置自动锁屏分钟数
---@param minutes integer 分钟数，0 表示永不锁屏
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.set_autolock_time)
---
function device.set_autolock_time(minutes) end

--- 锁定屏幕
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.lock_screen)
---
function device.lock_screen() end

--- 解锁屏幕
---@param password? string 锁屏密码，iOS 8 以上已不支持
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.unlock_screen)
---
function device.unlock_screen(password) end

--- 获取屏幕锁定状态
---@return boolean 是否锁屏
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.is_screen_locked)
---
function device.is_screen_locked() end

--- 获取前台应用的画面方向
---@return integer 旋转状态
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.front_orien)
---
function device.front_orien() end

--- 锁定屏幕旋转
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.lock_orien)
---
function device.lock_orien() end

--- 解锁屏幕旋转
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.unlock_orien)
---
function device.unlock_orien() end

--- 获取屏幕旋转锁定状态
---@return boolean 是否锁定
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.is_orien_locked)
---
function device.is_orien_locked() end

--- 振动设备
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.vibrator)
---
function device.vibrator() end

--- 打开 AssistiveTouch
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.assistive_touch_on)
---
function device.assistive_touch_on() end

--- 关闭 AssistiveTouch
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.assistive_touch_off)
---
function device.assistive_touch_off() end

--- 获取 AssistiveTouch 开关状态
---@return boolean 开关状态
function device.is_assistive_touch_on() end

--- 后台播放声音
---@param soundPath string 声音文件路径
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.play_sound)
---
function device.play_sound(soundPath) end

--- 设置设备音量
---@param volume number 音量 (0.0~1.0)
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.set_volume)
---
function device.set_volume(volume) end

--- 获取设备类型
---@return string 设备类型
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.type)
---
function device.type() end

--- 获取设备名
---@return string 设备名
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.name)
---
function device.name() end

--- 设置设备名
---@param name string 设备名
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.set_name)
---
function device.set_name(name) end

--- 获取设备UDID
---@return string UDID
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.udid)
---
function device.udid() end

--- 获取设备的序列号
---@return string 序列号
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.serial_number)
---
function device.serial_number() end

--- 获取设备的 Wi-Fi MAC 地址
---@return string 歪坏麦克
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.wifi_mac)
---
function device.wifi_mac() end

--- 获取设备的蓝牙 MAC 地址
---@return string 布鲁提麦克
function device.bluetooth_mac() end

--- 获取设备所有的接口 IP
---@return table 接口信息数组
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.ifaddrs)
---
function device.ifaddrs() end

--- 获取当前设备电池剩余电量
---@return number 电量
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.battery_level)
---
function device.battery_level() end

--- 获取当前设备充电状态
---@return string 充电状态
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.battery_state)
---
function device.battery_state() end

--- 获取背光亮度值
---@return number 亮度值 (0.0~1.0)
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.brightness)
---
function device.brightness() end

--- 设置背光亮度值
---@param value number 亮度值 (0.0~1.0)
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.set_brightness)
---
function device.set_brightness(value) end

--- 打开减弱动态效果
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.reduce_motion_on)
---
function device.reduce_motion_on() end

--- 关闭减弱动态效果
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.reduce_motion_off)
---
function device.reduce_motion_off() end

--- 获取减弱动态效果开关状态
--- @return boolean 获取开关状态
function device.is_reduce_motion_on() end

--- 打开减弱交叉淡出过渡效果
function device.reduce_motion_slide_on() end

--- 关闭减弱交叉淡出过渡效果
function device.reduce_motion_slide_off() end

--- 获取减弱交叉淡出过渡效果开关状态
--- @return boolean 获取开关状态
function device.is_reduce_motion_slide_on() end

--- 打开 Wi-Fi
function device.wifi_on() end

--- 关闭 Wi-Fi
function device.wifi_off() end

--- 获取 Wi-Fi 开关状态
---@return boolean 开关状态
function device.is_wifi_on() end

--- 打开设备 Wi-Fi
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_on_wifi)
---
function device.turn_on_wifi() end

--- 关闭设备 Wi-Fi
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_off_wifi)
---
function device.turn_off_wifi() end

--- 获取当前 Wi-Fi 信息
---@return table? wifiInfo Wi-Fi 信息
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.wifi_info)
---
function device.wifi_info() end

--- 打开蜂窝数据
function device.data_on() end

--- 关闭蜂窝数据
function device.data_off() end

--- 获取蜂窝数据开关状态
---@return boolean 开关状态
function device.is_data_on() end

--- 打开设备蜂窝数据
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_on_data)
---
function device.turn_on_data() end

--- 关闭设备蜂窝数据
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_off_data)
---
function device.turn_off_data() end

--- 打开蓝牙
function device.bluetooth_on() end

--- 关闭蓝牙
function device.bluetooth_off() end

--- 获取蓝牙开关状态
---@return boolean 开关状态
function device.is_bluetooth_on() end

--- 打开设备蓝牙
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_on_bluetooth)
---
function device.turn_on_bluetooth() end

--- 关闭设备蓝牙
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_off_bluetooth)
---
function device.turn_off_bluetooth() end

--- 打开飞行模式
function device.airplane_on() end

--- 关闭飞行模式
function device.airplane_off() end

--- 获取飞行模式开关状态
---@return boolean 开关状态
function device.is_airplane_on() end

--- 打开设备飞行模式
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_on_airplane)
---
function device.turn_on_airplane() end

--- 关闭设备飞行模式
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_off_airplane)
---
function device.turn_off_airplane() end

--- 连接当前所选 VPN
function device.vpn_on() end

--- 断开当前已连接的 VPN
function device.vpn_off() end

--- 获取 VPN 开关状态
---@return boolean 开关状态
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.is_vpn_on)
---
function device.is_vpn_on() end

--- 打开当前所选 VPN
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_on_vpn)
---
function device.turn_on_vpn() end

--- 断开当前已连接的 VPN
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.turn_off_vpn)
---
function device.turn_off_vpn() end

--- 打开闪光灯
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.flash_on)
---
function device.flash_on() end

--- 关闭闪光灯
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.flash_off)
---
function device.flash_off() end

--- 获取闪光灯开关状态
---@return boolean 是否开启
function device.is_flash_on() end

--- 加入到一个无线接入点
---@param SSID string SSID
---@param password? string 密码，有效密码长度必须大于等于 8
---@param timeout_ms? integer 超时毫秒数
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.join_wifi)
---
function device.join_wifi(SSID, password, timeout_ms) end

--- 遗忘无线接入点
---@param SSID string SSID
---
---[查看文档](https://xxtouch.app/docs/handbook/device/device.forget_wifi)
---
function device.forget_wifi(SSID) end


--------------------------------------------------------------------------------
-- 对话框模块
--------------------------------------------------------------------------------

---@class dialog*
dialog = {}

---@class Dialog*
Dialog = {}

--- 建立一个对话框，没有参数
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/new)
---
function dialog() end

--- 弹出一个只有一个 OK 按钮的弹窗提示
---@param text? string 内容
---@param timeout_s? number 超时秒
function dialog(text, timeout_s) end

--- 设置对话框配置分区
---@param configName? string 配置分区
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_set_config)
---
function Dialog:set_config(configName) end

--- 配置对话框自动消失时间
---@param timeout number 超时秒
---@param shouldSubmit? boolean 是否提交
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_set_timeout)
---
function Dialog:set_timeout(timeout, shouldSubmit) end

--- 配置对话框的标题
---@param title string 标题文本
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_set_title)
---
function Dialog:set_title(title) end

--- 配置对话框关闭按钮的标题
---@param title string 标题文本
---@return Dialog* 对话框
function Dialog:set_close_title(title) end

--- 配置对话框提交按钮的标题
---@param title string 标题文本
---@return Dialog* 对话框
function Dialog:set_submit_title(title) end

--- 配置对话框的尺寸
--- 仅对 webview 引擎的 dialog 有效
---@param width integer 宽度
---@param height integer 高度
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_set_size)
---
function Dialog:set_size(width, height) end

--- 配置对话框的位置及尺寸
--- 仅对 webview 引擎的 dialog 有效
---@param x integer 左上横坐标
---@param y integer 左上纵坐标
---@param width integer 宽度
---@param height integer 高度
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_set_frame)
---
function Dialog:set_frame(x, y, width, height) end

--- 配置对话框的圆角半径
--- 仅对 webview 引擎的 dialog 有效
---@param radius integer 圆角半径
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_set_corner_radius)
---
function Dialog:set_corner_radius(radius) end

--- 给对话框加上一个分组
--- 仅对 XUI 引擎的 dialog 有效
---@param groupName string 分组名称
---@return Dialog* 对话框
function Dialog:add_group(groupName) end

--- 给对话框加上一个标签
---@param labelText string 标签文本
---@param alignment? string 对齐方式
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_label)
---
function Dialog:add_label(labelText, alignment) end

--- 给对话框加上一个文本框
---@param labelText string 标题
---@param placeholder? string 占位符
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_input)
---
function Dialog:add_input(labelText, placeholder) end

--- 给对话框加上一个开关
---@param labelText string 开关标题
---@param defaultValue? boolean 默认值
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_switch)
---
function Dialog:add_switch(labelText, defaultValue) end

--- 给对话框加上一个滑块
---@param labelText string 滑块标题
---@param opts table 选项表 {最小值, 最大值, 步长}
---@param defaultValue? number 默认值
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_range)
---
function Dialog:add_range(labelText, opts, defaultValue) end

--- 给对话框加上一个单项选择器
---@param labelText string 标题
---@param optionList table 选项列表
---@param defaultValue? string 默认值
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_picker)
---
function Dialog:add_picker(labelText, optionList, defaultValue) end

--- 给对话框加上一个单选组
---@param labelText string 标题
---@param optionList table 选项列表
---@param defaultValue? string 默认值
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_radio)
---
function Dialog:add_radio(labelText, optionList, defaultValue) end

--- 给对话框加上一个多选组
---@param labelText string 标题
---@param optionList table 选项列表
---@param defaultList? table 默认值列表
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_checkbox)
---
function Dialog:add_checkbox(labelText, optionList, defaultList) end

--- 给对话框加上一张图片
---@param image ImageObject* 图片
---@return Dialog* 对话框
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_add_image)
---
function Dialog:add_image(image) end

--- 触发回调函数
--- 仅对 XUI 引擎的 dialog 有效
---@param labelText string 标题
---@param callbackFunc? function 回调函数
---@return Dialog* 对话框
function Dialog:add_button(labelText, callbackFunc) end

--- 将对话框弹出来并返回用户的选择
---@return boolean didSubmit 是否提交
---@return table optionTab 选项关联表
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_show)
---
function Dialog:show() end

--- 在不弹出对话框的情况下获得对话框配置
---@return boolean didSubmit 是否提交
---@return table optionTab 选项关联表
---
---[查看文档](https://xxtouch.app/docs/handbook/dialog/dialogm_load)
---
function Dialog:load() end


--------------------------------------------------------------------------------
-- 扩展字符串模块
--------------------------------------------------------------------------------

---@class string*
string = {}

--- 转成十六进制文本
---@param data string 数据内容
---@return string 十六进制文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.to_hex)
---
function string.to_hex(data) end

--- 从十六进制文本转回
---@param hexStr string 十六进制文本
---@return string 数据内容
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.from_hex)
---
function string.from_hex(hexStr) end

--- 将 GBK 编码的文本转成 UTF-8 编码的文本
---@param encStr string GBK编码的字符串
---@return string? 可以直接用的文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.from_gbk)
---
function string.from_gbk(encStr) end

--- 计算 MD5
---@param data string 数据内容
---@return string hexHash
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.md5)
---
function string.md5(data) end

--- 计算 SHA-1
---@param data string 数据内容
---@return string hexHash
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.sha1)
---
function string.sha1(data) end

--- 计算 SHA-256
---@param data string 数据内容
---@return string hexHash
function string.sha256(data) end

--- 计算 HMAC-SHA1
---@param data string 数据内容
---@param key string 密钥
---@return string hexHash
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.hmac_sha1)
---
function string.hmac_sha1(data, key) end

--- 计算 HMAC-SHA256
---@param data string 数据内容
---@param key string 密钥
---@return string hexHash
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.hmac_sha256)
---
function string.hmac_sha256(data, key) end

--- 计算 SHA-512
---@param data string 数据内容
---@return string hexHash
function string.sha512(data) end

--- 编码
---@param data string 数据内容
---@return string b64文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.base64_encode)
---
function string.base64_encode(data) end

--- 解码
---@param encStr string b64文本
---@return string 数据内容
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.base64_decode)
---
function string.base64_decode(encStr) end

--- 加密
---@param data string 数据内容
---@param secret string 密钥
---@return string 加密后的数据
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.aes128_encrypt)
---
function string.aes128_encrypt(data, secret) end

--- 解密
---@param encData string 加密后的数据
---@param secret string 密钥
---@return string 数据内容
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.aes128_decrypt)
---
function string.aes128_decrypt(encData, secret) end

--- 编码 URI 字符串
---@param uri string 原始 URI
---@return string encoded 已编码 URI
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.encode_uri)
---
function string.encode_uri(uri) end

--- 编码 URI 组件
---@param component string 原始文本
---@return string encoded 已编码文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.encode_uri_component)
---
function string.encode_uri_component(component) end

--- 解码 URI 字符串
---@param encodedUri string 编码后的 URI
---@return string uri 解码后的 URI
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.decode_uri)
---
function string.decode_uri(encodedUri) end

--- 解码 URI 组件
---@param encodedComponent string 编码后的文本
---@return string component 解码后的文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.decode_uri_component)
---
function string.decode_uri_component(encodedComponent) end

--- 用分隔符规则分割一个文本
---@param haystack string 待分割文本
---@param sep string 分隔符
---@param maxCnt? integer 最大返回个数
---@return table 分割好的文本数组
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.split)
---
function string.split(haystack, sep, maxCnt) end

--- 判断文本是否以指定前缀开头
---@param text string 被检测文本
---@param prefix string 前缀
---@param position? integer 检测起始位置
---@return boolean 是否匹配
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.starts_with)
---
function string.starts_with(text, prefix, position) end

--- 判断文本是否以指定后缀结尾
---@param text string 被检测文本
---@param suffix string 后缀
---@param length? integer 检测长度
---@return boolean 是否匹配
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.ends_with)
---
function string.ends_with(text, suffix, length) end

--- 去除文本左边的空白字符
---@param text string 处理前文本
---@return string 处理后文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.ltrim)
---
function string.ltrim(text) end

--- 去除文本右边的空白字符
---@param text string 处理前文本
---@return string 处理后文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.rtrim)
---
function string.rtrim(text) end

--- 去除文本两边的空白字符
---@param text string 处理前文本
---@return string 处理后文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.trim)
---
function string.trim(text) end

--- 去除文本中所有的空白字符
---@param text string 处理前文本
---@return string 处理后文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.atrim)
---
function string.atrim(text) end

--- 左侧补齐（别名）
---@param text string 原始文本
---@param length integer 目标长度
---@param padText? string 填充文本
---@return string 补齐后的文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.lpad)
---
function string.lpad(text, length, padText) end

--- 左补齐
---@param text string 处理前文本
---@param padLen integer 补齐长度
---@param padText? string 补齐文本
---@return string 处理后文本
function string.pad_start(text, padLen, padText) end

--- 右侧补齐（别名）
---@param text string 原始文本
---@param length integer 目标长度
---@param padText? string 填充文本
---@return string 补齐后的文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.rpad)
---
function string.rpad(text, length, padText) end

--- 右补齐
---@param text string 处理前文本
---@param padLen integer 补齐长度
---@param padText? string 补齐文本
---@return string 处理后文本
function string.pad_end(text, padLen, padText) end

--- 去除掉文本前的 UTF8-BOM
---@param text string 处理前文本
---@return string 处理后文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.strip_utf8_bom)
---
function string.strip_utf8_bom(text) end

--- 生成随机文本
---@param charPool string 字符池
---@param charCnt integer 生成字符个数
---@return string 随机文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.random)
---
function string.random(charPool, charCnt) end

--- 比较两个版本号大小
---@param verA string 版本号1
---@param verB string 版本号2
---@return integer 比较结果
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-string/string.compare_version)
---
function string.compare_version(verA, verB) end


--------------------------------------------------------------------------------
-- 扩展表模块
--------------------------------------------------------------------------------

---@class table*
table = {}

--- 深拷贝一个表
---@param inTab table 传入表
---@return table 传入表的副本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-table/table.deep_copy)
---
function table.deep_copy(inTab) end

--- 输出到标准输出
---@param inTab table 关联表
---@return string 表文本
function table.deep_print(inTab) end

--- 不输出到标准输出，仅返回字符串
---@param inTab table 关联表
---@return string 表文本
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-table/table.deep_dump)
---
function table.deep_dump(inTab) end

--- 从字符串加载一个表
---@param tabStr string 表文本
---@return table? 关联表
---
---[查看文档](https://xxtouch.app/docs/handbook/ext-table/table.load_string)
---
function table.load_string(tabStr) end


--------------------------------------------------------------------------------
-- 文件操作模块
--------------------------------------------------------------------------------

---@class file*
file = {}

---@class file.path*
file.path = {}

--- 判断文件或目录是否存在
---@param path string 文件或目录路径
---@return boolean 存在信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.exists)
---
function file.exists(path) end

--- 列出目录内所有文件名
---@param path string 目录路径
---@param deep_and_full? boolean 是否递归列出且返回完整路径
---@return table? 文件列表
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.list)
---
function file.list(path, deep_and_full) end

--- 获取文件属性
---@param path string 文件或目录路径
---@param fields? table | string 请求字段
---@return table? attrs 属性表
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.attrs)
---
function file.attrs(path, fields) end

--- 获取符号链接属性
---@param path string 文件或目录路径
---@param fields? table | string 请求字段
---@return table? attrs 属性表
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.lattrs)
---
function file.lattrs(path, fields) end

--- 切换当前工作目录
---@param path string 目录路径
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.chdir)
---
function file.chdir(path) end

--- 获取当前工作目录
---@return string? cwd 当前工作目录
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.currentdir)
---
function file.currentdir() end

--- 获得文件的尺寸
---@param path string 文件路径
---@return integer 文件尺寸
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.size)
---
function file.size(path) end

--- 计算文件的 MD5 值
---@param path string 文件路径
---@return string? hash MD5 值
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.md5)
---
function file.md5(path) end

--- 计算文件的 SHA-1 值
---@param path string 文件路径
---@return string? hash SHA-1 值
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.sha1)
---
function file.sha1(path) end

--- 读取文件中的数据
---@param path string 文件路径
---@return string? 文件内容
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.reads)
---
function file.reads(path) end

--- 将数据写入到文件
---@param path string 文件路径
---@param content string 待写入内容
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.writes)
---
function file.writes(path, content) end

--- 将数据追加到文件末尾
---@param path string 文件路径
---@param content string 待追加内容
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.appends)
---
function file.appends(path, content) end

--- 统计文本文件的总行数
---@param path string 文件路径
---@return integer 行数
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.line_count)
---
function file.line_count(path) end

--- 获取文本文件指定行的内容
---@param path string 文件路径
---@param lineNum integer 行号
---@return string? 行内容
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.get_line)
---
function file.get_line(path, lineNum) end

--- 设置文本文件指定行的内容
---@param path string 文件路径
---@param lineNum integer 行号
---@param content string 待写入内容
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.set_line)
---
function file.set_line(path, lineNum, content) end

--- 在文本文件指定行前插入内容
---@param path string 文件路径
---@param lineNum integer 行号
---@param content string 待插入的内容
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.insert_line)
---
function file.insert_line(path, lineNum, content) end

--- 移除文本文件指定行
---@param path string 文件路径
---@param lineNum integer 行号
---@return boolean operationSucceed 操作成败
---@return string? deletedLine 被删除行的内容
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.remove_line)
---
function file.remove_line(path, lineNum) end

--- 获取一个文本文件的所有行
---@param path string 文件路径
---@return table 行数组
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.get_lines)
---
function file.get_lines(path) end

--- 将一个顺序表转换逐行覆盖写入到文件中
---@param path string 文件路径
---@param lineArr table 行数组
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.set_lines)
---
function file.set_lines(path, lineArr) end

--- 将一个顺序表转换逐行插入到文件指定行前
---@param path string 文件路径
---@param lineNum integer 行号
---@param lineArr table 行数组
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.insert_lines)
---
function file.insert_lines(path, lineNum, lineArr) end

--- 删除文件或目录
---@param path string 文件或目录路径
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.remove)
---
function file.remove(path) end

--- 拷贝文件或目录
---@param srcPath string 源路径
---@param dstPath string 目标路径
---@param mode? "overwrite" | "o" | "merge" | "o" | "overwrite-merge" | "om" | "mo"  覆盖合并模式
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.copy)
---
function file.copy(srcPath, dstPath, mode) end

--- 移动文件或目录
---@param srcPath string 源路径
---@param dstPath string 目标路径
---@param mode? "overwrite" | "o" | "merge" | "o" | "overwrite-merge" | "om" | "mo"  覆盖合并模式
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.move)
---
function file.move(srcPath, dstPath, mode) end

--- 创建硬链接或符号链接
---@param srcPath string 源文件路径
---@param dstPath string 目标文件路径
---@param symbolic? boolean 是否创建符号链接
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.link)
---
function file.link(srcPath, dstPath, symbolic) end

--- 递归创建目录
---@param path string 目录路径
---@param uid? integer 用户 ID
---@param gid? integer 用户组 ID
---@param perm? integer | string 权限
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.mkdir_p)
---
function file.mkdir_p(path, uid, gid, perm) end

--- 更新文件访问和修改时间
---@param path string 文件路径
---@param accessTime? integer 访问时间戳
---@param modifyTime? integer 修改时间戳
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.touch)
---
function file.touch(path, accessTime, modifyTime) end

--- 使用 ZIP 打包文件或目录
---@param zipPath string 输出 zip 路径
---@param entries table | string 文件列表或目录路径
---@param password? string 密码
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.zip)
---
function file.zip(zipPath, entries, password) end

--- 解压 ZIP 文件
---@param zipPath string zip 文件路径
---@param targetPath string 解压目标路径
---@param password? string 密码
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.unzip)
---
function file.unzip(zipPath, targetPath, password) end

--- 在文件系统中搜索文件或目录
---@param pattern string | table 搜索模式
--   - **string (Glob 模式)**:
--     - 使用 Unix shell 风格的 glob 模式进行匹配。路径由 `/` 分隔。
--     - 支持的通配符:
--       - `*`: 匹配当前路径组件中零个或多个任意字符（不匹配 `/`）。
--       - `?`: 匹配当前路径组件中一个任意字符（不匹配 `/`）。
--       - `[...]`: 匹配方括号内指定的任意单个字符。支持：
--         - 字符列表: `[abc]` 匹配 'a', 'b', 或 'c'。
--         - 字符范围: `[a-z]` 匹配任意小写字母。
--         - 否定: `[!abc]` 匹配除 'a', 'b', 'c' 之外的任意字符。
--         - 特殊字符: 要匹配 `]`, `-`, `!` 或 `^` 本身，可以将它们放在开头（`]` 除外，它可以在 `!` 之后）或使用 `\` 转义（尽管转义在此实现中可能不被支持，建议将它们放在安全位置）。
--       - `\`: 用于转义特殊字符（在此实现中可能有限支持，优先使用上述方法）。
--     - 路径分隔符 `/` 用于分隔路径组件，通配符不会跨越 `/` 进行匹配。
--     - 路径开头的 `/` 表示绝对路径搜索。
--     - 路径末尾的 `/` 表示匹配到的最后一项必须是目录。
--     - 示例:
--       - `"/var/log/*.log"`: 查找 `/var/log/` 目录下所有以 `.log` 结尾的文件。
--       - `"/Users/*/Documents/report?.doc"`: 查找所有用户的 `Documents` 目录下名为 `report` 加一个任意字符再加 `.doc` 的文件。
--       - `"/etc/[a-c]*.conf"`: 查找 `/etc/` 目录下以 'a', 'b', 或 'c' 开头，并以 `.conf` 结尾的文件。
--       - `"/usr/local/bin/"`: 查找 `/usr/local/bin` 这个目录本身（如果存在）。
--
--   - **table (精确组件模式)**:
--     - 提供一个 Lua 数组（table），其中每个元素代表路径的一个层级（组件）。
--     - 组件类型:
--       - `string`: 精确匹配该字符串作为目录或文件名。
--         - 如果字符串以 `/` 开头（仅限第一个组件），表示绝对路径。
--         - 如果字符串以 `/` 结尾，表示这一层级匹配到的必须是目录。
--       - `table` (形如 `{ "lua_pattern" }`): 使用提供的 Lua 模式字符串匹配目录或文件名。模式会自动添加 `^` 和 `$` 以确保完全匹配整个组件名称。
--       - `function`: 提供一个自定义匹配函数 `func(name)`。函数接收目录或文件名 `name` 作为参数，需要返回 `true` 表示匹配成功，`false` 表示失败。
--     - 组件按顺序依次匹配。前一个组件必须成功匹配到一个目录（除非是最后一个组件），才能继续匹配下一个组件。
--     - 示例:
--       - `{"/var/log/", {"^apache.*%.log$"}}`: 查找 `/var/log/` 目录下所有以 `apache` 开头并以 `.log` 结尾的文件。
--       - `{ "/Users/", function(name) return name:sub(1,1) ~= "." end, "Documents/" }`: 查找所有非隐藏用户目录下的 `Documents` 目录。
--       - `{ "/", "tmp" }`: 查找根目录下的 `tmp` 文件或目录。
--
---@return table 一个包含所有匹配到的文件或目录的完整路径字符串的数组（table）。如果没有找到匹配项，则返回一个空表 `{}`
---
---[查看文档](https://xxtouch.app/docs/handbook/file/file.find)
---
function file.find(pattern) end

--- 将路径字符串分解为其组成部分。
---@param path string 要分解的路径字符串。
---@return table 一个包含路径各组成部分的数组（表），如果路径无效则返回 (nil, "Invalid path")。
---@usage local components = file.path.components("/usr/local/bin") -- 返回 {"/", "usr", "local", "bin"}
function file.path.components(path) end

--- 返回路径字符串的最后一个组成部分。
---@param path string 路径字符串。
---@return string 路径的最后一个组成部分，如果路径无效则返回 (nil, "Invalid path")。
---@usage local last = file.path.last_component("/usr/local/bin") -- 返回 "bin"
---@usage local last = file.path.last_component("/") -- 返回 "/"
function file.path.last_component(path) end

--- 返回通过删除最后一个路径组成部分生成的新路径字符串。
---@param path string 原始路径字符串。
---@return string 删除最后一个组成部分后的新路径字符串，如果路径无效则返回 (nil, "Invalid path")。
---@usage local parent = file.path.remove_last_component("/usr/local/bin") -- 返回 "/usr/local"
---@usage local parent = file.path.remove_last_component("/usr") -- 返回 "/"
---@usage local parent = file.path.remove_last_component("/") -- 返回 "/"
function file.path.remove_last_component(path) end

--- 返回通过将指定路径组成部分附加到接收者而生成的新路径字符串。
-- 此函数会根据需要自动处理路径分隔符 ('/')。
---@param path string 基础路径字符串。
---@param component string 要附加的路径组成部分。
---@return string 附加组成部分后的新路径字符串，如果任一路径或组件无效则返回 (nil, "Invalid path")。
---@usage local full_path = file.path.add_component("/usr/local", "bin") -- 返回 "/usr/local/bin"
---@usage local full_path = file.path.add_component("/", "tmp") -- 返回 "/tmp"
function file.path.add_component(path, component) end

--- 返回路径字符串的文件扩展名（如果存在）。
-- 扩展名是最后一个路径组成部分中最后一个句点之后的部分。
---@param path string 路径字符串。
---@return string 文件扩展名（不含 '.'），如果路径无效或没有扩展名则返回空字符串或 (nil, "Invalid path")。
---@usage local ext = file.path.extension("/path/to/file.txt") -- 返回 "txt"
---@usage local ext = file.path.extension("/path/to/archive.tar.gz") -- 返回 "gz"
---@usage local ext = file.path.extension("/path/to/file") -- 返回 ""
function file.path.extension(path) end

--- 返回通过删除文件扩展名（如果存在）生成的新路径字符串。
---@param path string 原始路径字符串。
---@return string 删除扩展名后的新路径字符串，如果路径无效则返回 (nil, "Invalid path")。
---@usage local base = file.path.remove_extension("/path/to/file.txt") -- 返回 "/path/to/file"
---@usage local base = file.path.remove_extension("/path/to/archive.tar.gz") -- 返回 "/path/to/archive.tar"
---@usage local base = file.path.remove_extension("/path/to/file") -- 返回 "/path/to/file"
function file.path.remove_extension(path) end

--- 返回通过将指定文件扩展名附加到接收者而生成的新路径字符串。
-- 如果原始路径已有扩展名，则新扩展名将附加在现有扩展名之后（例如，file.txt -> file.txt.bak）。
---@param path string 基础路径字符串。
---@param extension string 要附加的文件扩展名（可以包含或不包含前导 '.'）。
---@return string 附加扩展名后的新路径字符串，如果路径或扩展名无效则返回 (nil, "Invalid path" 或 "Invalid extension")。
---@usage local new_path = file.path.add_extension("/path/to/file", "txt") -- 返回 "/path/to/file.txt"
---@usage local new_path = file.path.add_extension("/path/to/file.tar", "gz") -- 返回 "/path/to/file.tar.gz"
function file.path.add_extension(path, extension) end

--- 返回通过标准化路径生成的新路径字符串。
-- 标准化过程包括解析路径中的 "." 和 ".." 组成部分，移除多余的斜杠，并尝试解析符号链接（但此函数不解析）。
---@param path string 原始路径字符串。
---@return string 标准化后的路径字符串，如果路径无效则返回 (nil, "Invalid path")。
---@usage local std_path = file.path.normalize("/usr/local/../bin/./script") -- 返回 "/usr/bin/script"
---@usage local std_path = file.path.normalize("//tmp///file/") -- 返回 "/tmp/file"
function file.path.normalize(path) end

--- 返回通过解析路径中的符号链接并标准化路径生成的新路径字符串。
-- 此函数会完全解析路径中的所有符号链接，直到获得最终的真实路径。
---@param path string 包含符号链接的原始路径字符串。
---@return string 解析符号链接并标准化后的路径字符串，如果路径无效或解析失败则返回 (nil, "Invalid path")。
---@usage local real_path = file.path.resolve_symlinks("/tmp") -- 可能返回 "/var/tmp"
function file.path.resolve_symlinks(path) end


--------------------------------------------------------------------------------
-- FTP 模块
--------------------------------------------------------------------------------

---@class ftp*
ftp = {}

--- FTP 文件下载
---@param remoteURL string URL
---@param localPath string 本地文件路径
---@param timeout? integer 连接超时秒
---@param shouldContinue? boolean 断点续传模式
---@param blockCallback? function 分块回调函数
---@param bufSiz? integer 缓冲区尺寸
---@return boolean downloadSucceed 下载成败
---@return table downloadDetail 下载信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ftp/ftp.download)
---
function ftp.download(remoteURL, localPath, timeout, shouldContinue, blockCallback, bufSiz) end

--- FTP 文件上传
---@param localPath string 本地文件路径
---@param remoteURL string URL
---@param timeout? integer 连接超时秒
---@param shouldContinue? boolean 断点续传模式
---@param blockCallback? function 分块回调函数
---@param bufSiz? integer 缓冲区尺寸
---@return boolean uploadSucceed 上传成败
---@return table uploadDetail 上传信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ftp/ftp.upload)
---
function ftp.upload(localPath, remoteURL, timeout, shouldContinue, blockCallback, bufSiz) end


--------------------------------------------------------------------------------
-- HTTP 模块
--------------------------------------------------------------------------------

---@class http*
http = {}

--- 发起 GET 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
---
---[查看文档](https://xxtouch.app/docs/handbook/http/http.get)
---
function http.get(optionsOrURL, timeout, headers) end

--- 发起 POST 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
---
---[查看文档](https://xxtouch.app/docs/handbook/http/http.post)
---
function http.post(optionsOrURL, timeout, headers, body) end

--- HTTP 文件下载
---@param remoteURL string URL
---@param localPath string 本地文件路径
---@param timeout? integer 连接超时秒
---@param shouldContinue? boolean 断点续传模式
---@param blockCallback? function 分块回调函数
---@param bufSize? integer 缓冲区尺寸
---@return boolean downloadSucceed 下载成败
---@return table downloadDetail 下载信息
---
---[查看文档](https://xxtouch.app/docs/handbook/http/http.download)
---
function http.download(remoteURL, localPath, timeout, shouldContinue, blockCallback, bufSize) end

--- 发起 HEAD 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---
---[查看文档](https://xxtouch.app/docs/handbook/http/http.head)
---
function http.head(optionsOrURL, timeout, headers) end

--- 发起 DELETE 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
---
---[查看文档](https://xxtouch.app/docs/handbook/http/http.delete)
---
function http.delete(optionsOrURL, timeout, headers) end

--- 将表编码为 application/x-www-form-urlencoded
---@param formTable table 需要编码的表
---@return string formText 编码后的表单文本
---
---[查看文档](https://xxtouch.app/docs/handbook/http/http.table_to_form_urlencoded)
---
function http.table_to_form_urlencoded(formTable) end

--- 将 application/x-www-form-urlencoded 表单文本解码为表
---@param formText string 需要解码表单文本
---@return table? formTable 解码后的表
function http.form_urlencoded_to_table(formText) end

--- 发起 PUT 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
---
---[查看文档](https://xxtouch.app/docs/handbook/http/http.put)
---
function http.put(optionsOrURL, timeout, headers, body) end

--- 发起 MOVE 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.move(optionsOrURL, timeout, headers, body) end

--- 发起 LOCK 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.lock(optionsOrURL, timeout, headers, body) end

--- 发起 UNLOCK 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.unlock(optionsOrURL, timeout, headers, body) end

--- 发起 PROPPATCH 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.proppatch(optionsOrURL, timeout, headers, body) end

--- 发起 COPY 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.copy(optionsOrURL, timeout, headers, body) end

--- 发起 MKCOL 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.mkcol(optionsOrURL, timeout, headers, body) end

--- 发起 PATCH 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.patch(optionsOrURL, timeout, headers, body) end

--- 发起 PROPFIND 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.propfind(optionsOrURL, timeout, headers, body) end

--- 发起 TRACE 请求
---@param optionsOrURL string|{url:string,timeout?:integer,headers?:table,params?:table,multipart?:table,data?:string|table,json?:table,upload_file?:string,download_file?:string} URL或选项
---@param timeout? integer 超时秒
---@param headers? table 请求头
---@param body? string 请求主体
---@return integer statusCode HTTP状态码
---@return string headerJSON 返回头JSON文本
---@return string bodyData 返回主体
function http.trace(optionsOrURL, timeout, headers, body) end


--------------------------------------------------------------------------------
-- CoreML 模块
--------------------------------------------------------------------------------

---@class coreml*
coreml = {}

--- 本机编译 CoreML 模型
---@param modelPath string 模型文件路径
---@return string? compiledPath 编译好的模型路径
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.compile_model)
---
function coreml.compile_model(modelPath) end

--- 创建一个 CoreML 视觉推理器
---@param compiledModelPath string 编译好的模型路径
---@return coreml_vision_request_object*? request 视觉推理器对象
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.new_vision_request)
---
function coreml.new_vision_request(compiledModelPath) end

---@class coreml_model_request_options*
---@field compiled_model_path string 编译好的模型路径
---@field uses_cpu_only? boolean 是否只使用 CPU

--- 创建一个 CoreML 模型请求对象
---@param options coreml_model_request_options*|string 模型请求选项或编译模型路径
---@return coreml_model_request_object* request 模型请求对象
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.new_model_request)
---
function coreml.new_model_request(options) end

--- 创建一个 CoreML 模型请求对象
---@param options coreml_model_request_options*|string 模型请求选项或编译模型路径
---@return coreml_model_request_object* request 模型请求对象
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.new_model_request)
---
function coreml.model_request(options) end

--- 创建一个 CoreML 模型请求对象
---@param options coreml_model_request_options*|string 模型请求选项或编译模型路径
---@return coreml_model_request_object* request 模型请求对象
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.new_model_request)
---
function coreml.session(options) end

--- 创建 CoreML 解码器
---@param schema table|string 解码 schema
---@return coreml_decoder* decoder 解码器
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.create_decoder(schema) end

--- 从图片创建 CoreML/ONNX 兼容张量
---@param imageObj ImageObject* 图片对象
---@param options? table 选项
---@return coreml_multi_array*|onnxruntime_tensor* tensor 张量
---@return onnxruntime_image_tensor_meta* meta 预处理元信息
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.tensor_from_image(imageObj, options) end

--- 从图片数组创建 CoreML/ONNX 兼容 batch 张量
---@param images ImageObject*[] 图片对象数组
---@param options? table 选项
---@return coreml_multi_array*|onnxruntime_tensor* tensor 张量
---@return onnxruntime_image_tensor_meta[] metas 预处理元信息
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.tensor_from_images(images, options) end

---@param matrix coreml_multi_array*|onnxruntime_tensor* 候选矩阵
---@param schema table|string 解码 schema
---@param options? table 选项
---@return table candidates 候选结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.decode_matrix_candidates(matrix, schema, options) end

---@param boxes coreml_multi_array*|onnxruntime_tensor* boxes
---@param scores coreml_multi_array*|onnxruntime_tensor* scores
---@param classIds coreml_multi_array*|onnxruntime_tensor* class ids
---@param keepIndices? coreml_multi_array*|onnxruntime_tensor* keep indices
---@return onnxruntime_box_record[] records 检测记录
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.records_from_boxes(boxes, scores, classIds, keepIndices) end

---@param prototypes coreml_multi_array*|onnxruntime_tensor* prototypes
---@param coefficients coreml_multi_array*|onnxruntime_tensor* coefficients
---@param boxes coreml_multi_array*|onnxruntime_tensor* boxes
---@param width integer 图片宽度
---@param height integer 图片高度
---@param options? table 选项
---@return onnxruntime_mask_bitmap[] masks 掩膜列表
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.proto_masks(prototypes, coefficients, boxes, width, height, options) end

---@param lhs onnxruntime_mask_bitmap*|coreml_multi_array*|onnxruntime_tensor* 左掩膜
---@param rhs onnxruntime_mask_bitmap*|coreml_multi_array*|onnxruntime_tensor* 右掩膜
---@param options? table 选项
---@return number iou 掩膜 IoU
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.mask_iou(lhs, rhs, options) end

---@param opts? table 选项
---@return coreml_tracker* tracker 跟踪器
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml.tracker(opts) end

---@class coreml_vision_request_object*
coreml_vision_request_object = {}

--- 使用 CoreML 推理图像
---@param imageObj ImageObject* 需要推理的图片
---@return table result 推理结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_vision_request_objectm_predict)
---
function coreml_vision_request_object:predict(imageObj) end

---@return boolean ok 是否已关闭
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_vision_request_objectm_predict)
---
function coreml_vision_request_object:close() end

---@return string[] names 输入名
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_vision_request_objectm_predict)
---
function coreml_vision_request_object:input_names() end

---@return string[] names 输出名
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_vision_request_objectm_predict)
---
function coreml_vision_request_object:output_names() end

---@class coreml_model_request_object*
coreml_model_request_object = {}

--- 使用 CoreML 推理
---@param inputs table|string|ImageObject* 输入
---@param outputsOrOptions? string[]|table 输出名或选项
---@param options? table 选项
---@return table result 推理结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:predict(inputs, outputsOrOptions, options) end

--- 使用 CoreML 推理
---@param inputs table|string|ImageObject* 输入
---@param outputsOrOptions? string[]|table 输出名或选项
---@param options? table 选项
---@return table result 推理结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:run(inputs, outputsOrOptions, options) end

---@param inputs table[] batch 输入
---@param outputsOrOptions? string[]|table 输出名或选项
---@param options? table 选项
---@return table result 推理结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:predict_batch(inputs, outputsOrOptions, options) end

---@return boolean done 是否完成异步请求
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:is_done() end

---@return table result 异步结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:results() end

---@return boolean ok 是否已关闭
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:close() end

---@return table metadata 模型元数据
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:metadata() end

---@return boolean usesCpuOnly 是否只使用 CPU
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:uses_cpu_only() end

---@return string computeUnits 计算单元
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:compute_units() end

---@return string[] names 输入名
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:input_names() end

---@return string[] names 输出名
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:output_names() end

---@return table[] features 输入特征
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:input_features() end

---@return table[] features 输出特征
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:output_features() end

---@return table info 输入信息
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:input_info() end

---@return table info 输出信息
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:output_info() end

---@return string[] labels 类别标签
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods)
---
function coreml_model_request_object:class_labels() end

---@class coreml_decoder*
coreml_decoder = {}

---@param outputs table 模型输出
---@param options? table 选项
---@return any result 解码结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_decoder:decode(outputs, options) end

---@return string task 任务名
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_decoder:task() end

---@return table schema 解码 schema
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_decoder:schema() end

---@class coreml_tracker*
coreml_tracker = {}

---@param detections table[] 检测结果
---@param options? table 选项
---@return onnxruntime_track[] tracks 跟踪结果
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_tracker:update(detections, options) end

---@return boolean ok 是否成功
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_tracker:reset() end

---@return onnxruntime_track[] tracks 跟踪状态
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_tracker:state() end

---@return boolean ok 是否成功
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_tracker:close() end

---@class coreml_multi_array*
coreml_multi_array = {}

---@return integer[] shape 形状
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_multi_array:shape() end

---@return string dataType 数据类型
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_multi_array:data_type() end

---@return integer count 元素数量
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_multi_array:count() end

---@return integer[] strides 步长
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_multi_array:strides() end

---@return table data 数据表
---
---[查看文档](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module)
---
function coreml_multi_array:to_table() end


--------------------------------------------------------------------------------
-- 图像模块
--------------------------------------------------------------------------------

---@class image*
image = {}

---@class ImageObject*
ImageObject = {}

--- 判断一个值是否为图片对象
---@param value any 需要判断的值
---@return boolean 是否为图片对象
---
---[查看文档](https://xxtouch.app/docs/handbook/image/image.is)
---
function image.is(value) end

--- 创建指定尺寸空白图片对象
---@param width integer 宽
---@param height integer 高
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/image.new)
---
function image.new(width, height) end

--- 新建一个文本图片对象
---@param text string 文本
---@param opts? table 选项表 {font = 字体, size = 字体大小, color = 字体颜色, alpha = 字体不透明度, back_color = 背景色, back_alpha = 背景不透明度}
---
---[查看文档](https://xxtouch.app/docs/handbook/image/image.new_text_image)
---
function image.new_text_image(text, opts) end

--- 从文件创建图片对象
---@param imgPath string 文件路径
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/image.load_file)
---
function image.load_file(imgPath) end

--- 从数据创建图片对象
---@param imgData string 图像数据
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/image.load_data)
---
function image.load_data(imgData) end

--- 图像拼接
---@param imageNameList table 图片文件名数组
---@param outputPath string 输出路径
---@param direction? integer 拼接方向
---@param quality? number 生成质量
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/image/image.oper_merge)
---
function image.oper_merge(imageNameList, outputPath, direction, quality) end

--- 导入一个图片文件到相册
---@param imagePath string 图片文件路径
function image.image_to_album(imagePath) end

--- 导入一个视频文件到相册
---@param videoPath string 视频文件路径
function image.video_to_album(videoPath) end

--- 获取图片对象的尺寸
---@return integer width 宽
---@return integer height 高
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_size)
---
function ImageObject:size() end

--- 从图片对象创建拷贝图片对象
---@return ImageObject* 图像2
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_copy)
---
function ImageObject:copy() end

--- 截取部分区域新建图片对象
---@param left? integer 左
---@param top? integer 上
---@param right? integer 右
---@param bottom? integer 下
---@return ImageObject* 图像2
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_crop)
---
function ImageObject:crop(left, top, right, bottom) end

--- 销毁一个图片对象
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_destroy)
---
function ImageObject:destroy() end

--- 保存图片对象到相册
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_save_to_album)
---
function ImageObject:save_to_album() end

--- 输出图片对象到 PNG 文件或数据
---@param imagePath string 文件路径
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_save_to_png_file)
---
function ImageObject:save_to_png_file(imagePath) end

--- 输出图片对象到 PNG 文件或数据
---@return string PNG数据
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_png_data)
---
function ImageObject:png_data() end

--- 输出图片对象到 JPEG 文件或数据
---@param imagePath string 文件路径
---@param quality? number 图像质量
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_save_to_jpeg_file)
---
function ImageObject:save_to_jpeg_file(imagePath, quality) end

--- 输出图片对象到 JPEG 文件或数据
---@param quality? number 图像质量
---@return string JPEG数据
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_jpeg_data)
---
function ImageObject:jpeg_data(quality) end

--- 逆时针旋转 90 度 ⤴️
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_turn_left)
---
function ImageObject:turn_left() end

--- 顺时针旋转 90 度 ⤵️
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_turn_right)
---
function ImageObject:turn_right() end

--- 上下翻转
---@return ImageObject* 图像
function ImageObject:turn_upondown() end

--- 缩放图片对象
---@param newWidth integer 宽
---@param newHeight integer 高
---@return ImageObject* 图像
function ImageObject:resize(newWidth, newHeight) end

--- OpenCV 缩放图片对象
---@param newWidth integer 宽
---@param newHeight integer 高
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_cv_resize)
---
function ImageObject:cv_resize(newWidth, newHeight) end

--- 获取图片对象某点颜色
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@return integer color 颜色
---@return integer alpha 不透明度
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_get_color)
---
function ImageObject:get_color(coordX, coordY) end

--- 设置图片对象某点颜色
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@param color integer 颜色
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_set_color)
---
function ImageObject:set_color(coordX, coordY, color) end

--- 颜色替换
---@param origColor integer 原色
---@param replColor integer 替换色
---@param similarity integer 原色相似度
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_replace_color)
---
function ImageObject:replace_color(origColor, replColor, similarity) end

--- 图中贴图
---@param smallImg ImageObject* 小图像
---@param opts? table 选项表 {left = 左上横坐标, top = 左上纵坐标, alpha = 不透明度, background = {{颜色*, 色偏*}, {颜色*, 色偏*}, ...}}
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_draw_image)
---
function ImageObject:draw_image(smallImg, opts) end

--- OpenCV 自动二值化
---@param threshold? integer 二值化阈值
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_cv_binaryzation)
---
function ImageObject:cv_binaryzation(threshold) end

--- 色偏法二值化
---@param opts? table | string { [white_background = boolean], [csim_mode = boolean], [csim_algorithm = 0|1|2], {颜色*, 色偏*}, ... } 或偏色字符串
---@return ImageObject* 图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_binaryzation)
---
function ImageObject:binaryzation(opts) end

--- 使用 OpenCV 比较另一张图片的差异区域
---@param other ImageObject* 另一个图片对象
---@param opts? table 比图配置 {should_visualize = 是否可视化, approx_epsilon = 轮廓逼近周长百分率}
---@return table diffShapes 差异形状集合
---@return ImageObject*? visualizeImage 可视化图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_cv_compare_image)
---
function ImageObject:cv_compare_image(other, opts) end

--- 将图片转换成形状轮廓集合
---@param opts? table 轮廓配置 {should_visualize = 是否可视化, closed = 是否闭合, blur_size = 模糊核, canny_threshold1 = 边缘最小阈值, canny_threshold2 = 边缘最大阈值, approx_epsilon = 轮廓逼近周长百分率}
---@return table shapeList 形状集合
---@return ImageObject*? visualizeImage 可视化图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_cv_to_shapes)
---
function ImageObject:cv_to_shapes(opts) end

--- 在图片中查找给定形状集合
---@param shapes table 目标形状集合
---@param opts? table 配置 {should_visualize = 是否可视化, closed = 是否闭合, min_area = 最小面积, max_area = 最大面积, blur_size = 模糊核, canny_threshold1 = 边缘最小阈值, canny_threshold2 = 边缘最大阈值, diff_threshold = 差异阈值, approx_epsilon = 轮廓逼近周长百分率}
---@return table matches 匹配到的形状信息
---@return ImageObject*? visualizeImage 可视化图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_cv_find_shapes)
---
function ImageObject:cv_find_shapes(shapes, opts) end

--- 使用 OpenCV 特征点匹配检测模板
---@param templates table 模板集合，其中顺序元素是图片对象，字段为配置 {should_visualize = 是否可视化, detector = 特征检测器, score_thresh = 匹配得分阈值}
---@return table results 模板检测结果
---@return ImageObject*? visualizeImage 可视化图像
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_cv_detect_templates)
---
function ImageObject:cv_detect_templates(templates) end

--- 在图片中使用 OpenCV 找图
---@param smallImg ImageObject* 小图像
---@return integer coordX 横坐标
---@return integer coordY 纵坐标
---@return number similarity 匹配相似度
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_cv_find_image)
---
function ImageObject:cv_find_image(smallImg) end

--- 解码当前图片中的二维码
---@return string? text 识别文本
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_qr_decode)
---
function ImageObject:qr_decode() end

--- 图片多点颜色匹配
---@param colors table 匹配表 {{横坐标*, 纵坐标*, 颜色*}, {横坐标*, 纵坐标*, 颜色*}, ...}
---@param similarity? integer 相似度
---@return boolean 是否完全匹配
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_is_colors)
---
function ImageObject:is_colors(colors, similarity) end

--- 图中找色（多点相似度模式）
---@param opts table 匹配表 {[find_order = 查找顺序], [find_all = 是否搜索多个结果], [max_results = 最大结果数], [max_miss = 允许最多未命中数], {起始点横坐标, 起始点纵坐标, 起始点颜色[, 起始点相似度]}, {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]}, {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]}, ...}
---@param similarity? integer 全局相似度
---@param left? integer 搜索区域左上横坐标
---@param top? integer 搜索区域左上纵坐标
---@param right? integer 搜索区域右下横坐标
---@param bottom? integer 搜索区域右下纵坐标
---@return integer coordX 横坐标
---@return integer coordY 纵坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_find_color)
---
function ImageObject:find_color(opts, similarity, left, top, right, bottom) end

--- 图中找色（多点色偏模式）
---@param opts table 匹配表 {[find_order = 查找顺序], [find_all = 是否搜索多个结果], [max_results = 最大结果数], [max_miss = 允许最多未命中数], {起始点横坐标, 起始点纵坐标, {起始点颜色[, 起始点色偏]}}, {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}}, {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}}, ...}
---@param left? integer 搜索区域左上横坐标
---@param top? integer 搜索区域左上纵坐标
---@param right? integer 搜索区域右下横坐标
---@param bottom? integer 搜索区域右下纵坐标
---@return integer coordX 横坐标
---@return integer coordY 纵坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_find_color)
---
function ImageObject:find_color(opts, left, top, right, bottom) end

--- 图中找图
---@param smallImg ImageObject* | string 子图像或子图像路径
---@param confidence_threshold? number | {find_all? : boolean, confidence_threshold? : number, mask? : ImageObject*, downscale? : number, should_visualize? : boolean} 相似度或选项
---@param left? integer 搜索区域左边界
---@param top? integer 搜索区域上边界
---@param right? integer 搜索区域右边界
---@param bottom? integer 搜索区域下边界
---@return integer | table coordX 横坐标
---@return integer coordY 纵坐标
---@return integer resultSimilarity 结果相似度
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_find_image)
---
function ImageObject:find_image(smallImg, confidence_threshold, left, top, right, bottom) end

--- 图片进行光学字符识别
---@param lang_opt? string | table 语言选项
---@param bin_opt? table | string | boolean 二值化选项
---@return string 识别结果字符串列表
---@return table 识别结果详情，包括识别到的区域坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/image/imagem_ocr_text)
---
function ImageObject:ocr_text(lang_opt, bin_opt) end

--- 使用点阵字库对图像执行 OCR，返回识别出的文本与字符信息。
---@param md MatrixDict* 字库对象
---@param opts? number | table 相似度或选项表
--- options 表支持字段：
--- * `sim` number 相似度阈值，取值 0～100，默认 98。
--- * `nms` boolean 是否启用非极大值抑制，默认 true。
--- * `nms_threshold` number 非极大值抑制阈值，默认 0.2，在 `nms` 为 false 时自动置为 0。
---@return string text 以换行分隔的识别结果
---@return table boxes 识别到的字符数组，每项为 {word:string, x:integer, y:integer, w:integer, h:integer}
--- 其中 x=rect.top、y=rect.left，w/h 分别为 rect.bottom-rect.top、rect.right-rect.left；不包含 score 字段。
function ImageObject:dm_ocr(md, opts) end

--- 在图像中查找指定字符串，返回目标起始坐标与匹配字符信息。
---@param md MatrixDict* 字库对象
---@param sim_or_opts? number | string | table 当为 number 表示相似度；为 string 则表示目标文本；为 table 表示选项。
---@param keyword? string 当 `sim_or_opts` 为 number 时，该参数为待查字符串，其它情况可忽略。
--- options 表支持字段：
--- * `sim` number 相似度阈值，取值 0～100，默认 98。
--- * `nms` boolean 是否启用非极大值抑制，默认 true。
--- * `nms_threshold` number 非极大值抑制阈值，默认 0.2。
--- * `find` string | table 指定一个或多个目标字符串。
---@return integer coordX 找到的目标横坐标（未找到返回 -1）
---@return integer coordY 找到的目标纵坐标（未找到返回 -1）
---@return table boxes 命中字符表格，每项格式同 `ImageObject:dm_ocr`。
--- 参数非法时同样返回 -1, -1 与空表。
function ImageObject:dm_find_str(md, sim_or_opts, keyword) end


--------------------------------------------------------------------------------
-- 矩阵字库模块
--------------------------------------------------------------------------------

---@class matrix_dict*
matrix_dict = {}

---@class MatrixDict*
MatrixDict = {}

--- 新建一个空的点阵字库
---@return MatrixDict* dict 字库对象
function matrix_dict.new() end

--- 从文件加载点阵信息创建字库
---@param filename string 文件路径，内容为点阵信息，每行一条
---@return MatrixDict*|nil dict 字库对象
---@return string? errMsg 打开失败时的错误描述
function matrix_dict.load_file(filename) end

--- 从字符串加载点阵信息创建字库
---@param matrixStr string 点阵信息字符串，可包含多行
---@return MatrixDict* dict 字库对象
function matrix_dict.load_string(matrixStr) end

--- 复制当前字库
---@return MatrixDict* newDict 新字库
function MatrixDict:copy() end

--- 追加字符串点阵信息到字库
---@param matrixStr string 点阵信息字符串，可包含多行
---@return integer addedCount 新增的条目数（重复键不会计数）
function MatrixDict:add_with_string(matrixStr) end

--- 追加文件中的点阵信息到字库
---@param filename string 文件路径，内容为点阵信息
---@return integer addedCount 新增的条目数（重复键不会计数）
function MatrixDict:add_with_file(filename) end

--- 将另一个字库的内容追加到当前字库
---@param other MatrixDict* 另一个字库对象
---@return integer addedCount 新增的条目数（重复键不会计数）
function MatrixDict:add_with_dict(other) end

--- 获取当前字库的条目数
---@return integer count 条目数量
function MatrixDict:size() end

--- 导出当前字库的所有原始点阵字符串（按换行拼接）
---@return string matrices 每条点阵一行（遍历顺序为哈希迭代，非排序）
function MatrixDict:dump() end

--- 从字库中删除一条点阵
---@param matrixStr string 点阵信息原文（匹配键）
---@return boolean removed 是否删除成功
function MatrixDict:remove(matrixStr) end


--------------------------------------------------------------------------------
-- JSON 模块
--------------------------------------------------------------------------------

---@class json*
json = {}

--- JSON 中的 NULL 常量
json.null = nil

--- 将 Lua 值转储为 JSON 文本
---@param value any 值
---@return string JSON文本
---
---[查看文档](https://xxtouch.app/docs/handbook/json/json.encode)
---
function json.encode(value) end

--- 将 JSON 文本加载为 Lua 值
---@param jsonStr string JSON文本
---@return any | nil 值
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/json/json.decode)
---
function json.decode(jsonStr) end


--------------------------------------------------------------------------------
-- 硬件输入设备公共类型
--------------------------------------------------------------------------------

---@class hardware_device_properties*
---@field VendorID? integer 供应商编号
---@field ProductID? integer 产品编号
---@field VersionNumber? integer 设备版本号
---@field Product? string 产品名称
---@field Manufacturer? string 制造商名称
---@field Transport? string 本机识别方式；设为 Bluetooth 或 BluetoothLowEnergy 不会建立真实蓝牙连接
---@field SerialNumber? string 序列号
---@field LocationID? integer 位置编号


--------------------------------------------------------------------------------
-- 模拟按键与硬件键盘模块
--------------------------------------------------------------------------------

---@class key*
key = {}

--- 硬件键盘对象；执行 press 或 send_text 时，同一对象的其它操作可能返回 false, "hardware keyboard is busy"
---@class HardwareKeyboard*
HardwareKeyboard = {}

--- 模拟按一下物理按键
--- 使用全局硬件键盘的行为在 20260805 以后版本方可使用；普通键盘和数字小键盘按键会由全局硬件键盘输入，默认保持 10 毫秒，等待期间可能让出当前 Lua 执行线程
---@param keyCode string 按键名称
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.press)
---
function key.press(keyCode) end

--- 模拟按下物理按键
--- 使用全局硬件键盘的行为在 20260805 以后版本方可使用；应当用对应的 key.up 释放按键
---@param keyCode string 按键名称
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.down)
---
function key.down(keyCode) end

--- 松开按下的物理按键
--- 使用全局硬件键盘的行为在 20260805 以后版本方可使用；会与对应的 key.down 保持配对
---@param keyCode string 按键名称
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.up)
---
function key.up(keyCode) end

--- 模拟键入文本
--- 使用全局硬件键盘的行为在 20260805 以后版本方可使用；仅支持英文、数字、空格、半角字符及退格、回车和制表符；硬件键盘按美式键盘映射生成按键
---@param text string 文本
---@param delay? integer 每键延迟毫秒数
---@param shift_delay? integer Shift 键延迟毫秒数
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.send_text)
---
function key.send_text(text, delay, shift_delay) end

--- 输入文字
--- 该函数在 20260816 以后版本方可使用；通过模拟输入法选字的方式输入文字，不读取或修改系统公共剪贴板；`"\b"` 会执行退格操作；密码输入框请使用 sys.input_text
---@param text string 有效的 UTF-8 文字，可以为空
---@param need_enter? boolean 输入完成后是否按回车，默认 false
---@return boolean success 是否成功发出模拟输入操作
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.input_text)
---
function key.input_text(text, need_enter) end

--- 创建独立硬件键盘对象
--- 该函数在 20260805 以后版本方可使用；等待连接时会让出当前 Lua 执行线程
---@param properties? hardware_device_properties* 配置属性；默认 VendorID=0x5858、ProductID=0x0001、Product="XXTouch Keyboard"、Manufacturer="XXTouch"、Transport="USB"
---@return HardwareKeyboard*? keyboard 硬件键盘对象，失败时为 nil
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.connect_keyboard)
---
function key.connect_keyboard(properties) end

--- 创建并连接全局硬件键盘
--- 该函数在 20260805 以后版本方可使用；等待连接时会让出当前 Lua 执行线程，同时只能连接一个全局硬件键盘
---@param properties? hardware_device_properties* 配置属性，与 key.connect_keyboard 相同
---@return HardwareKeyboard*? keyboard 硬件键盘对象，失败时为 nil
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.connect_global_keyboard)
---
function key.connect_global_keyboard(properties) end

--- 获取当前全局硬件键盘
--- 该函数在 20260805 以后版本方可使用；未连接、正在连接或已经断开时返回 nil
---@return HardwareKeyboard*? keyboard 当前全局硬件键盘对象
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.get_global_keyboard)
---
function key.get_global_keyboard() end

--- 释放全部按键并断开当前全局硬件键盘
--- 该函数在 20260805 以后版本方可使用；可以重复调用，没有全局硬件键盘时也返回 true
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/key/key.disconnect_global_keyboard)
---
function key.disconnect_global_keyboard() end

--- 按下硬件键盘按键
--- 该方法在 20260805 以后版本方可使用；字符串使用既有按键名称，数值重载的 Usage Page 只支持 0x07
---@param keyCode string 按键名称
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---@overload fun(self: HardwareKeyboard*, usagePage: integer, usageID: integer): boolean, string?
---
---[查看文档](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_down)
---
function HardwareKeyboard:down(keyCode) end

--- 松开硬件键盘按键
--- 该方法在 20260805 以后版本方可使用；字符串使用既有按键名称，数值重载的 Usage Page 只支持 0x07
---@param keyCode string 按键名称
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---@overload fun(self: HardwareKeyboard*, usagePage: integer, usageID: integer): boolean, string?
---
---[查看文档](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_up)
---
function HardwareKeyboard:up(keyCode) end

--- 按下并松开硬件键盘按键
--- 该方法在 20260805 以后版本方可使用；默认保持 10 毫秒，等待时会让出当前 Lua 执行线程
---@param keyCode string 按键名称
---@param pressDelayMs? number 按下时间毫秒数，默认 10
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---@overload fun(self: HardwareKeyboard*, usagePage: integer, usageID: integer, pressDelayMs?: number): boolean, string?
---
---[查看文档](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_press)
---
function HardwareKeyboard:press(keyCode, pressDelayMs) end

--- 使用硬件键盘输入文本
--- 该方法在 20260805 以后版本方可使用；等待时会让出当前 Lua 执行线程，仅支持英文、数字、空格、半角字符及退格、回车和制表符；按美式键盘映射生成按键，最终字符受目标系统布局影响
---@param text string 文本
---@param typeDelayMs? number 每键延迟毫秒数，默认 0
---@param shiftDelayMs? number Shift 键延迟毫秒数，默认 0
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_send_text)
---
function HardwareKeyboard:send_text(text, typeDelayMs, shiftDelayMs) end

--- 判断硬件键盘是否已连接
--- 该方法在 20260805 以后版本方可使用
---@return boolean connected 是否已连接
---
---[查看文档](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_is_connected)
---
function HardwareKeyboard:is_connected() end

--- 获取创建硬件键盘时保存的配置属性副本
--- 该方法在 20260805 以后版本方可使用；返回值不是实时连接状态，脚本只应依赖公开字段
---@return hardware_device_properties* properties 配置属性
---
---[查看文档](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_get_properties)
---
function HardwareKeyboard:get_properties() end

--- 释放全部按键并断开硬件键盘
--- 该方法在 20260805 以后版本方可使用；可以重复调用
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_disconnect)
---
function HardwareKeyboard:disconnect() end


--------------------------------------------------------------------------------
-- 硬件鼠标模块
--------------------------------------------------------------------------------

---@alias hardware_mouse_button_name "left"|"right"|"middle"|"back"|"forward"
---@alias hardware_mouse_button integer|string|hardware_mouse_button_name

---@class mouse*
mouse = {}

--- 硬件鼠标对象；输入发送失败时会释放全部按键并断开；执行 click 时，同一对象的其它操作可能返回 false, "hardware mouse is busy"
---@class HardwareMouse*
HardwareMouse = {}

--- 创建并连接独立硬件鼠标对象
--- 该函数在 20260805 以后版本方可使用；等待连接时会让出当前 Lua 执行线程
---@param properties? hardware_device_properties* 配置属性；默认 VendorID=0x5858、ProductID=0x0006、VersionNumber=1、Product="XXTouch Mouse"、Manufacturer="XXTouch"、Transport="USB"
---@return HardwareMouse*? mouseObject 硬件鼠标对象，失败时为 nil
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mouse.connect)
---
function mouse.connect(properties) end

--- 相对当前位置移动硬件鼠标
--- 该方法在 20260805 以后版本方可使用；水平和垂直位移均为 -2047 至 2047 的整数，正水平向右，正垂直向下
---@param dx integer 水平位移
---@param dy integer 垂直位移
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_move)
---
function HardwareMouse:move(dx, dy) end

--- 按下硬件鼠标按键
--- 该方法在 20260805 以后版本方可使用；按键可为 1 至 32，名称不区分大小写
---@param button hardware_mouse_button 按键编号或名称
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_down)
---
function HardwareMouse:down(button) end

--- 松开硬件鼠标按键
--- 该方法在 20260805 以后版本方可使用；按键可为 1 至 32，名称不区分大小写
---@param button hardware_mouse_button 按键编号或名称
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_up)
---
function HardwareMouse:up(button) end

--- 点击硬件鼠标按键
--- 该方法在 20260805 以后版本方可使用；默认保持 60 毫秒，等待时会让出当前 Lua 执行线程，目标按键已按下时返回失败
---@param button hardware_mouse_button 按键编号或名称
---@param pressDelayMs? number 按下时间毫秒数，默认 60，必须为非负有限数值
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_click)
---
function HardwareMouse:click(button, pressDelayMs) end

--- 滚动硬件鼠标滚轮
--- 该方法在 20260805 以后版本方可使用；水平和垂直滚动量均为 -127 至 127 的整数，正水平向右，正垂直向上
---@param deltaX integer 水平滚动量
---@param deltaY integer 垂直滚动量
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_scroll)
---
function HardwareMouse:scroll(deltaX, deltaY) end

--- 判断硬件鼠标是否已连接
--- 该方法在 20260805 以后版本方可使用
---@return boolean connected 是否已连接
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_is_connected)
---
function HardwareMouse:is_connected() end

--- 获取创建硬件鼠标时保存的配置属性副本
--- 该方法在 20260805 以后版本方可使用；返回值不是实时连接状态，脚本只应依赖公开字段
---@return hardware_device_properties* properties 配置属性
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_get_properties)
---
function HardwareMouse:get_properties() end

--- 释放全部按键并断开硬件鼠标
--- 该方法在 20260805 以后版本方可使用；可以重复调用
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/mouse/mousem_disconnect)
---
function HardwareMouse:disconnect() end


--------------------------------------------------------------------------------
-- 硬件游戏手柄模块
--------------------------------------------------------------------------------

---@alias hardware_gamepad_button_name "a"|"b"|"x"|"y"|"left_shoulder"|"left_bumper"|"lb"|"l1"|"right_shoulder"|"right_bumper"|"rb"|"r1"|"left_trigger"|"lt"|"l2"|"right_trigger"|"rt"|"r2"|"left_stick"|"l3"|"right_stick"|"r3"|"l4"|"left_paddle"|"r4"|"right_paddle"|"m1"|"m2"|"m3"|"m4"|"start"|"menu"
---@alias hardware_gamepad_button integer|string|hardware_gamepad_button_name
---@alias hardware_gamepad_stick_name "left"|"right"
---@alias hardware_gamepad_stick string|hardware_gamepad_stick_name

---@class gamepad*
gamepad = {}

--- 硬件游戏手柄对象；输入发送失败时会复位并断开；执行 press 时，同一对象的其它操作可能返回 false, "hardware gamepad is busy"
---@class HardwareGamepad*
HardwareGamepad = {}

--- 创建并连接独立硬件游戏手柄对象
--- 该函数在 20260805 以后版本方可使用；等待连接时会让出当前 Lua 执行线程
---@param properties? hardware_device_properties* 配置属性；默认 VendorID=0x5858、ProductID=0x0007、VersionNumber=1、Product="XXTouch Gamepad"、Manufacturer="XXTouch"、Transport="USB"
---@return HardwareGamepad*? gamepadObject 硬件游戏手柄对象，失败时为 nil
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepad.connect)
---
function gamepad.connect(properties) end

--- 按下游戏手柄按键
--- 该方法在 20260805 以后版本方可使用；按键可为 1 至 32、预定义名称或 start、menu，名称不区分大小写
---@param button hardware_gamepad_button 按键编号或名称
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_down)
---
function HardwareGamepad:down(button) end

--- 松开游戏手柄按键
--- 该方法在 20260805 以后版本方可使用；参数规则与 down 相同
---@param button hardware_gamepad_button 按键编号或名称
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_up)
---
function HardwareGamepad:up(button) end

--- 按下并松开游戏手柄按键
--- 该方法在 20260805 以后版本方可使用；默认保持 60 毫秒，等待时会让出当前 Lua 执行线程，目标按键已按下时返回失败
---@param button hardware_gamepad_button 按键编号或名称
---@param pressDelayMs? number 按下时间毫秒数，默认 60，必须为非负有限数值
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_press)
---
function HardwareGamepad:press(button, pressDelayMs) end

--- 设置游戏手柄摇杆位置
--- 该方法在 20260805 以后版本方可使用；坐标必须是 -1 至 1 的有限数值，正水平向右，正垂直向上，0、0 表示回中；位置直接变化，不生成平滑过程
---@param stick hardware_gamepad_stick 左摇杆或右摇杆
---@param x number 水平位置
---@param y number 垂直位置
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_set_stick)
---
function HardwareGamepad:set_stick(stick, x, y) end

--- 设置游戏手柄方向键状态
--- 该方法在 20260805 以后版本方可使用；x 和 y 只能为 -1、0 或 1，可组合斜向，0、0 表示松开
---@param x integer 水平方向
---@param y integer 垂直方向
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_set_dpad)
---
function HardwareGamepad:set_dpad(x, y) end

--- 复位游戏手柄状态
--- 该方法在 20260805 以后版本方可使用；会松开全部按键，并使两个摇杆和方向键回中
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_reset)
---
function HardwareGamepad:reset() end

--- 判断游戏手柄是否已连接
--- 该方法在 20260805 以后版本方可使用
---@return boolean connected 是否已连接
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_is_connected)
---
function HardwareGamepad:is_connected() end

--- 获取创建游戏手柄时保存的配置属性副本
--- 该方法在 20260805 以后版本方可使用；返回值不是实时连接状态，脚本只应依赖公开字段
---@return hardware_device_properties* properties 配置属性
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_get_properties)
---
function HardwareGamepad:get_properties() end

--- 复位并断开游戏手柄
--- 该方法在 20260805 以后版本方可使用；可以重复调用
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/gamepad/gamepadm_disconnect)
---
function HardwareGamepad:disconnect() end


--------------------------------------------------------------------------------
-- 剪贴板模块
--------------------------------------------------------------------------------

---@alias pasteboard_item table<string, string>
---@alias pasteboard_items pasteboard_item|pasteboard_item[]

---@class pasteboard_write_options*
---@field local_only? boolean 仅保存在本机，iOS 10 及以上支持
---@field expiration_date? number Unix 时间戳，单位秒，iOS 10 及以上支持

---@class pasteboard*
pasteboard = {}

--- 获取剪贴板中的数据
---@param utiType? string 通用类型标识
---@return string 数据
---
---[查看文档](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.read)
---
function pasteboard.read(utiType) end

--- 写内容进剪贴板
--- 传入剪贴板项目或剪贴板项目列表时，可为同一个剪贴板项目提供多种格式表示
---@param data string|pasteboard_items 数据、剪贴板项目或剪贴板项目列表
---@param utiTypeOrOptions? string|pasteboard_write_options* 通用类型标识或选项
---@return boolean ok 是否成功
---
---[查看文档](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.write)
---
function pasteboard.write(data, utiTypeOrOptions) end

--- 写剪贴板项目
--- 该函数在 20260428 以后版本方可使用
---@param itemOrItems pasteboard_items 剪贴板项目或剪贴板项目列表
---@param options? pasteboard_write_options* 选项
---@return boolean ok 是否成功
---
---[查看文档](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.write_items)
---
function pasteboard.write_items(itemOrItems, options) end

--- 获取剪贴板中所有数据项的信息
---@return table dataItems 剪贴板中的数据项信息
function pasteboard.dump() end

--- 获取剪贴板中所有数据类型
---@return table types 数据类型列表
function pasteboard.types() end

--- 清空剪贴板并返回原内容
---@return table dataItems 剪贴板中的数据
---
---[查看文档](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.clear)
---
function pasteboard.clear() end


--------------------------------------------------------------------------------
-- 属性表模块
--------------------------------------------------------------------------------

---@class plist*
plist = {}

--- 读取属性表文件
---@param path string 文件路径
---@return table? 表
---
---[查看文档](https://xxtouch.app/docs/handbook/plist/plist.read)
---
function plist.read(path) end

--- 写入属性表文件
---@param path string 文件路径
---@param tab table 表
---@param fmt? "xml" | "binary" | "openstep" 属性表数据格式，默认 "xml"
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/plist/plist.write)
---
function plist.write(path, tab, fmt) end

--- 将属性表数据加载为 Lua 表
---@param data string 属性表数据
---@return table? 表
---
---[查看文档](https://xxtouch.app/docs/handbook/plist/plist.load)
---
function plist.load(data) end

--- 将 Lua 表转储为属性表数据
---@param tab table 表
---@param fmt "xml" | "binary" | "openstep" 数据格式，默认 "xml"
---@return string 属性表数据
---
---[查看文档](https://xxtouch.app/docs/handbook/plist/plist.dump)
---
function plist.dump(tab, fmt) end

--- 属性表数据格式转换
---@param data string 属性表数据
---@param fmt? "xml" | "binary" | "openstep" 属性表数据格式，默认 "xml"
---@return string? convertedData 转换后的属性表数据
---
---[查看文档](https://xxtouch.app/docs/handbook/plist/plist.data_convert)
---
function plist.data_convert(data, fmt) end


--------------------------------------------------------------------------------
-- 进程字典模块
--------------------------------------------------------------------------------

--- 存储值到进程字典
---@param key string 键名
---@param value string 值
---@return string 返回这个键位置的旧的值，如果没有则返回空字符串
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_put)
---
function proc_put(key, value) end

--- 查看进程字典存储的值
---@param key string 键名
---@return string 返回该键位置存储的值，如果该键位置没有值则返回空字符串
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_get)
---
function proc_get(key) end

--- 执行进程字典事务代码
---@param code string 事务 Lua 代码
---@return string? result 返回内容
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_dict_run)
---
function proc_dict_run(code) end

--- 向进程队列词典的尾部压入一个值
---@param key string 键名
---@param value string 值
---@return integer 当前队列长度
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_push)
---
function proc_queue_push(key, value) end

--- 从进程队列词典的尾部弹出一个值
---@param key string 键名
---@return string 返回弹出的值，如果队列不存在或为空，则返回空字符串
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_pop)
---
function proc_queue_pop(key) end

--- 向进程队列词典的尾部压入一个值
---@param key string 键名
---@param value string 值
---@return integer 当前队列长度
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_push_back)
---
function proc_queue_push_back(key, value) end

--- 向进程队列词典的头部压入一个值
---@param key string 键名
---@param value string 值
---@return integer 当前队列长度
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_push_front)
---
function proc_queue_push_front(key, value) end

--- 从进程队列词典的尾部弹出一个值
---@param key string 键名
---@return string 返回弹出的值，如果队列不存在或为空，则返回空字符串
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_pop_back)
---
function proc_queue_pop_back(key) end

--- 从进程队列词典的头部弹出一个值
---@param key string 键名
---@return string 返回弹出的值，如果队列不存在或为空，则返回空字符串
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_pop_front)
---
function proc_queue_pop_front(key) end

--- 读取进程队列词典中所有的值
---@param key string 键名
---@return table values 值集合
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_read)
---
function proc_queue_read(key) end

--- 从进程队列词典弹出所有指定值
---@param key string 键名
---@param value string 指定值
---@return integer count 弹出个数
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_pop_value)
---
function proc_queue_pop_value(key, value) end

--- 统计进程队列词典中特定值个数
---@param key string 键名
---@param value string 指定值
---@return integer count 个数
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_count_value)
---
function proc_queue_count_value(key, value) end

--- 从进程队列词典中弹出所有值
---@param key string 键名
---@return table 返回弹出的值列表，如果队列不存在或为空，则返回空列表
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_clear)
---
function proc_queue_clear(key) end

--- 获取进程队列词典的尺寸
---@param key string 键名
---@return integer 当前队列长度
---
---[查看文档](https://xxtouch.app/docs/handbook/proc/proc_queue_size)
---
function proc_queue_size(key) end

--------------------------------------------------------------------------------
-- 屏幕模块
--------------------------------------------------------------------------------

---@class screen*
screen = {}

--- 初始化旋转坐标系
---@param coordinate integer 坐标系
---@return integer 原坐标系
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.init)
---
function screen.init(coordinate) end

--- 初始化旋转坐标系（Home 在下）
---@return integer 原坐标系
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.init)
---
function screen.init_home_on_bottom() end

--- 初始化旋转坐标系（Home 在右）
---@return integer 原坐标系
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.init)
---
function screen.init_home_on_right() end

--- 初始化旋转坐标系（Home 在左）
---@return integer 原坐标系
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.init)
---
function screen.init_home_on_left() end

--- 初始化旋转坐标系（Home 在上）
---@return integer 原坐标系
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.init)
---
function screen.init_home_on_top() end

--- 坐标旋转转换
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@param direction integer 旋转方向
---@return integer newCoordX 旋转后的横坐标
---@return integer newCoordY 旋转后的纵坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.rotate_xy)
---
function screen.rotate_xy(coordX, coordY, direction) end

--- 反向坐标旋转转换
---@param coordX integer 原横坐标
---@param coordY integer 原纵坐标
---@param direction integer 原坐标旋转方向
---@return integer portraitX 对应的竖屏横坐标
---@return integer portraitY 对应的竖屏纵坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.unrotate_xy)
---
function screen.unrotate_xy(coordX, coordY, direction) end

--- 获取屏幕缩放因子
---@return number scaleFactor 屏幕缩放因子
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.scale_factor)
---
function screen.scale_factor() end

--- 获取屏幕尺寸
---@return integer screenWidth 屏宽
---@return integer screenHeight 屏高
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.size)
---
function screen.size() end

--- 保持屏幕
---@return integer 获取屏幕内容计数
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.keep)
---
function screen.keep() end

--- 退出屏幕保持状态
---@return integer 获取屏幕内容计数
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.unkeep)
---
function screen.unkeep() end

--- 获取屏幕上某点颜色
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@return integer 颜色值
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.get_color)
---
function screen.get_color(coordX, coordY) end

--- 获取屏幕上某点颜色 RGB
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@return integer red 红
---@return integer green 绿
---@return integer blue 蓝
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.get_color_rgb)
---
function screen.get_color_rgb(coordX, coordY) end

--- 屏幕多点颜色匹配
---@param colors table 颜色表 {{横坐标*, 纵坐标*, 颜色*}, {横坐标*, 纵坐标*, 颜色*}, ...}
---@param similarity? integer 相似度
---@return boolean 是否完全匹配
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.is_colors)
---
function screen.is_colors(colors, similarity) end

--- 多点相似度模式找色
---@param opts table 匹配表 {[find_all = 是否搜索多个结果], [max_results = 最大结果数], [max_miss = 允许最多未命中数], {起始点横坐标, 起始点纵坐标, 起始点颜色[, 起始点相似度]}, {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]}, {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]}, ...}
---@param similarity? integer 全局相似度
---@param left? integer 搜索区域左边界
---@param top? integer 搜索区域上边界
---@param right? integer 搜索区域右边界
---@param bottom? integer 搜索区域下边界
---@return integer coordX 横坐标
---@return integer coordY 纵坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.find_color-co)
---
function screen.find_color(opts, similarity, left, top, right, bottom) end

--- 多点色偏模式找色
---@param opts table 匹配表 {[find_all = 是否搜索多个结果], [max_results = 最大结果数], [max_miss = 允许最多未命中数], {起始点横坐标, 起始点纵坐标, {起始点颜色[, 起始点色偏]}}, {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}}, {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}}, ...}
---@param left? integer 搜索区域左边界
---@param top? integer 搜索区域上边界
---@param right? integer 搜索区域右边界
---@param bottom? integer 搜索区域下边界
---@return integer coordX 横坐标
---@return integer coordY 纵坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.find_color-cs)
---
function screen.find_color(opts, left, top, right, bottom) end

--- 获取屏幕内容
---@param left? integer 左
---@param top? integer 上
---@param right? integer 右
---@param bottom? integer 下
---@return ImageObject* 屏幕内容
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.image)
---
function screen.image(left, top, right, bottom) end

--- 屏幕找图
---@param smallImg ImageObject* | string 子图像或子图像路径
---@param confidence_threshold? number | {find_all? : boolean, confidence_threshold? : number, mask? : ImageObject*, downscale? : number, should_visualize? : boolean} 相似度或选项
---@param left? integer 搜索区域左边界
---@param top? integer 搜索区域上边界
---@param right? integer 搜索区域右边界
---@param bottom? integer 搜索区域下边界
---@return integer | table coordX 横坐标
---@return integer coordY 纵坐标
---@return integer resultSimilarity 结果相似度
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.find_image)
---
function screen.find_image(smallImg, confidence_threshold, left, top, right, bottom) end

--- 屏幕区域光学字符识别
---@param left? integer 横坐标左边界
---@param top? integer 纵坐标上边界
---@param right? integer 横坐标右边界
---@param bottom? integer 纵坐标下边界
---@param lang_opt? string | table 语言选项
---@param bin_opt? table | string | boolean 二值化选项
---@return string 识别结果字符串
---@return table 识别结果详情，包括识别到的区域坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/screen/screen.ocr_text)
---
function screen.ocr_text(left, top, right, bottom, lang_opt, bin_opt) end

--------------------------------------------------------------------------------
-- 系统模块
--------------------------------------------------------------------------------

---@class sys*
sys = {}

--- 显示提示文字
---@param text string 文字内容
---@param orien? integer | {allow_screenshot? : boolean, orien?: integer} 旋转方向或选项 allow_screenshot 允许 toast 被截屏
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.toast)
---
function sys.toast(text, orien) end

--- 弹出系统提示
---@param content string 文字内容
---@param autoDismissalInSeconds? integer 自动消失秒数
---@param title? string 标题
---@param btnA? string 按钮0标题
---@param btnB? string 按钮1标题
---@param btnC? string 按钮2标题
---@return integer 选择
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.alert)
---
function sys.alert(content, autoDismissalInSeconds, title, btnA, btnB, btnC) end

--- 弹出输入提示
---@param title string 标题
---@param message? string 描述内容
---@param shadowOpts? string|table 阴影提示内容或阴影提示表 {"文本框1阴影提示", "文本框2阴影提示"}
---@param defaultTexts? string|table 默认文本内容或默认文本表 {"文本框1默认文本", "文本框2默认文本"}
---@param btnA? string 按钮0标题
---@param btnB? string 按钮1标题
---@param btnC? string 按钮2标题
---@param autoDismissalInSeconds? integer 自动消失秒数
---@return string enteredTextA 输入的文本行A
---@return string? enteredTextB 输入的文本行B
---@return integer? selectedButtonIndex 选择的按钮索引
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.input_box)
---
function sys.input_box(title, message, shadowOpts, defaultTexts, btnA, btnB, btnC, autoDismissalInSeconds) end

--- 弹出输入提示
---@param title string 标题
---@param message? string 描述内容
---@param shadowOpts? string|table 阴影提示内容或阴影提示表 {"文本框1阴影提示", "文本框2阴影提示"}
---@param defaultTexts? string|table 默认文本内容或默认文本表 {"文本框1默认文本", "文本框2默认文本"}
---@param autoDismissalInSeconds? integer 自动消失秒数
---@return string enteredTextA 输入的文本行A
---@return string? enteredTextB 输入的文本行B
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.input_box)
---
function sys.input_box(title, message, shadowOpts, defaultTexts, autoDismissalInSeconds) end

--- 输入文字
---@param text string 文字内容
---@param shouldPressEnter? boolean 输入完成按回车
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.input_text)
---
function sys.input_text(text, shouldPressEnter) end

--- 毫秒级延迟
---@param delayInMilliseconds integer 毫秒数
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.msleep)
---
function sys.msleep(delayInMilliseconds) end

--- 获取当前毫秒级时间戳
---@return integer 毫秒级UNIX时间戳
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.mtime)
---
function sys.mtime() end

--- 获取网络时间
---@return integer timestamp 秒级UNIX时间戳
---@return boolean isSynchronized 是否已同步
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.net_time)
---
function sys.net_time() end

--- 产生一个随机数
---@return integer 随机数字
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.rnd)
---
function sys.rnd() end

--- 获取设备当前可用内存值
---@return number 可用内存
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.available_memory)
---
function sys.available_memory() end

--- 获取设备当前内存状态信息
---@return table memoryInfo 内存状态
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.memory_info)
---
function sys.memory_info() end

--- 获取设备当前未使用的存储空间值
---@param mountPoint? string 挂载点
---@return number freeSize 剩余空间 (MB)
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.free_disk_space)
---
function sys.free_disk_space(mountPoint) end

--- 输出标准系统日志
---@param ... any
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.log)
---
function sys.log(...) end

--- 问系统一个问题
---@param question string 问题名称
---@return string? 系统回复
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.mgcopyanswer)
---
function sys.mgcopyanswer(question) end

--- 读取指定的 sysctl 键值
---@param keyName string sysctl 的完整键名，例如 "kern.boottime"
---@return string? data 原始字节数据，读取失败时返回 nil
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.ctlbyname)
---
function sys.ctlbyname(keyName) end

--- 获取系统版本
---@return string 系统版本
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.version)
---
function sys.version() end

--- 获取 CoreFoundation 版本
---@return number cfVersion CoreFoundation 版本号
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.cfversion)
---
function sys.cfversion() end

--- 获取 XXTouch 版本
---@return string 版本号
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.xtversion)
---
function sys.xtversion() end

--- 获取允许 App 请求跟踪开关状态
--- 该函数在 20260529 以后版本方可使用
---@return boolean? allow 是否允许 App 请求跟踪，读取失败返回 nil
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.user_tracking)
---
function sys.user_tracking() end

--- 设置允许 App 请求跟踪开关状态
--- 该函数在 20260529 以后版本方可使用
---@param allow boolean 是否允许 App 请求跟踪
---@return boolean success 是否设置成功
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.user_tracking)
---
function sys.set_user_tracking(allow) end

--- 获取个性化广告开关状态
--- 该函数在 20260529 以后版本方可使用
---@return boolean? allow 是否允许个性化广告，读取失败返回 nil
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.personalized_advertising)
---
function sys.personalized_advertising() end

--- 设置个性化广告开关状态
--- 该函数在 20260529 以后版本方可使用
---@param allow boolean 是否允许个性化广告
---@return boolean success 是否设置成功
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.personalized_advertising)
---
function sys.set_personalized_advertising(allow) end

--- 获取定位服务总开关状态
--- 该函数在 20260529 以后版本方可使用
---@return boolean? enabled 是否开启定位服务，读取失败返回 nil
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.location_services)
---
function sys.location_services() end

--- 设置定位服务总开关状态
--- 该函数在 20260529 以后版本方可使用
---@param enabled boolean 是否开启定位服务
---@return boolean success 是否设置成功
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.location_services)
---
function sys.set_location_services(enabled) end

--- 获取 XXTouch OpenAPI 的端口号
---@return integer 端口号
function sys.port() end

--- 向指定进程发送信号
---@param pid integer 进程号
---@param signal integer 信号编号
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.kill)
---
function sys.kill(pid, signal) end

--- 向指定名称的进程发送信号
---@param signal integer 信号编号
---@param ... string 进程名称列表
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.killall)
---
function sys.killall(signal, ...) end

--- 重启
function sys.reboot() end

--- 关机
function sys.halt() end

--- 递归修改文件所有者
---@param path string 文件或目录路径
---@param uid integer 用户 ID
---@param gid integer 用户组 ID
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.lchown_r)
---
function sys.lchown_r(path, uid, gid) end

--- 递归修改文件权限
---@param path string 文件或目录路径
---@param perm integer | string 权限
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.lchmod_r)
---
function sys.lchmod_r(path, perm) end

--- 递归修改文件所有者与权限
---@param path string 文件或目录路径
---@param uid integer 用户 ID
---@param gid integer 用户组 ID
---@param perm integer | string 权限
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.lchownmod_r)
---
function sys.lchownmod_r(path, uid, gid, perm) end

--- 递归创建目录
---@param path string 目录路径
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.mkdir_p)
---
function sys.mkdir_p(path) end

---@class sys_task_pipe_object*
sys_task_pipe_object = {}

--- 从管道中读取已经准备好的数据
---@param bytes? integer 读取字节数
---@return string data 数据内容
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_pipe_object:read(bytes) end

--- 向管道中写入数据
---@param data string 数据内容
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_pipe_object:write(data) end

--- 关闭管道写端
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_pipe_object:wclose() end

--- 关闭管道读端
---@return boolean ok 操作成败
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_pipe_object:rclose() end

---@class sys_task_object*
sys_task_object = {}

--- 启动任务
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:launch() end

--- 同步等待任务结束
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:wait_until_exit() end

--- 设置任务输入流
---@param input sys_task_pipe_object* | "/dev/null" | "/dev/zero" 输入流
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:set_stdin(input) end

--- 获取任务输入流
---@return sys_task_pipe_object* input 输入流
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:stdin() end

--- 设置任务输出流
---@param output sys_task_pipe_object* | "/dev/null" 输出流
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:set_stdout(output) end

--- 获取任务输出流
---@return sys_task_pipe_object* output 输出流
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:stdout() end

--- 设置任务错误流
---@param output sys_task_pipe_object* | "/dev/null" 错误流
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:set_stderr(output) end

--- 获取任务错误流
---@return sys_task_pipe_object* output 错误流
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:stderr() end

--- 设置任务的工作目录
---@param workDir string 工作目录
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:set_work_dir(workDir) end

--- 获取任务的工作目录
---@return string workDir 工作目录
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:work_dir() end

--- 设置任务环境变量
---@param env table 环境变量词典
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:set_env(env) end

--- 获取任务环境变量
---@return table env 环境变量词典
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:env() end

--- 获取任务进程号
---@return integer pid 进程号
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:pid() end

--- 判断任务是否正在运行
---@return boolean running 是否运行中
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:is_running() end

--- 向任务发送 SIGINT
---@return boolean ok 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:interrupt() end

--- 向任务发送 SIGTERM
---@return boolean ok 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:terminate() end

--- 向任务发送 SIGKILL
---@return boolean ok 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:kill() end

--- 获取任务终止状态
---@return integer | nil status 终止状态
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:termination_status() end

--- 获取任务终止原因
---@return string | nil reason 终止原因
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys_task_object:termination_reason() end

--- 创建一个执行任务
---@param executablePath string 可执行文件路径
---@param ... string 参数
---@return sys_task_object* task 任务对象
---
---[查看文档](https://xxtouch.app/docs/handbook/sys/sys.task)
---
function sys.task(executablePath, ...) end


--------------------------------------------------------------------------------
-- 线程模块
--------------------------------------------------------------------------------

---@class thread*
thread = {}

--- 派发一个任务
---@param taskClousure function 任务函数
---@param errorCallback? function 错误回调
---@return integer 任务ID
---
---[查看文档](https://xxtouch.app/docs/handbook/thread/thread.dispatch)
---
function thread.dispatch(taskClousure, errorCallback) end

--- 获取当前任务的 ID
---@return integer 任务ID
---
---[查看文档](https://xxtouch.app/docs/handbook/thread/thread.current_id)
---
function thread.current_id() end

--- 从队列中移除一项任务
---@param taskID integer 任务ID
---
---[查看文档](https://xxtouch.app/docs/handbook/thread/thread.kill)
---
function thread.kill(taskID) end

--- 阻塞等待一个任务完成
---@param taskID integer 任务ID
---@param timeout? integer 超时秒
---
---[查看文档](https://xxtouch.app/docs/handbook/thread/thread.wait)
---
function thread.wait(taskID, timeout) end

--- 注册监听一个事件
---@param eventName string 事件名称
---@param eventCallback function 事件回调
---@param errorCallback? function 错误回调
---@return integer 事件监听ID
---
---[查看文档](https://xxtouch.app/docs/handbook/thread/thread.register_event)
---
function thread.register_event(eventName, eventCallback, errorCallback) end

--- 反注册监听一个事件
---@param eventName string 事件名称
---@param eventID integer 事件监听ID
---@return integer 事件监听ID
---
---[查看文档](https://xxtouch.app/docs/handbook/thread/thread.unregister_event)
---
function thread.unregister_event(eventName, eventID) end


--------------------------------------------------------------------------------
-- 模拟触摸模块
--------------------------------------------------------------------------------

---@class touch*
touch = {}

---@class TouchObject*
TouchObject = {}

--- 设置触摸事件可视化显示
---@param shouldShow boolean 是否显示
function touch.show_pose(shouldShow) end

--- 模拟手指轻触一次屏幕
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@param delayBetweenDownAndUpInMs? integer 延迟毫秒
---@param delayAfterUpInMs? integer 操作后等待毫秒
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touch.tap)
---
function touch.tap(coordX, coordY, delayBetweenDownAndUpInMs, delayAfterUpInMs) end

--- 模拟手指接触屏幕
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@return TouchObject* 触摸事件
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touch.on)
---
function touch.on(coordX, coordY) end

--- 模拟手指离开屏幕
---@param coordX? integer 横坐标
---@param coordY? integer 纵坐标
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_off)
---
function TouchObject:off(coordX, coordY) end

--- 模拟手指在屏幕上移动
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@param pressure? integer 压力
---@param twist? integer 角度
---@param flags? integer 选项标识位
---@return TouchObject* 触摸事件
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_move)
---
function TouchObject:move(coordX, coordY, pressure, twist, flags) end

--- 设置触摸事件对象移动每步延迟
---@param stepDelayMs integer 每步延迟毫秒数
---@return TouchObject* 触摸事件
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_step_delay)
---
function TouchObject:step_delay(stepDelayMs) end

--- 设置触摸事件对象移动步长
---@param stepLength integer 步长
---@return TouchObject* 触摸事件
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_step_len)
---
function TouchObject:step_len(stepLength) end

--- 毫秒级延迟
---@param delayInMs integer 毫秒数
---@return TouchObject* 触摸事件
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_msleep)
---
function TouchObject:msleep(delayInMs) end

--- 毫秒级延迟
---@param delayInMs integer 毫秒数
---@return TouchObject* 触摸事件
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_msleep)
---
function TouchObject:delay(delayInMs) end

--- 模拟手指在屏幕上施加压力
---@param pressure? integer 压力
---@param twist? integer 角度
---@return TouchObject* 触摸事件
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_press)
---
function TouchObject:press(pressure, twist) end

--- 模拟手指接触屏幕
---@param finger_id integer 手指ID
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@return integer 触摸手指ID
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touch.on)
---
function touch.on(finger_id, coordX, coordY) end

--- 模拟手指在屏幕上移动
---@param finger_id integer 手指ID
---@param coordX? integer 横坐标
---@param coordY? integer 纵坐标
---@return integer 触摸手指ID
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_move)
---
function touch.move(finger_id, coordX, coordY) end

--- 模拟手指离开屏幕
---@param finger_id integer 手指ID
---@param coordX? integer 横坐标
---@param coordY? integer 纵坐标
---@return integer 触摸手指ID
---
---[查看文档](https://xxtouch.app/docs/handbook/touch/touchm_off)
---
function touch.off(finger_id, coordX, coordY) end


--------------------------------------------------------------------------------
-- 小工具模块
--------------------------------------------------------------------------------

---@class utils*
utils = {}

--- 时间戳转换为格式化时间文本
---@param format string 时间格式
---@param timestamp number 时间戳
---@param opts? table 选项 {tz = 时区, locale = 本地化}
---@return string formattedText 格式化时间
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.date_to_format)
---
function utils.date_to_format(format, timestamp, opts) end

--- 格式化时间文本转换为时间戳
---@param format string 时间格式
---@param dateText string 时间文本
---@param opts? table 选项 {tz = 时区, locale = 本地化}
---@return number timestamp 时间戳
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.date_from_format)
---
function utils.date_from_format(format, dateText, opts) end

--- 时间戳转换为 RFC 1123 文本
---@param timestamp number 时间戳
---@return string rfc1123 RFC1123 文本
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.date_to_rfc1123)
---
function utils.date_to_rfc1123(timestamp) end

--- RFC 1123 文本转换为时间戳
---@param rfc1123 string RFC1123 文本
---@return number timestamp 时间戳
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.date_from_rfc1123)
---
function utils.date_from_rfc1123(rfc1123) end

--- 时间戳转换为 RFC 3339 文本
---@param timestamp number 时间戳
---@return string rfc3339 RFC3339 文本
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.date_to_rfc3339)
---
function utils.date_to_rfc3339(timestamp) end

--- RFC 3339 文本转换为时间戳
---@param rfc3339 string RFC3339 文本
---@return number timestamp 时间戳
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.date_from_rfc3339)
---
function utils.date_from_rfc3339(rfc3339) end

--- 生成一个 UUID
---@return string uuid UUID
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.gen_uuid)
---
function utils.gen_uuid() end

--- 生成基于时间的一次性验证码
--- 该函数在 20260107 以后版本方可使用
---@param timestamp integer Unix 时间戳，单位为秒；传入 -1 表示使用当前时间
---@param url string TOTP 链接，格式为 otpauth://totp/...
---@param secret? string Base32 密钥
---@return string? code 一次性验证码
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.totp_next)
---
function utils.totp_next(timestamp, url, secret) end

--- 按计数器生成一次性验证码
--- 该函数在 20260107 以后版本方可使用
---@param counter integer HOTP 计数器
---@param url string HOTP 链接，格式为 otpauth://hotp/...
---@param secret? string Base32 密钥
---@return string? code 一次性验证码
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.hotp_counter)
---
function utils.hotp_counter(counter, url, secret) end

--- 生成下一个基于计数器的一次性验证码
--- 该函数在 20260107 以后版本方可使用
---@param url string HOTP 链接，格式为 otpauth://hotp/...
---@param secret? string Base32 密钥
---@return string? code 一次性验证码
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.hotp_next)
---
function utils.hotp_next(url, secret) end

--- 将文本编码成二维码图片
---@param text string 文本内容
---@param opts? table 选项 {size = 尺寸, fill_color = 填充颜色, shadow_color = 阴影颜色}
---@return ImageObject* image 图片对象
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.qr_encode)
---
function utils.qr_encode(text, opts) end

--- 导入一个视频文件到相册
---@param videoPath string 视频文件路径
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.video_to_album)
---
function utils.video_to_album(videoPath) end

--- 给通讯录添加一个或多个联系人
---@param contacts table 联系人列表
---{
---  {
---    firstName = "姓1",
---    lastName = "名1",
---    phoneNumbers = {
---      "联系人1号码1",
---      "联系人1号码2",
---    },
---    emails = {
---      "联系人1邮箱1",
---      "联系人1邮箱2",
---    },
---  },
---  {
---    firstName = "姓2",
---    lastName = "名2",
---    phoneNumbers = {
---      "联系人2号码1",
---      "联系人2号码2",
---    },
---    emails = {
---      "联系人2邮箱1",
---      "联系人2邮箱2",
---    },
---  },
---  ...
---}
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.add_contacts)
---
function utils.add_contacts(contacts) end

--- 删除通讯录所有联系人
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.remove_all_contacts)
---
function utils.remove_all_contacts() end

--- 获得当前脚本的启动参数
---@return table 启动参数关联表
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.launch_args)
---
function utils.launch_args() end

--- 判断当前脚本是否从 App 内启动
---@return boolean 是否从App内启动
---
---[查看文档](https://xxtouch.app/docs/handbook/utils/utils.is_launch_via_app)
---
function utils.is_launch_via_app() end


--------------------------------------------------------------------------------
-- VPN 配置模块
--------------------------------------------------------------------------------

---@class vpnconf*
vpnconf = {}

--- 创建一个 VPN 配置
---@param configTab table 配置表
---@return boolean 创建成败
---
---[查看文档](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.create)
---
function vpnconf.create(configTab) end

--- 获取当前系统 VPN 的列表
---@return table VPN列表
---
---[查看文档](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.list)
---
function vpnconf.list() end

--- 选择一个 VPN 配置
---@param displayID string 显示名或VPNID
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.select)
---
function vpnconf.select(displayID) end

--- 删除一个 VPN 配置
---@param displayID string 显示名或VPNID
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.delete)
---
function vpnconf.delete(displayID) end

--- 以当前选择的 VPN 建立连接
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.connect)
---
function vpnconf.connect() end

--- 断开当前的 VPN 连接
---@return boolean 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.disconnect)
---
function vpnconf.disconnect() end

--- 获取当前选择的 VPN 的状态
---@return table 状态描述表
---
---[查看文档](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.status)
---
function vpnconf.status() end


--------------------------------------------------------------------------------
-- 脚本包模块
--------------------------------------------------------------------------------

---@class xpp*
xpp = {}

--- 获取当前脚本包的元信息
---@return table info 元信息
---
---[查看文档](https://xxtouch.app/docs/handbook/xpp/xpp.info)
---
function xpp.info() end

--- 获取当前脚本包的包路径
---@return string path 包路径
---
---[查看文档](https://xxtouch.app/docs/handbook/xpp/xpp.bundle_path)
---
function xpp.bundle_path() end

--- 获取当前脚本包中的资源路径
---@param resourceName string 资源文件名
---@return string? path 资源路径
---
---[查看文档](https://xxtouch.app/docs/handbook/xpp/xpp.resource_path)
---
function xpp.resource_path(resourceName) end


--------------------------------------------------------------------------------
-- Web 视图模块
--------------------------------------------------------------------------------

---@class webview*
webview = {}

--- 展现一个 Web 视图
---@param opts table 选项表 {id = 视图ID, html = HTML内容, x = 原点横坐标, y = 原点纵坐标, width = 宽度, height = 高度, corner_radius = 圆角半径, alpha = 不透明度, animation_duration = 动画时间, rotate = 旋转角度, level = 窗体层级, opaque = 范围不透明, ignores_hit = 是否忽略触摸事件, can_drag = 是否能被拖动}
---
---[查看文档](https://xxtouch.app/docs/handbook/webview/webview.show)
---
function webview.show(opts) end

--- 隐藏一个 Web 视图
---@param viewID integer 视图ID
---
---[查看文档](https://xxtouch.app/docs/handbook/webview/webview.hide)
---
function webview.hide(viewID) end

--- 在一个 Web 视图上执行一段 JavaScript
---@param jsContent string JS文本
---@param viewID integer 视图ID
---@return string 执行结果文本
---
---[查看文档](https://xxtouch.app/docs/handbook/webview/webview.eval)
---
function webview.eval(jsContent, viewID) end

--- 获取一个 Web 视图的区域及层级信息
---@param viewID integer 视图ID
---@return table? 区域及层级信息表
---
---[查看文档](https://xxtouch.app/docs/handbook/webview/webview.frame)
---
function webview.frame(viewID) end

--- 销毁一个 Web 视图
---@param viewID integer 视图ID
---
---[查看文档](https://xxtouch.app/docs/handbook/webview/webview.destroy)
---
function webview.destroy(viewID) end


--------------------------------------------------------------------------------
-- 配置界面模块
--------------------------------------------------------------------------------

---@class xui*
xui = {}

--- 展示一个配置界面
---@param fileName string 配置界面文件名
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.show)
---
function xui.show(fileName) end

--- 收起正在展示的配置界面
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.dismiss)
---
function xui.dismiss() end

--- 重新加载当前正在展示的配置界面
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.reload)
---
function xui.reload() end

--- 校验并初始化配置界面配置
---@param fileName string 配置界面文件名
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.setup)
---
function xui.setup(fileName) end

--- 清除某个配置分区所有配置
---@param defaults string 配置分区
---@return boolean ok 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.clear)
---
function xui.clear(defaults) end

--- 获取配置界面上的某个配置值
---@param defaults string 配置分区
---@param key string 配置键
---@return any value 配置值
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.get)
---
function xui.get(defaults, key) end

--- 设置配置界面上的某个配置值
---@param defaults string 配置分区
---@param key string 配置键
---@param value any 配置值
---@return boolean ok 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.set)
---
function xui.set(defaults, key, value) end

--- 读取某个配置分区的全部配置
---@param defaults string 配置分区
---@return table config 配置表
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.read)
---
function xui.read(defaults) end

--- 覆盖写入配置分区的配置
---@param defaults string 配置分区
---@param config table 配置表
---@return boolean ok 操作成败
---
---[查看文档](https://xxtouch.app/docs/handbook/xui/xui.write)
---
function xui.write(defaults, config) end
