Native 运行时

Native 运行时通过动态库暴露 capability 方法，适合平台相关或性能敏感任务。能力声明、权限模型和 HostGateway 调用仍然与 JS、WASM 一致。

动态库入口

Native 运行时至少需要导出 plugin_invoke 和释放函数；需要宿主数据时，通过 plugin_set_host_api 接收 Host API，再调用 host_invoke。

#[repr(C)]
pub struct TingNativeHostApi {
    pub version: u32,
    pub host_invoke: Option<unsafe extern "C" fn(
        method: *const u8,
        params_json: *const u8,
        result_json: *mut *mut u8,
    ) -> i32>,
    pub host_free: Option<unsafe extern "C" fn(ptr: *mut u8)>,
}

#[no_mangle]
pub unsafe extern "C" fn plugin_set_host_api(api: *const TingNativeHostApi) -> i32 {
    // Store the host API pointer after checking version.
    0
}

#[no_mangle]
pub unsafe extern "C" fn plugin_invoke(
    method: *const u8,
    params: *const u8,
    result_ptr: *mut *mut u8,
) -> i32 {
    // Decode method and JSON params, then dispatch by capability.invoke.
    0
}

Host API

host_invoke(method, params_json, result_json) 返回 JSON 字符串，方法名与 HostGateway 一致。调用依赖当前认证用户上下文；公共路由、初始化和无用户上下文的后台场景可能被拒绝。

规则	说明
权限	manifest 必须声明对应 permission
用户	读取书籍、进度、库文件时必须有当前用户
管理员	`metadata.write`、`database.update`、`library.file.write` 需要管理员上下文
内存	插件分配给宿主的字符串必须提供释放函数

能力示例

Native 运行时常用于 format_handler，例如格式探测、播放 URL 生成、流式解密或调用系统媒体库。

runtime: native
entry_point: libting_format.so
capabilities:
  - id: format.decrypt
    kind: format_handler
    invoke: handleFormat
    matches:
      extensions: [m4b, encrypted-audio]
permissions:
  - type: media_read
  - type: file_read

平台包

标识	环境
windows-x86_64	Windows 桌面或服务器
linux-x86_64	Linux 服务器、Intel/AMD NAS
linux-aarch64	ARM NAS、树莓派、ARM 云主机
macos-x86_64	Intel Mac
macos-aarch64	Apple Silicon Mac

发布 Native 运行时插件时通常按平台分别构建 .tr 包，并让插件商店按平台返回对应下载地址。

适合 Native 的场景

格式解码、流式解密、音频标签读写。
调用 FFmpeg、FFprobe 或系统原生库。
需要平台二进制依赖或高性能 I/O 的工具能力。

← 上一篇WASM 运行时