SenRi FFI

Appearance

快速开始 ​

简介 ​

SenRi FFI 是一个统一 FFI 库，让您在 KossJS、Node.js 和 Bun 上使用同一套 API 调用原生 C 动态库。

本文档将指导您如何安装和使用 SenRi FFI。

安装 ​

bash
npm install senri_ffi

Node.js 额外步骤 ​

在 Node.js 上，还需要安装 koffi：

bash
npm install koffi

KossJS 和 Bun 无需额外依赖，它们内置了 FFI 支持。

第一个示例 ​

加载原生库并调用 abs 函数：

ts
import { Library, types } from 'senri_ffi';

// 加载原生库（自动根据平台选择）
const lib = Library.load(
  process.platform === 'win32' ? 'user32.dll' : 'libm.so.6'
);

// 绑定 C 函数
const abs = lib.func('abs', types.int32, [types.int32]);

// 调用 C 函数
console.log(abs(-42)); // 输出: 42

// 关闭库释放资源
lib.close();

跨平台示例 ​

Windows — 调用 MessageBox ​

ts
import { Library, types } from 'senri_ffi';

const user32 = Library.load('user32.dll');

const MessageBoxW = user32.func(
  'MessageBoxW',
  types.int32,
  [types.pointer, types.cstring, types.cstring, types.uint32]
);

MessageBoxW(null, 'Hello from SenRi FFI!', '标题', 0);
user32.close();

Linux / macOS — 调用数学函数 ​

ts
import { Library, types } from 'senri_ffi';

const libm = Library.load(
  process.platform === 'darwin' ? 'libm.dylib' : 'libm.so.6'
);

const sqrt = libm.func('sqrt', types.float64, [types.float64]);
console.log(sqrt(16)); // 输出: 4

const pow = libm.func('pow', types.float64, [types.float64, types.float64]);
console.log(pow(2, 10)); // 输出: 1024

libm.close();

基本概念 ​

类型系统 ​

SenRi FFI 提供了一套统一的 C 类型名称：

类型大小说明
types.void0无返回值
types.int8 / types.uint818 位整数
types.int16 / types.uint16216 位整数
types.int32 / types.uint32432 位整数
types.int64 / types.uint64864 位整数 (BigInt)
types.float32432 位浮点数
types.float64864 位浮点数
types.pointer8指针
types.cstring8C 字符串 (指针)

复合类型 ​

ts
import { pointer, array } from 'senri_ffi';

pointer(types.int32);       // 指向 int32 的指针
array(types.uint8, 256);    // uint8[256]

内存管理 ​

ts
import { alloc, free, addressOf } from 'senri_ffi';

// 手动分配内存
const mem = alloc(128);
mem.writeInt32(0, 42);
free(mem);

// 从 ArrayBuffer 获取指针
const buf = new ArrayBuffer(16);
const ptr = addressOf(buf);

运行时确认 ​

你可以通过以下代码确认当前使用的运行时：

ts
// KossJS
typeof globalThis._senri_ffi !== 'undefined' && globalThis._senri_ffi

// Bun
typeof Bun !== 'undefined' && Bun.ffi

// Node.js
typeof process !== 'undefined' && process.versions && process.versions.node

SenRi FFI 会在模块加载时自动检测并选择正确的后端。

下一步: