> ## 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.

# Raw NAPI Bridge

> Direct access to the underlying NAPI functions

The raw bridge provides direct access to the NAPI functions exported from `liblibrary.so`.

## Import

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

## API Reference

### `load()`

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

Calls `dlopen()` on the given library. Returns a `bigint` handle.

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

### `close()`

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

Calls `dlclose()` on the library handle.

### `defineFunction()`

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

Resolves a function via `dlsym()` and registers its type signature.

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

### `callBySig()`

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

Calls a previously registered function.

```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;
```

One-shot call — `dlsym()` + type dispatch in a single call.

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

### `callString()`

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

Calls a C function returning `const char*`.

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

### `readCString()`

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

Reads a null-terminated C string from a raw pointer.

### `callPtr()`

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

Calls a function by its raw pointer, skipping `dlsym()`.

### `callPtrAsync()`

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

Async version of `callPtr` — executes on a libuv worker thread and returns a Promise without blocking the JS thread.

```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;
```

Returns the raw function pointer for a symbol.

### `createCallback()`

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

Stores a TS function in the callback registry. Returns a slot handle.

### `destroyCallback()`

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

Removes a callback from the registry.

### `invokeCallback()`

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

Invokes a stored callback by its handle.

### `getCallbackThreadsafe()`

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

Returns whether the callback is thread-safe.

### `getCallbackPtr()`

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

Returns the callback function pointer.

* Non-threadsafe: returns the slot handle
* Threadsafe: returns a real executable trampoline address

### `callCallbackThreadSafe()`

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

Calls a callback through the TSFN path for verification purposes.

### `ptr()`

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

Gets the underlying memory pointer of an ArrayBuffer or TypedArray.

```typescript theme={null}
const buf = new ArrayBuffer(256);
const p = ffi.ptr(buf); // → memory address
```