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

# arkffi 概述

> ArkTS / HarmonyOS 的外部函數接口庫

arkffi 讓你從 ArkTS 直接調用 `.so` 共享庫中的 C 函數 —— 無需手寫 NAPI 綁定。

<CardGroup cols={3}>
  <Card title="快速開始" icon="rocket" href="/zh/getting-started">
    安裝、配置，在幾分鐘內調用你的第一個 C 函數。
  </Card>

  <Card title="API 參考" icon="book-open" href="/zh/api/dlopen">
    dlopen、FFIType、CString、CFunction、JSCallback 完整參考。
  </Card>

  <Card title="指南" icon="compass" href="/zh/guides/mixed-types">
    混合類型、函數指針、回調的深入指南。
  </Card>
</CardGroup>

## 概述

arkffi 提供三個抽象層：

| 層級                         | 說明                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| **原始 NAPI 橋接**             | `load`、`close`、`callMixed`、`callBySig`、`callString`、`readCString`、`getSymbolPtr`、`callPtr` |
| **`dlopen` 封裝**            | 聲明式 `dlopen()`，支持字典式函數定義和類型化符號                                                             |
| **CFunction / JSCallback** | 函數指針包裝和 ArkTS 回調支持                                                                         |

### 特性

* 從 `.so` 庫調用任意導出的 C 函數
* 支持 `int32`、`int64`、`double`、`float`、`bool`、`pointer`、`cstring`
* 混合參數類型（`int` + `double` + `string` 一次調用）
* 通過 `CFunction` 支持函數指針
* 通過 `JSCallback` 支持 ArkTS 回調，可設置 `threadsafe`
* 通過 `CString` 讀取 C 字符串
* TypeScript 泛型支持 IDE 代碼補全

## 快速開始

```typescript theme={null}
import { dlopen, FFIType, CString } from 'arkffi';

const lib = dlopen('libffi_target.so', {
  add:        { args: [FFIType.double, FFIType.double], returns: FFIType.double },
  getVersion: { args: [],                                returns: FFIType.int64 },
});

lib.symbols.add(2.0, 3.0);
new CString(lib.symbols.getVersion()).toString();

lib.close();
```

## 架構

```
ArkTS / TypeScript        dlopen / CFunction / JSCallback / CString
      │                              │
      ▼                              ▼ (NAPI)
liblibrary.so ──dlopen/dlsym/dlclose──► libffi_target.so (或任意 .so)
```

## 安裝

```bash theme={null}
ohpm install arkffi
```