XU XUv0.13.1
EN

#xacp

导入方式: #xacp

公开 API: 58 函数, 4 方法, 11 类型, 29 常量, 0 方法集

#xacp 是随 Xu 0.13.1 SDK 发布的、与传输无关的安全核心:帧上限、XUN 校验、权限和会话生命周期。导入它不会打开控制通道。stdio 与本机回环 TCP 是运行时钩子,只有 xu build --xacp 或 --xacp-port 才会插入。

命令行:xu xacp · 常见问题 · 对应发布源码 · 开发分支协议

API 声明已对照选定发布源码审阅。下文 ui.record 有界采样契约依据开发分支协议 §7。原生 stdio/TCP 会话、UI 附着、截图和各平台验收仍为待验。

会话

open_session() 返回 STATE_NEW(0)会话,权限为 PERM_NONE,代数为 1,下一个请求 id 为 1。close_session 将其改为 STATE_CLOSED(2),增加代数,清掉活动请求并收回权限。STATE_OPEN 为 1。

同一时刻只能有一个活动请求。begin_request 检查授权,只接受正数且等于 next_id 的 id,预约后推进下一个 id。非法 id 返回 invalid_request_id;第二个活动请求返回 request_in_flight。首个请求不是 hello 时,以 hello_required 关闭会话。finish_request 检查活动 id 和代数(不匹配返回 stale_request)。成功协商的 hello 打开会话;未经协商的 hello 不能打开会话。已关闭会话返回 session_closed。

函数作用
open_session() Session新建无权限会话。
close_session(s $&Session)关闭并清空权限。
cancel_request(s $&Session)丢弃活动请求,不把会话打开。
begin_request(s $&Session, r &Request) Outcome在 authorized 允许时预约下一个单调 id。
finish_request(s $&Session, id int) Outcome释放活动 id。id 1 会打开会话。
authorized(s $&Session, r &Request) boolxacp.hello 仅在 STATE_NEW。其后的操作需要对应权限位。
dispatch(s $&Session, d &xun.Doc, l &Limits) Outcome只做核心生命周期。完成 xacp.hello,不授予 development 权限。其他已知操作在 begin 成功后返回 not_implemented;未授权时返回 permission_denied。

Hello 与权限

权限变更是宿主策略。set_permissions 只在会话仍为 STATE_NEW 时成功,并且只接受 0..15 内的位。未知位会被拒绝。请求一旦 finish,权限不再改变。

常量值操作
PERM_NONE0xacp.hello,且仅来自 STATE_NEW
PERM_INFO1proc.status
PERM_PROCESS2proc.output
PERM_UI_READ4ui.tree、ui.screenshot、ui.record
PERM_UI_MUTATE8ui.input、ui.act
PERM_ALL15development_permissions() 与 enable_development()

enable_development(s) 是等同于 set_permissions(s, PERM_ALL) 的显式宿主辅助函数,不绕过 schema 校验、会话生命周期、原生资源释放或上限。hello 完成后调用它返回 false。启动与附着服务改为读取 XU_XACP_TOKEN,在合法 hello 已 begin、尚未 finish_request 时调用 negotiate_hello。

Hello 必须提供 ver: !ver 1.0.0 和非空字符串 nonce,响应会回显 nonce。宿主未设置令牌时,即使客户端发送令牌,权限仍至多为 PERM_INFO。宿主设置令牌时,客户端 args.token 缺失或不匹配会返回 auth_failed 并关闭会话;匹配后至多允许 PERM_ALL(本 SDK 为 15)。可选的 args.permissions 是只包含已知位的 !i 掩码:实际授权为请求值与宿主允许值的交集;省略则请求宿主的全部允许值。响应包含数值 permissions 与 permission_label(none、info、development 或 custom)。

帧与上限

两种传输均使用 XACP/1\n<N>\n,紧接恰好 N 字节的纯 XUN 正文。帧头行以 LF(0x0A)结束;N 是不含帧头的正 ASCII 十进制字节数。按 UTF-8 字节计数,正文换行也计入。没有结束分隔符,帧间不添加额外分隔字节。传输层去掉前缀并读取恰好 N 字节,再调用 parse_frame(body)。该函数只接收 XUN 正文,拒绝空正文、非法 XUN 和超过 MAX_FRAME_BYTES 的正文。validate_request 要求根字典恰好包含 id、op、args;id 是正数 !i。

default_limits() 使用下列硬上限。自定义 Limits 只能更小。

常量值
MAX_FRAME_BYTES1048576(1 MiB)
MAX_STRING_BYTES65536
MAX_FIELDS64
MAX_TABLE_ROWS10000
MAX_NODE_ID16777215

consume_input 与 consume_output 拒绝负数、单次超过帧上限或累计超过会话字节预算的计数。启动期读取器对超限正文返回 frame_too_large,对帧头或正文内部的 EOF 返回 truncated_frame。帧边界上的完整 EOF 关闭会话。帧错误使用 id 0;schema 错误尽量使用有效的 id 提示,否则使用 0。帧、schema 和认证错误会关闭会话。

以下 hello 的正文为 69 字节,帧头为 10 字节(共 79 字节)。每一行都以 LF 结束,包括 nonce 行:

XACP/1
69
id: !i 1
op: xacp.hello
args:
  ver: !ver 1.0.0
  nonce: docs-client

宿主未配置令牌时,对应响应的正文为 109 字节(含帧头共 120 字节)。最后一行同样以 LF 结束。响应使用相同的长度前缀,包含 id、ok,以及 data 或 error.code(还可带 error.msg)。下一帧紧接正文开始:

XACP/1
109
id: !i 1
ok: !b true
data:
  state: OPEN
  nonce: "docs-client"
  permissions: !i 1
  permission_label: info

已知操作

schema 只允许下列操作。其余都是未知操作。

操作权限启动期控制通道
xacp.helloPERM_NONE,且仅 STATE_NEW在 finish 之前协商令牌与权限,返回 state: OPEN、回显 nonce、数值权限和权限标签。
proc.statusPERM_INFOargs 必须为空。返回真实的 os.getpid() 与 state: OPEN。
proc.outputPERM_PROCESS做 schema 校验(stream 为 stdout 或 stderr)。没有输出适配器时返回 not_implemented。
ui.treePERM_UI_READ做 schema 校验。没有 Screen 适配器时返回 not_implemented。
ui.screenshotPERM_UI_READ同上。这条通道不返回真实像素。
ui.inputPERM_UI_MUTATE同上,包括步进校验之后。
ui.actPERM_UI_MUTATE同上。schema 允许的动作名是 focus、click、set_text、set_checked。
ui.recordPERM_UI_READ同上。schema 模式为 events 与 frames。这不是启动器的 stdout record 模式。

在启动通道上,not_implemented 发生在 begin_request 之后,因此该 id 已被消耗,下一帧必须使用随后的 id。permission_denied 在 id 前进之前返回。

UI 控制需要显式的 attach_stdio 或 attach_tcp 句柄、通过 register_screen 注册的真实 ui/widgets.Screen,以及 Screen 所属协程在 UI 事件迭代之间调用 poll。这条路径中业务 main 继续运行,退出轮询循环前应注销 Screen。带类型的辅助函数(ui_tree、ui_screenshot、ui_input、ui_act 和录制辅助函数)仍要求相应权限,检查窗口/节点 id、缩放(0.1 至 4.0)、文本以及行数/事件预算。截图返回拥有所有权的 draw.Surface,调用方负责 dispose。启动期 --xacp-stdio 与 --xacp-tcp 不会注册 Screen。端到端 UI 行为仍为待验。

有界 UI 录制

注册了匹配的 Screen 时,ui.record 在单次请求内进行有界、拉取式 XAR1 采样。它要求 PERM_UI_READ、正整数 win: !i 及 mode: events|frames。Screen 所属协程启动内存中的有界 StreamWriter,同步采样,并在响应前结束录制器。可选参数如下:

参数默认值范围与含义
max_bytes: !i65536,为容纳响应可进一步缩小1..limits.max_frame_bytes;XAR1 累计字节数,包含头部与末尾 LF。
max_records: !i64至少为 1;本段最多返回的完整记录数。
duration_ms: !i00..limits.request_timeout_ms - 1;0 立即采样一次,正值限定采样窗口。

未知字段、类型错误或越界值返回 schema_error。采样之间最多休眠 10 ms,到达时长或记录数/字节预算即停止;请求排队时间会缩短可用窗口。每次成功响应包含 mode、records: !i、bytes: !i、truncated: !b 和 payload,后者为只含完整记录的带引号 XAR1 字符串。truncated=true 表示字节或记录数预算耗尽;仅到达请求的采样时长属于正常完成。为预留响应封装与字符串转义空间,有效字节预算最多为 (limits.max_frame_bytes - 256) / 2,序列化后的响应还会再次检查帧大小上限。

首条记录放不下,或接收器/快照失败时,中止录制器并返回 adapter_error。后续记录放不下则返回已经完成的记录前缀,并设置 truncated=true。响应沿用普通的 XU_XACP_WRITE_TIMEOUT_MS 帧写入期限。

events 输出标记为 state=true 的当前状态观测,包含 window、canvas、generation 与 open。Screen 没有公开的输入事件历史或订阅接口,因此这些记录不是真实输入事件日志。frames 依次调用 screen_screenshot 与 surface_record,仅导出尺寸并标记 redacted=true,不含像素;每个原生 Surface 都在继续采样前 dispose。采样不注入输入,也不要求 PERM_UI_MUTATE,不会驱动应用的 UI 事件循环或重建请求之间的事件。

客户端通过重复请求 ui.record 拉取后续片段。每段序号都从 1 开始,没有持久录制器或续传游标,每个请求仍只有一个 XACP/1 响应。没有 Screen 时返回 not_implemented;不属于该 Screen 或已关闭的窗口返回 stale_window。stream_required 仅保留给没有接收器/采样能力的适配器,内置 Screen 采样路径不会返回它。平台支持取决于已注册的 Screen 及其快照后端,包括 Windows。

库函数 start_recorder / write_record / finish_recorder 也接受其他 StreamWriter 接收器;失败时调用方必须调用 abort_recorder。具有输入源的库调用方可以写入 input_record 载荷。XAR1 片段与捕获 stdout 的 CLI xu xacp record 不同。完整录制契约见 dev 分支的 PROTOCOL.md §7。

传输钩子

src/xacp/stdio.xu 位于同一个包。--xacp 构建会在 main 开头插入 stdio_preflight(port)。那才是控制入口。普通 #xacp 导入不会发出这段启动代码。

--xacp-help 是单独的启动期打印,不是控制会话。它的 capabilities 行是 stdio。构建端口为 0 时还会打印 tcp: disabled (port 0)。正端口会打印 tcp: enabled 和 bind: 127.0.0.1:PORT。启动器模式见命令行参考。

尚未覆盖

正式 API 以对应发布源码和冒烟脚本为准,有界 UI 采样以开发分支协议 §7为准。较早的样例 README/设计说明可能记载过时的分帧、权限或超时行为。

示例代码 · API 声明

示例代码

以下源码来自官方 examples 仓库,可复制或下载。请在完整工程中使用本地 Xu SDK 运行;网络、数据库和桌面示例需要对应的服务或资源。

16_ui_webview/xacp_screen/main.xu

所需 SDK:Xu 0.10.13-dev.1 · 完整工程 · 下载源码 · events.xu

Xu本地 SDK 示例
@main

#ui
#ui/widgets
#xacp
#errors

demo #"github.com/xulang-org/examples/ui_demo"

struct Model{
    label_id int
    count int
}

fn (m $&Model) layout(s $&widgets.Screen) int {
    s.place(m.label_id, 32.0, 36.0, 540.0, 44.0) or >>
    << 0
}

fn inspect_screen(s $&widgets.Screen) int {
    $session := xacp.open_session()
    // The in-process adapter follows the current session lifecycle too.
    // This token belongs only to this local demonstration; no listener is opened.
    permissions := xacp.PERM_UI_READ | xacp.PERM_UI_MUTATE
    limits := xacp.default_limits()
    $nonces := xacp.new_nonce_registry(8, true)
    hello := xacp.parse_frame("id: !i 1\nop: xacp.hello\nargs:\n  ver: !ver 1.0.0\n  nonce: local-screen-demo\n  token: local-screen-demo\n  permissions: !i " + str(permissions) + "\n") or(err) {
        xacp.close_session($&session)
        >> err
    }
    opened := xacp.dispatch_with_token($&session, &hello, &limits, "local-screen-demo", $&nonces)
    if !opened.ok{
        xacp.close_session($&session)
        >> errors.new("xacp_screen: " + opened.err_msg)
    }
    tree := xacp.ui_tree(& * s, $&session, 2, false, 0, 32, &limits) or(err) {
        xacp.close_session($&session)
        >> err
    }
    println("XACP ui.tree: " + str(tree.nodes.len) + " visible nodes")
    for node in tree.nodes{
        println("  #" + str(node.id) + " kind=" + str(node.kind) + " " + node.text)
    }

    $snapshot := xacp.ui_screenshot(& * s, $&session, 3, 1.0, &limits) or(err) {
        xacp.close_session($&session)
        >> err
    }
    println("XACP ui.screenshot: " + str(snapshot.pixel_width) + "x" + str(snapshot.pixel_height) + " pixels")
    snapshot.dispose() or(err) {
        xacp.close_session($&session)
        >> err
    }

    _ := xacp.ui_act(& * s, $&session, 2, 4, "focus", "", false, &limits) or(err) {
        xacp.close_session($&session)
        >> err
    }
    xacp.close_session($&session)
    << 0
}

fn scene(events chan ui.Event) int {
    ready := demo.ready(events) or >>
    if ready.kind == ui.EV_EXIT{ << 0}
    $screen := widgets.screen(&ready) or >>
    screen.resize(640.0, 180.0) or >>
    label_id := screen.label("XACP Screen adapter", 22.0, false) or >>
    button_id := screen.button("Activate locally or through ui.act") or >>
    screen.place(label_id, 32.0, 36.0, 540.0, 44.0) or >>
    screen.place(button_id, 32.0, 96.0, 360.0, 40.0) or >>
    inspect_screen($&screen) or(err) {
        screen.dispose()
        >> err
    }
    $model := Model{label_id: label_id, count: 0}
    $actions := widgets.action_dispatcher(&model, &screen)
    actions.on(button_id, widgets.ACTION_ACTIVATE, activate) or >>
    actions.set_fallback(global_key)
    << widgets.run_screen_actions($&screen, events, $&model, layout_action, &actions) or >>
}

fn worker(events chan ui.Event) {
    scene(events) or(err) {demo.fail(err.msg())
        << }
}

fn launch() int {
    $app := demo.app("Xu / XACP Screen adapter", 640, 180) or >>
    xu worker(app.event_ch)
    << app.run() or >>
}

fn main() int {
    << launch() or(err) {eprintln(err.msg())
        << 1}
}

API 声明

const MAX_FRAME_BYTES

XuAPI
pub const MAX_FRAME_BYTES = 1048576

用途

常量 MAX_FRAME_BYTES,定义了相关的协议或算法配置参数。

const MAX_STRING_BYTES

XuAPI
pub const MAX_STRING_BYTES = 65536

用途

常量 MAX_STRING_BYTES,定义了相关的协议或算法配置参数。

const MAX_FIELDS

XuAPI
pub const MAX_FIELDS = 64

用途

常量 MAX_FIELDS,定义了相关的协议或算法配置参数。

const MAX_TABLE_ROWS

XuAPI
pub const MAX_TABLE_ROWS = 10000

用途

常量 MAX_TABLE_ROWS,定义了相关的协议或算法配置参数。

const MAX_NODE_ID

XuAPI
pub const MAX_NODE_ID = 16777215

用途

常量 MAX_NODE_ID,定义了相关的协议或算法配置参数。

const DEFAULT_REQUEST_TIMEOUT_MS

XuAPI
pub const DEFAULT_REQUEST_TIMEOUT_MS = 5000

用途

常量 DEFAULT_REQUEST_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const MAX_REQUEST_TIMEOUT_MS

XuAPI
pub const MAX_REQUEST_TIMEOUT_MS = 600000

用途

常量 MAX_REQUEST_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const DEFAULT_WRITE_TIMEOUT_MS

XuAPI
pub const DEFAULT_WRITE_TIMEOUT_MS = 10000

用途

常量 DEFAULT_WRITE_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const MAX_WRITE_TIMEOUT_MS

XuAPI
pub const MAX_WRITE_TIMEOUT_MS = 600000

用途

常量 MAX_WRITE_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const DEFAULT_HELLO_TIMEOUT_MS

XuAPI
pub const DEFAULT_HELLO_TIMEOUT_MS = 5000

用途

常量 DEFAULT_HELLO_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const MAX_HELLO_TIMEOUT_MS

XuAPI
pub const MAX_HELLO_TIMEOUT_MS = 600000

用途

常量 MAX_HELLO_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const DEFAULT_IDLE_TIMEOUT_MS

XuAPI
pub const DEFAULT_IDLE_TIMEOUT_MS = 60000

用途

常量 DEFAULT_IDLE_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const MIN_IDLE_TIMEOUT_MS

XuAPI
pub const MIN_IDLE_TIMEOUT_MS = 1000

用途

常量 MIN_IDLE_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const MAX_IDLE_TIMEOUT_MS

XuAPI
pub const MAX_IDLE_TIMEOUT_MS = 3600000

用途

常量 MAX_IDLE_TIMEOUT_MS,定义了相关的协议或算法配置参数。

const DEFAULT_NONCE_CACHE

XuAPI
pub const DEFAULT_NONCE_CACHE = 1024

用途

常量 DEFAULT_NONCE_CACHE,定义了相关的协议或算法配置参数。

const MAX_NONCE_CACHE

XuAPI
pub const MAX_NONCE_CACHE = 65536

用途

常量 MAX_NONCE_CACHE,定义了相关的协议或算法配置参数。

const STATE_NEW

XuAPI
pub const STATE_NEW = 0

用途

常量 STATE_NEW,定义了相关的协议或算法配置参数。

const STATE_OPEN

XuAPI
pub const STATE_OPEN = 1

用途

常量 STATE_OPEN,定义了相关的协议或算法配置参数。

const STATE_CLOSED

XuAPI
pub const STATE_CLOSED = 2

用途

常量 STATE_CLOSED,定义了相关的协议或算法配置参数。

const PERM_NONE

XuAPI
pub const PERM_NONE = 0

用途

常量 PERM_NONE,定义了相关的协议或算法配置参数。

const PERM_INFO

XuAPI
pub const PERM_INFO = 1

用途

常量 PERM_INFO,定义了相关的协议或算法配置参数。

const PERM_PROCESS

XuAPI
pub const PERM_PROCESS = 2

用途

常量 PERM_PROCESS,定义了相关的协议或算法配置参数。

const PERM_UI_READ

XuAPI
pub const PERM_UI_READ = 4

用途

常量 PERM_UI_READ,定义了相关的协议或算法配置参数。

查看用法示例

const PERM_UI_MUTATE

XuAPI
pub const PERM_UI_MUTATE = 8

用途

常量 PERM_UI_MUTATE,定义了相关的协议或算法配置参数。

查看用法示例

const PERM_UI_RAW

XuAPI
pub const PERM_UI_RAW = 16

用途

常量 PERM_UI_RAW,定义了相关的协议或算法配置参数。

const PERM_ALL

XuAPI
pub const PERM_ALL = 31

用途

常量 PERM_ALL,定义了相关的协议或算法配置参数。

struct Limits

XuAPI
pub struct Limits {
    pub max_frame_bytes int
    pub max_string_bytes int
    pub max_fields int
    pub max_table_rows int
    pub max_node_id int
    pub request_timeout_ms int
    pub write_timeout_ms int
    pub hello_timeout_ms int
    pub idle_timeout_ms int
}

用途

承载 max_frame_bytes、max_string_bytes、max_fields、max_table_rows、max_node_id 等属性的结构体。

公开字段

max_frame_bytes int
字段(int)
max_string_bytes int
字段(int)
max_fields int
字段(int)
max_table_rows int
字段(int)
max_node_id int
字段(int)
request_timeout_ms int
字段(int)
write_timeout_ms int
字段(int)
hello_timeout_ms int
字段(int)
idle_timeout_ms int
字段(int)

struct Session

XuAPI
pub struct Session {
    pub state int
    pub generation int
    pub next_id int
    pub active_id int
    pub active_generation int
    pub permissions int
    pub nonce string
    pub bytes_in int
    pub bytes_out int
}

用途

承载 state、generation、next_id、active_id、active_generation 等属性的结构体。

公开字段

state int
字段(int)
generation int
字段(int)
next_id int
字段(int)
active_id int
字段(int)
active_generation int
字段(int)
permissions int
字段(int)
nonce string
字段(string)
bytes_in int
字段(int)
bytes_out int
字段(int)

struct NonceRegistry

XuAPI
pub struct NonceRegistry {

}

用途

NonceRegistry 上下文或状态结构体。

公开字段

此类型没有公开字段。

new_nonce_registry

XuAPI
pub fn new_nonce_registry(capacity int, enabled bool) NonceRegistry

用途

构造 nonce registry。

参数

capacity int
capacity(int)
enabled bool
enabled(bool)

返回值

NonceRegistry — 该类型的值

查看用法示例

struct Request

XuAPI
pub struct Request {
    pub id int
    pub op string
    pub args int
}

用途

承载 id、op、args 等属性的结构体。

公开字段

id int
字段(int)
op string
字段(string)
args int
可变实参

struct Outcome

XuAPI
pub struct Outcome {
    pub ok bool
    pub request_id int
    pub err_code string
    pub err_msg string
}

用途

承载 ok、request_id、err_code、err_msg 等属性的结构体。

公开字段

ok bool
字段(bool)
request_id int
字段(int)
err_code string
字段(string)
err_msg string
字段(string)

default_limits

XuAPI
pub fn default_limits() Limits

用途

执行 default limits 操作。

参数

无需传入参数。

返回值

Limits — 该类型的值

查看用法示例

request_timeout_from_env

XuAPI
pub fn request_timeout_from_env() int

用途

执行 request timeout from env 操作。

参数

无需传入参数。

返回值

int — 该类型的值

write_timeout_from_env

XuAPI
pub fn write_timeout_from_env() int

用途

执行 write timeout from env 操作。

参数

无需传入参数。

返回值

int — 该类型的值

hello_timeout_from_env

XuAPI
pub fn hello_timeout_from_env() int

用途

执行 hello timeout from env 操作。

参数

无需传入参数。

返回值

int — 该类型的值

idle_timeout_from_env

XuAPI
pub fn idle_timeout_from_env() int

用途

执行 idle timeout from env 操作。

参数

无需传入参数。

返回值

int — 该类型的值

nonce_cache_from_env

XuAPI
pub fn nonce_cache_from_env() int

用途

执行 nonce cache from env 操作。

参数

无需传入参数。

返回值

int — 该类型的值

nonce_replay_from_env

XuAPI
pub fn nonce_replay_from_env() bool

用途

执行 nonce replay from env 操作。

参数

无需传入参数。

返回值

bool — 是否成立

open_session

XuAPI
pub fn open_session() Session

用途

执行 open session 操作。

参数

无需传入参数。

返回值

Session — 该类型的值

查看用法示例

close_session

XuAPI
pub fn close_session(s $&Session)

用途

执行 close session 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)

返回值

不返回值。

查看用法示例

cancel_request

XuAPI
pub fn cancel_request(s $&Session)

用途

取消请求。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)

返回值

不返回值。

set_permissions

XuAPI
pub fn set_permissions(s $&Session, permissions int) bool

用途

设置 permissions。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
permissions int
permissions(int)

返回值

bool — 是否成立

development_permissions

XuAPI
pub fn development_permissions() int

用途

执行 development permissions 操作。

参数

无需传入参数。

返回值

int — 该类型的值

enable_development

XuAPI
pub fn enable_development(s $&Session) bool

用途

执行 enable development 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)

返回值

bool — 是否成立

parse_frame

XuAPI
pub fn parse_frame(src string) xun.Doc

用途

解析一个 XACP/1 帧的纯 XUN 正文。传输层已去掉 XACP/1\n<N>\n 长度前缀并读取恰好 N 字节;本函数只接收正文。空正文、超过 MAX_FRAME_BYTES 或非法 XUN 时抛出错误。

参数

src string
传输层解码后的纯 XUN 正文,不含长度前缀

返回值

解析后的 XUN 文档;请求 schema 由 validate_request 另行校验

查看用法示例

request_id_hint

XuAPI
pub fn request_id_hint(d &xun.Doc) int

用途

执行 request id hint 操作。

参数

d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)

返回值

int — 该类型的值

validate_request

XuAPI
pub fn validate_request(d &xun.Doc, l &Limits) Request

用途

执行 validate request 操作。失败时抛出错误,调用方需处理或继续传播。

参数

d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

Request — 该类型的值

authorized

XuAPI
pub fn authorized(s $&Session, r &Request) bool

用途

执行 authorized 处理。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
r &Request
rune(Unicode 码点)(只读借用,调用方仍持有原值;类型 &Request)

返回值

bool — 是否成立

begin_request

XuAPI
pub fn begin_request(s $&Session, r &Request) Outcome

用途

执行 begin request 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
r &Request
rune(Unicode 码点)(只读借用,调用方仍持有原值;类型 &Request)

返回值

Outcome — 该类型的值

finish_request

XuAPI
pub fn finish_request(s $&Session, id int) Outcome

用途

执行 finish request 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
id int
id(int)

返回值

Outcome — 该类型的值

consume_input

XuAPI
pub fn consume_input(s $&Session, n int, l &Limits) bool

用途

执行 consume input 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
n int
数量、长度或上限(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

bool — 是否成立

consume_output

XuAPI
pub fn consume_output(s $&Session, n int, l &Limits) bool

用途

执行 consume output 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
n int
数量、长度或上限(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

bool — 是否成立

check_window

XuAPI
pub fn check_window(start int, count int, total int, l &Limits) bool

用途

执行 check window 操作。

参数

start int
start(int)
count int
count(int)
total int
total(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

bool — 是否成立

check_node

XuAPI
pub fn check_node(node int, l &Limits) bool

用途

执行 check node 操作。

参数

node int
node(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

bool — 是否成立

negotiate_hello

XuAPI
pub fn negotiate_hello(s $&Session, d &xun.Doc, r &Request, expected_token string, nonces $&NonceRegistry) Outcome

用途

执行 negotiate hello 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)
r &Request
rune(Unicode 码点)(只读借用,调用方仍持有原值;类型 &Request)
expected_token string
expected_token(string)
nonces $&NonceRegistry
nonces(独占借用,可修改原值;类型 $&NonceRegistry)

返回值

Outcome — 该类型的值

dispatch

XuAPI
pub fn dispatch(s $&Session, d &xun.Doc, l &Limits, nonces $&NonceRegistry) Outcome

用途

执行 dispatch 处理。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)
nonces $&NonceRegistry
nonces(独占借用,可修改原值;类型 $&NonceRegistry)

返回值

Outcome — 该类型的值

dispatch_with_token

XuAPI
pub fn dispatch_with_token(s $&Session, d &xun.Doc, l &Limits, expected_token string, nonces $&NonceRegistry) Outcome

用途

执行 dispatch with token 操作。

参数

s $&Session
s(独占借用,可修改原值;类型 $&Session)
d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)
expected_token string
expected_token(string)
nonces $&NonceRegistry
nonces(独占借用,可修改原值;类型 $&NonceRegistry)

返回值

Outcome — 该类型的值

查看用法示例

struct ControlReply

XuAPI
pub struct ControlReply {
    pub outcome Outcome
    pub data string
}

用途

承载 outcome、data 等属性的结构体。

公开字段

outcome Outcome
字段(Outcome)
data string
数据

struct ControlJob

XuAPI
pub struct ControlJob {
    pub id int
    pub op string
    pub body string
    pub permissions int
    pub generation int
    pub started int
    pub timeout_ms int
    pub reply chan ControlReply
}

用途

承载 id、op、body、permissions、generation 等属性的结构体。

公开字段

id int
字段(int)
op string
字段(string)
body string
正文
permissions int
字段(int)
generation int
字段(int)
started int
字段(int)
timeout_ms int
字段(int)
reply chan ControlReply
字段(通道;类型 chan ControlReply)

struct ScreenControl

XuAPI
pub struct ScreenControl {
    pub done chan int
}

用途

承载 done 等属性的结构体。

公开字段

done chan int
字段(通道;类型 chan int)

attach_stdio

XuAPI
pub fn attach_stdio() ScreenControl

用途

执行 attach stdio 操作。

参数

无需传入参数。

返回值

ScreenControl — 该类型的值

attach_tcp

XuAPI
pub fn attach_tcp(port int) ScreenControl

用途

执行 attach tcp 操作。失败时抛出错误,调用方需处理或继续传播。

参数

port int
端口(int)

返回值

ScreenControl — 该类型的值

register_screen

XuAPI
pub fn register_screen(control $&ScreenControl,s &widgets.Screen) int

用途

执行 register screen 操作。失败时抛出错误,调用方需处理或继续传播。

参数

control $&ScreenControl
control(独占借用,可修改原值;类型 $&ScreenControl)
s &widgets.Screen
s(只读借用,调用方仍持有原值;类型 &widgets.Screen)

返回值

int — 该类型的值

unregister_screen

XuAPI
pub fn unregister_screen(control $&ScreenControl)

用途

执行 unregister screen 操作。

参数

control $&ScreenControl
control(独占借用,可修改原值;类型 $&ScreenControl)

返回值

不返回值。

poll

XuAPI
pub fn poll(control $&ScreenControl,s $&widgets.Screen) bool

用途

执行 poll 处理。

参数

control $&ScreenControl
control(独占借用,可修改原值;类型 $&ScreenControl)
s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)

返回值

bool — 是否成立

struct RecordBuffer

XuAPI
pub struct RecordBuffer {

}

用途

RecordBuffer 上下文或状态结构体。

公开字段

此类型没有公开字段。

record_buffer

XuAPI
pub fn record_buffer(max_bytes int) RecordBuffer

用途

执行 record buffer 操作。失败时抛出错误,调用方需处理或继续传播。

参数

max_bytes int
max_bytes(int)

返回值

RecordBuffer — 该类型的值

($&RecordBuffer) write_str

XuAPI
pub fn (b $&RecordBuffer) write_str(data string) int

用途

$&RecordBuffer 上的操作:写入字符串。失败时抛出错误,调用方需处理或继续传播。

参数

b $&RecordBuffer
本次调用使用的 RecordBuffer 实例;以独占借用传入,方法可修改它,调用方仍持有实例。
data string
数据(string)

返回值

int — 该类型的值

(&RecordBuffer) text

XuAPI
pub fn (b &RecordBuffer) text() string

用途

&RecordBuffer 上的操作:返回当前文本。

参数

b &RecordBuffer
本次调用使用的 RecordBuffer 实例;以只读借用传入,调用方仍持有实例。

返回值

string — 结果字符串

const MAX_SCREENSHOT_BYTES

XuAPI
pub const MAX_SCREENSHOT_BYTES = 33554432

用途

常量 MAX_SCREENSHOT_BYTES,定义了相关的协议或算法配置参数。

screenshot_dir

XuAPI
pub fn screenshot_dir() string

用途

执行 screenshot dir 操作。失败时抛出错误,调用方需处理或继续传播。

参数

无需传入参数。

返回值

string — 结果字符串

program_preflight

XuAPI
pub fn program_preflight(port int)

用途

执行 program preflight 操作。

参数

port int
端口(int)

返回值

不返回值。

stdio_preflight

XuAPI
pub fn stdio_preflight(port int)

用途

执行 stdio preflight 操作。

参数

port int
端口(int)

返回值

不返回值。

const MAX_ERROR_MSG_BYTES

XuAPI
pub const MAX_ERROR_MSG_BYTES = 256

用途

常量 MAX_ERROR_MSG_BYTES,定义了相关的协议或算法配置参数。

serve_stdio

XuAPI
pub fn serve_stdio() int

用途

执行 serve stdio 操作。失败时抛出错误,调用方需处理或继续传播。

参数

无需传入参数。

返回值

int — 该类型的值

serve_tcp

XuAPI
pub fn serve_tcp(port int) int

用途

执行 serve tcp 操作。失败时抛出错误,调用方需处理或继续传播。

参数

port int
端口(int)

返回值

int — 该类型的值

const MAX_UI_EVENTS

XuAPI
pub const MAX_UI_EVENTS = 512

用途

常量 MAX_UI_EVENTS,定义了相关的协议或算法配置参数。

struct Recorder

XuAPI
pub struct Recorder {
    pub mode string
    pub max_bytes int
    pub bytes int
    pub sequence int
    pub closed bool
    pub request_id int
    pub session_generation int
}

用途

承载 mode、max_bytes、bytes、sequence、closed 等属性的结构体。

公开字段

mode string
模式
max_bytes int
字段(int)
bytes int
字段(int)
sequence int
字段(int)
closed bool
字段(bool)
request_id int
字段(int)
session_generation int
字段(int)

new_recorder

XuAPI
pub fn new_recorder(mode string,max_bytes int,l &Limits) Recorder

用途

构造 recorder。失败时抛出错误,调用方需处理或继续传播。

参数

mode string
模式(string)
max_bytes int
max_bytes(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

Recorder — 该类型的值

($&Recorder) close

XuAPI
pub fn (r $&Recorder) close()

用途

$&Recorder 上的操作:关闭资源。

参数

r $&Recorder
本次调用使用的 Recorder 实例;以独占借用传入,方法可修改它,调用方仍持有实例。

返回值

不返回值。

(&Recorder) is_open

XuAPI
pub fn (r &Recorder) is_open() bool

用途

&Recorder 上的操作:判断是否 open。

参数

r &Recorder
本次调用使用的 Recorder 实例;以只读借用传入,调用方仍持有实例。

返回值

bool — 是否成立

write_record

XuAPI
pub fn write_record#W:StreamWriter(r $&Recorder,sink $&W,kind string,data string) int

用途

执行 write record 操作。失败时抛出错误,调用方需处理或继续传播。

参数

r $&Recorder
rune(Unicode 码点)(独占借用,可修改原值;类型 $&Recorder)
sink $&W
sink(独占借用,可修改原值;类型 $&W)
kind string
类型标签(string)
data string
数据(string)

返回值

int — 该类型的值

input_record

XuAPI
pub fn input_record(event &ui.InputEvent) string

用途

执行 input record 操作。

参数

event &ui.InputEvent
event(只读借用,调用方仍持有原值;类型 &ui.InputEvent)

返回值

string — 结果字符串

surface_record

XuAPI
pub fn surface_record(surface &draw.Surface) string

用途

执行 surface record 操作。

参数

surface &draw.Surface
surface(只读借用,调用方仍持有原值;类型 &draw.Surface)

返回值

string — 结果字符串

struct TreeWindow

XuAPI
pub struct TreeWindow {
    pub start int
    pub total int
    pub nodes []widgets.ScreenNodeInfo
}

用途

承载 start、total、nodes 等属性的结构体。

公开字段

start int
字段(int)
total int
字段(int)
nodes []widgets.ScreenNodeInfo
字段([]widgets.ScreenNodeInfo)

screen_tree

XuAPI
pub fn screen_tree(s $&widgets.Screen,include_hidden bool,start int,max_rows int,l &Limits) TreeWindow

用途

执行 screen tree 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
include_hidden bool
include_hidden(bool)
start int
start(int)
max_rows int
max_rows(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

TreeWindow — 该类型的值

screen_screenshot

XuAPI
pub fn screen_screenshot(s $&widgets.Screen,scale f64) draw.Surface

用途

执行 screen screenshot 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
scale f64
scale(f64)

返回值

draw.Surface — 该类型的值

screen_screenshot_node

XuAPI
pub fn screen_screenshot_node(s $&widgets.Screen,node int,scale f64,l &Limits) draw.Surface

用途

执行 screen screenshot node 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
node int
node(int)
scale f64
scale(f64)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

draw.Surface — 该类型的值

screen_input

XuAPI
pub fn screen_input(s $&widgets.Screen,events &[]ui.InputEvent,l &Limits) []widgets.Action

用途

执行 screen input 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
events &[]ui.InputEvent
events(只读借用,调用方仍持有原值;类型 &[]ui.InputEvent)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

[]widgets.Action — 切片结果

screen_input_request

XuAPI
pub fn screen_input_request(s $&widgets.Screen,d &xun.Doc,args int,l &Limits) []widgets.Action

用途

执行 screen input request 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)
args int
可变实参(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

[]widgets.Action — 切片结果

screen_act

XuAPI
pub fn screen_act(s $&widgets.Screen,id int,act string,text string,checked bool,l &Limits) []widgets.Action

用途

执行 screen act 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
id int
id(int)
act string
act(string)
text string
文本(string)
checked bool
checked(bool)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

[]widgets.Action — 切片结果

start_recorder

XuAPI
pub fn start_recorder(session $&Session,id int,mode string,max_bytes int,l &Limits) Recorder

用途

启动记录器。失败时抛出错误,调用方需处理或继续传播。

参数

session $&Session
session(独占借用,可修改原值;类型 $&Session)
id int
id(int)
mode string
模式(string)
max_bytes int
max_bytes(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

Recorder — 该类型的值

finish_recorder

XuAPI
pub fn finish_recorder(session $&Session,r $&Recorder) int

用途

执行 finish recorder 操作。失败时抛出错误,调用方需处理或继续传播。

参数

session $&Session
session(独占借用,可修改原值;类型 $&Session)
r $&Recorder
rune(Unicode 码点)(独占借用,可修改原值;类型 $&Recorder)

返回值

int — 该类型的值

abort_recorder

XuAPI
pub fn abort_recorder(session $&Session,r $&Recorder)

用途

执行 abort recorder 操作。

参数

session $&Session
session(独占借用,可修改原值;类型 $&Session)
r $&Recorder
rune(Unicode 码点)(独占借用,可修改原值;类型 $&Recorder)

返回值

不返回值。

ui_tree

XuAPI
pub fn ui_tree(s $&widgets.Screen,session $&Session,id int,include_hidden bool,start int,max_rows int,l &Limits) TreeWindow

用途

执行 ui tree 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
session $&Session
session(独占借用,可修改原值;类型 $&Session)
id int
id(int)
include_hidden bool
include_hidden(bool)
start int
start(int)
max_rows int
max_rows(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

TreeWindow — 该类型的值

查看用法示例

ui_screenshot

XuAPI
pub fn ui_screenshot(s $&widgets.Screen,session $&Session,id int,scale f64,l &Limits) draw.Surface

用途

执行 ui screenshot 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
session $&Session
session(独占借用,可修改原值;类型 $&Session)
id int
id(int)
scale f64
scale(f64)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

draw.Surface — 该类型的值

查看用法示例

ui_screenshot_node

XuAPI
pub fn ui_screenshot_node(s $&widgets.Screen,session $&Session,id int,node int,scale f64,l &Limits) draw.Surface

用途

执行 ui screenshot node 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
session $&Session
session(独占借用,可修改原值;类型 $&Session)
id int
id(int)
node int
node(int)
scale f64
scale(f64)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

draw.Surface — 该类型的值

ui_input

XuAPI
pub fn ui_input(s $&widgets.Screen,session $&Session,id int,events &[]ui.InputEvent,l &Limits) []widgets.Action

用途

执行 ui input 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
session $&Session
session(独占借用,可修改原值;类型 $&Session)
id int
id(int)
events &[]ui.InputEvent
events(只读借用,调用方仍持有原值;类型 &[]ui.InputEvent)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

[]widgets.Action — 切片结果

ui_input_request

XuAPI
pub fn ui_input_request(s $&widgets.Screen,session $&Session,id int,d &xun.Doc,args int,l &Limits) []widgets.Action

用途

执行 ui input request 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
session $&Session
session(独占借用,可修改原值;类型 $&Session)
id int
id(int)
d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)
args int
可变实参(int)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

[]widgets.Action — 切片结果

ui_act

XuAPI
pub fn ui_act(s $&widgets.Screen,session $&Session,id int,request_id int,act string,text string,checked bool,l &Limits) []widgets.Action

用途

执行 ui act 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
session $&Session
session(独占借用,可修改原值;类型 $&Session)
id int
id(int)
request_id int
request_id(int)
act string
act(string)
text string
文本(string)
checked bool
checked(bool)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)

返回值

[]widgets.Action — 切片结果

查看用法示例

dispatch_screen

XuAPI
pub fn dispatch_screen(s $&widgets.Screen,session $&Session,d &xun.Doc,l &Limits,nonces $&NonceRegistry) ControlReply

用途

执行 dispatch screen 操作。失败时抛出错误,调用方需处理或继续传播。

参数

s $&widgets.Screen
s(独占借用,可修改原值;类型 $&widgets.Screen)
session $&Session
session(独占借用,可修改原值;类型 $&Session)
d &xun.Doc
d(只读借用,调用方仍持有原值;类型 &xun.Doc)
l &Limits
l(只读借用,调用方仍持有原值;类型 &Limits)
nonces $&NonceRegistry
nonces(独占借用,可修改原值;类型 $&NonceRegistry)

返回值

ControlReply — 该类型的值