API 参考

本节详细介绍了 KossJS 的 API 接口、数据结构和用法。

核心概念

KossInstance

KossJS 中的每个 JS 实例都是完全隔离的虚拟机 (VM)，互不影响。您可以创建任意数量的实例。

KossResult

大多数 API 函数返回 KossResult 结构体：

typedef struct {
    int code;       /* 0=ok, 1=js error, 2=bad argument */
    char *value;    /* heap string — free with koss_free_string */
} KossResult;

code	含义
0	成功
1	JavaScript 执行错误
2	无效参数

KossNativeFn

原生函数回调类型：

typedef char* (*KossNativeFn)(int argc, const char **argv);

KossCapability（能力位掩码）

KossJS 使用位掩码控制每个实例的可用能力（沙箱机制）。详见安全与沙箱指南。

typedef enum {
    KOSS_CAP_FS              = 1 << 0,  // 文件系统
    KOSS_CAP_NET             = 1 << 1,  // 网络
    KOSS_CAP_CRYPTO          = 1 << 2,  // 加密
    KOSS_CAP_WORKER          = 1 << 3,  // Worker 线程池
    KOSS_CAP_EXTERNAL_LOADER = 1 << 4,  // 外部模块加载器
} KossCapability;

#define KOSS_CAP_SANDBOX 0
#define KOSS_CAP_ALL     (KOSS_CAP_FS | KOSS_CAP_NET | KOSS_CAP_CRYPTO \
                          | KOSS_CAP_WORKER | KOSS_CAP_EXTERNAL_LOADER)

C ABI 函数列表

实例生命周期

函数名	功能描述
koss_create	创建新的 JS 实例（全部能力）
koss_create_with_caps	按能力位掩码创建实例
koss_create_with_modules	创建支持模块加载的 JS 实例
koss_create_with_modules_and_caps	创建支持模块加载 + 能力控制的实例
koss_destroy	销毁 JS 实例并释放内存
koss_get_capabilities	查询实例当前能力集（只读）

代码执行

函数名	功能描述
koss_eval	执行 JavaScript 代码并返回结果
koss_run_file	执行 JavaScript 文件
koss_run_module	执行 ES Module 文件
koss_run_string	执行 JavaScript 代码字符串
koss_run_module_string	执行 ES Module 代码字符串

异步执行 & 事件循环

函数名	功能描述
koss_run_async	执行异步代码并驱动事件循环直到完成或超时
koss_tick	运行事件循环的单次迭代

全局变量注入

函数名	功能描述
koss_set_global_string	设置全局字符串变量
koss_set_global_number	设置全局数字变量
koss_set_global_bool	设置全局布尔变量
koss_set_global_null	设置全局 null 变量
koss_set_global_undefined	设置全局 undefined 变量
koss_set_global_json	设置全局 JSON 对象/数组

原生函数 / 类注册

函数名	功能描述
koss_register_function	注册可从 JS 调用的原生函数
koss_register_class	注册支持 `new` 关键字的 JS 类
koss_register_module_loader	注册模块加载器

Worker 线程池

函数名	功能描述
koss_create_worker_pool	创建指定大小的 Worker 线程池
koss_worker_post_message	向指定 Worker 发送消息
koss_worker_execute	在 Worker 线程上执行代码
koss_worker_try_recv	非阻塞收取 Worker 消息/结果
koss_worker_terminate	终止指定 Worker
koss_worker_shutdown	关闭全部 Worker 线程池

Fetch & 内部绑定

函数名	功能描述
koss_fetch	执行 HTTP 请求
koss_get_binding	获取内部 Rust 绑定信息（调试用）

内存管理

函数名	功能描述
koss_free_string	释放字符串内存
koss_free_result	释放 KossResult 内存

信息获取

函数名	功能描述
koss_version	获取 KossJS 版本字符串

函数详情链接

详细文档请参阅各函数页面：

使用示例

C 语言

#include <stdio.h>
#include "kossjs.h"

int main() {
    KossInstance* inst = koss_create();
    if (!inst) {
        fprintf(stderr, "Failed to create instance\n");
        return 1;
    }

    KossResult result = koss_eval(inst, "1 + 2");
    if (result.code == 0) {
        printf("Result: %s\n", result.value);
        koss_free_result(result);
    }

    koss_destroy(inst);
    return 0;
}

Python

python

from kossjs_interface import KossJS

with KossJS() as koss:
    result = koss.eval("'Hello ' + 'World'")
    print(result)

如需了解各个函数的详细信息，请点击上方链接查看各函数文档。

API 参考 ​

核心概念 ​

KossInstance ​

KossResult ​

KossNativeFn ​

KossCapability（能力位掩码） ​

C ABI 函数列表 ​

实例生命周期 ​

代码执行 ​

异步执行 & 事件循环 ​

全局变量注入 ​

原生函数 / 类注册 ​

Worker 线程池 ​

Fetch & 内部绑定 ​

内存管理 ​

信息获取 ​

函数详情链接 ​

使用示例 ​

C 语言 ​

Python ​