> ## 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); // → 內存地址
```