使用 dart:ffi 与 C 进行交互

Dart 的移动端、命令行和服务端应用所运行的 Dart 原生平台，均可以使用 dart:ffi 库调用原生的 C 语言 API，用于读、写、分配和销毁原生内存。 FFI 指的是 外部函数接口。类似的术语包括 原生接口 和 语言绑定。

相关的 API 文档可在 dart:ffi API 文档 查看。

请下载完整的 ffi samples 目录，来使用本指南中的示例。以下的示例将展示如何使用 dart:ffi 库：

hello_world 示例 展示了如何用最少的代码调用 C 语言库。该示例可在上一节下载的 samples/ffi 中找到。

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;
   

   content_copy

2. 导入 path 库用于合成动态库的路径。

   dart

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

   content_copy

3. 用 C 函数的 FFI 类型签名定义一个 typedef。
   请参阅 定义原生类型的接口 来了解 dart:ffi 库中定义的常用类型。

   dart

   typedef hello_world_func = ffi.Void Function();
   

   content_copy

4. 为调用 C 函数的变量定义一个 typedef。

   dart

   typedef HelloWorld = void Function();
   

   content_copy

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',
     );
   }
   

   content_copy

6. 加载包含 C 函数的动态库。

   dart

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

   content_copy

7. 获取该 C 函数的引用，接着将其赋予变量。这段代码使用了步骤 2 和 3 定义的 typedef，以及步骤 4 定义的动态库变量。

   dart

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

   content_copy

8. 调用 C 函数。

   dart

   hello();
   

   content_copy

当你理解 hello_world 示例的内容后，可以进一步学习 其他的 dart:ffi 示例。

根据平台和库的类型的不同，集成 / 打包 / 分发后加载原生 C 库的方式，也有所不同。

请参考以下页面和示例，来了解如何使用。

• 用于 Android 应用的 Flutter dart:ffi

• 用于 iOS 应用的 Flutter dart:ffi

• 用于 macOS 应用的 Flutter dart:ffi

• dart:ffi 示例

The dart:ffi library provides multiple types that implement NativeType and represent native types in C. You can instantiate some native types. Some other native types can be used only as markers in type signatures.

The following native types can be used as markers in type signatures. They or their subtypes can be instantiated in Dart code.

The following list shows which platform-agnostic native types that serve as markers in type signatures. They can't be instantiated in Dart code.

There are also many ABI specific marker native types that extend AbiSpecificInteger. To learn how these types map on specific platforms, consult the API documentation linked in the following table.

为大量的 API 编写绑定可能要花费你的大量时间。你可以使用 package:ffigen 绑定生成器，自动地从 C 头文件生成 FFI 包装，从而减少时间消耗。

要了解 Dart FFI 对代码资源的支持，请查阅 dart:ffi API 参考文档中的 Native 和 DefaultAsset。

Dart build hooks (formerly known as native assets) enable packages to contain native code assets that are transparently built, bundled, and made available at runtime. For more information, see Hooks.