> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arkffi.hmbill.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 原始 NAPI 桥接

> 底层 NAPI 函数的直接访问

原始桥接提供对 `liblibrary.so` 导出的 NAPI 函数的直接访问。

## 导入

```typescript theme={null}
import ffi from 'liblibrary.so';
```

## API 参考

### `load()`

```typescript theme={null}
function load(libName: string): bigint;
```

调用 `dlopen()` 打开库。返回 `bigint` 句柄。

```typescript theme={null}
const handle = ffi.load('libffi_target.so');
```

### `close()`

```typescript theme={null}
function close(handle: bigint): void;
```

调用 `dlclose()` 释放库句柄。

### `defineFunction()`

```typescript theme={null}
function defineFunction(handle: bigint, funcName: string, argTypes: string, returnType: string): void;
```

通过 `dlsym()` 解析函数并注册类型签名。

```typescript theme={null}
ffi.defineFunction(handle, 'add', 'dd', 'd');
```

### `callBySig()`

```typescript theme={null}
function callBySig(handle: bigint, funcName: string, numArgs: number[], strArgs: string[]): number;
```

调用之前注册的函数。

```typescript theme={null}
ffi.callBySig(handle, 'add', [2.0, 3.0], []);
```

### `callMixed()`

```typescript theme={null}
function callMixed(handle: bigint, funcName: string, argTypes: string, returnType: string, numArgs: number[], strArgs: string[]): number;
```

一站式调用——`dlsym()` 和类型分发合并为一次调用。

```typescript theme={null}
ffi.callMixed(handle, 'compute', 'ids', 'd', [0, 4.0], ['square']);
```

### `callString()`

```typescript theme={null}
function callString(handle: bigint, funcName: string): string;
```

调用返回 `const char*` 的 C 函数。

```typescript theme={null}
ffi.callString(handle, 'getVersion'); // → "1.0.0"
```

### `readCString()`

```typescript theme={null}
function readCString(ptr: number): string;
```

从原始指针读取 null 结尾的 C 字符串。

### `callPtr()`

```typescript theme={null}
function callPtr(ptr: number, argTypes: string, returnType: string, numArgs: number[], strArgs: string[]): number;
```

通过原始函数指针调用，跳过 `dlsym()`。

### `callPtrAsync()`

```typescript theme={null}
function callPtrAsync(ptr: number, argTypes: string, returnType: string, numArgs: number[], strArgs: string[]): Promise<number>;
```

`callPtr` 的异步版本，在 libuv 工作线程上执行调用，返回 Promise 不阻塞 JS 线程。

```typescript theme={null}
ffi.callPtrAsync(addPtr, 'dd', 'd', [2.0, 3.0], []).then(r => console.log(r));
```

### `getSymbolPtr()`

```typescript theme={null}
function getSymbolPtr(handle: bigint, funcName: string): number;
```

返回符号的原始函数指针。

### `createCallback()`

```typescript theme={null}
function createCallback(callback: Function, argTypes: string, returnType: string, threadsafe?: boolean): number;
```

将 ArkTS 函数存入回调注册表。返回槽位句柄。

### `destroyCallback()`

```typescript theme={null}
function destroyCallback(handle: number): void;
```

从注册表移除回调。

### `invokeCallback()`

```typescript theme={null}
function invokeCallback(handle: number, ...args: any[]): any;
```

通过句柄调用已存储的回调。

### `getCallbackThreadsafe()`

```typescript theme={null}
function getCallbackThreadsafe(handle: number): boolean;
```

返回回调是否为线程安全模式。

### `getCallbackPtr()`

```typescript theme={null}
function getCallbackPtr(handle: number): number;
```

返回回调的函数指针。

* 非线程安全：返回槽位句柄（小整数）
* 线程安全：返回真实的可执行蹦床函数地址

### `callCallbackThreadSafe()`

```typescript theme={null}
function callCallbackThreadSafe(handle: number, arg: number): void;
```

通过 TSFN（线程安全函数）路径调用回调，用于验证线程安全机制。

### `ptr()`

```typescript theme={null}
function ptr(buffer: ArrayBuffer | TypedArray): number;
```

获取 ArrayBuffer 或 TypedArray 的底层内存指针。

```typescript theme={null}
const buf = new ArrayBuffer(256);
const p = ffi.ptr(buf); // → 内存地址
```