使用 dart:ffi 进行 C 语言互操作

运行在 Dart 原生平台上的 Dart 移动、命令行和服务器应用可以使用 dart:ffi 库调用原生 C API，以及读、写、分配和释放原生内存。FFI 是 Foreign Function Interface 的缩写，意为外部函数接口。类似功能的其他术语包括原生接口和语言绑定。

API 文档可在dart:ffi API 参考中查阅。

要使用本指南中的示例，请下载完整的 ffi 示例目录。它包括以下示例，展示如何使用 dart:ffi 库

要了解如何使用 dart:ffi 库调用 C 函数，请回顾 hello.dart 文件。本节解释了该文件的内容。

hello_world 示例包含以下文件

构建 C 库会创建几个文件，包括名为 libhello.dylib (macOS)、libhello.dll (Windows) 或 libhello.so (Linux) 的动态库文件。

构建动态库并执行 Dart 应用的命令序列类似于以下内容。

cd hello_library
cmake .
...
make
...
cd ..
dart pub get
dart run hello.dart
Hello World

要了解如何使用 dart:ffi 库调用 C 函数，请回顾 hello.dart 文件。本节解释了该文件的内容。

1. 导入 dart:ffi。

   dart

   import 'dart:ffi' as ffi;

2. 导入 path 库，该库将用于存储动态库的路径。

   dart

   import 'dart:io' show Platform, Directory;
   import 'package:path/path.dart' as path;

3. 使用 C 函数的 FFI 类型签名创建 typedef。
   要了解 dart:ffi 库中最常用的类型，请查阅与原生类型交互。

   dart

   typedef hello_world_func = ffi.Void Function();

4. 为调用 C 函数时要使用的变量创建 typedef。

   dart

   typedef HelloWorld = void Function();

5. 创建一个变量来存储动态库的路径。

   dart

   final String libraryPath;
   if (Platform.isMacOS) {
     libraryPath = path.join(
       Directory.current.path,
       'hello_library',
       'libhello.dylib',
     );
   } else if (Platform.isWindows) {
     libraryPath = path.join(
       Directory.current.path,
       'hello_library',
       'Debug',
       'hello.dll',
     );
   } else {
     libraryPath = path.join(
       Directory.current.path,
       'hello_library',
       'libhello.so',
     );
   }

6. 打开包含 C 函数的动态库。

   dart

   final dylib = ffi.DynamicLibrary.open(libraryPath);

7. 获取 C 函数的引用，并将其存入变量。此代码使用步骤 2 和 3 中的 typedefs，以及步骤 4 中的动态库变量。

   dart

   final HelloWorld hello = dylib
       .lookup<ffi.NativeFunction<hello_world_func>>('hello_world')
       .asFunction();

8. 调用 C 函数。

   dart

   hello();

理解 hello_world 示例后，请查阅其他 dart:ffi 示例。

打包/封装/分发然后加载原生 C 库的方法取决于平台和库类型。

要了解具体方法，请查阅以下页面和示例。

• Flutter dart:ffi 用于 Android 应用
• Flutter dart:ffi 用于 iOS 应用
• Flutter dart:ffi 用于 macOS 应用
• dart:ffi 示例

dart:ffi 库提供了多种实现 NativeType 并表示 C 语言原生类型的类型。您可以实例化某些原生类型。另一些原生类型只能用作类型签名中的标记。

以下原生类型可用作类型签名中的标记。它们或其子类型可以在 Dart 代码中实例化。

以下列表显示了哪些平台无关的原生类型可用作类型签名中的标记。它们不能在 Dart 代码中实例化。

还有许多特定于 ABI 的标记原生类型，它们扩展自 AbiSpecificInteger。要了解这些类型在特定平台上的映射方式，请查阅下表中链接的 API 文档。

对于大型 API 接口，手动编写与 C 代码集成的 Dart 绑定可能非常耗时。要让 Dart 从 C 头文件创建 FFI 包装器，请使用 package:ffigen 绑定生成器。

Dart 构建钩子（以前称为原生资产）使包除了 Dart 源代码外，还能包含更多内容。现在，包可以包含原生代码资产，这些资产会被透明地构建、打包并在运行时可用。

此功能简化了 Dart 包依赖和使用原生代码的方式

• 使用包的构建钩子（位于 hook/build.dart 中）构建原生代码或获取二进制文件。
• Dart 和 Flutter 会打包构建钩子报告的 CodeAsset。
• 通过使用 assetId 的声明式 @Native<>() extern 函数在运行时访问代码资产。

Flutter 和独立的 Dart 会自动打包应用使用的所有包的原生代码，并在运行时使其可用。这适用于 flutter (run|build) 和 dart (run|build) 命令。

native_add_library 示例包含了在 Dart 包中构建和打包 C 代码所需的最低代码。

该示例包含以下文件

当 Dart 或 Flutter 项目依赖于 package:native_add_library 时，在运行 run、build 和 test 命令时会调用 hook/build.dart 构建钩子。native_add_app 示例展示了 native_add_library 的用法。

以下包的 API 文档可以在这里找到

• 要了解 Dart FFI 中对代码资产的支持，请查阅 dart:ffi API 参考中的 Native 和 DefaultAsset。
• 要了解 hook/build.dart 构建钩子，请查阅package:hooks API 参考。

要提供反馈，请参考这些跟踪议题

• Dart 构建钩子与代码资产
• Flutter 构建钩子与代码资产