使用 dart:ffi 进行 C 互操作

在 Dart Native 平台上运行的 Dart 移动、命令行和服务器应用程序可以使用 dart:ffi 库来调用原生 C API，并读取、写入、分配和释放原生内存。FFI 代表 外部函数接口。类似功能的其他术语包括原生接口和语言绑定。

API 文档可在 dart:ffi API 参考中找到。

要使用本指南中的示例，请下载完整的 ffi 示例目录。它包含以下示例，展示了如何使用 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;

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

   var libraryPath = path.join(Directory.current.path, 'hello_library',
       'libhello.so');
   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');
   }

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 库的方法取决于平台和库类型。

要了解如何操作，请查阅以下页面和示例。

• 适用于 Android 应用程序的 Flutter dart:ffi
• 适用于 iOS 应用程序的 Flutter dart:ffi
• 适用于 macOS 应用程序的 Flutter dart:ffi
• dart:ffi 示例

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

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

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

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

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

原生资产特性应该可以解决与依赖于原生代码的 Dart 包的发布相关的许多问题。它通过为集成到构建 Flutter 和独立 Dart 应用程序的各种构建系统提供统一的钩子来实现这一点。

此特性应该简化 Dart 包依赖和使用原生代码的方式。原生资产应该提供以下好处

• 使用包的 hook/build.dart 构建钩子构建原生代码或获取二进制文件。
• 捆绑 build.dart 构建钩子报告的原生 Asset。
• 通过使用 assetId 的声明式 @Native<>() extern 函数，使原生资产在运行时可用。

当您选择加入原生实验时，flutter (run|build) 和 dart (run|build) 命令会使用 Dart 代码构建并捆绑原生代码。

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 中的原生资产，请查阅 Native 和 DefaultAsset 的 dart:ffi API 参考。
• 要了解 hook/build.dart 构建钩子，请查阅 package:native_assets_cli API 参考。

要了解如何启用实验并提供反馈，请查阅以下跟踪问题

• Dart 原生资产
• Flutter 原生资产

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面上次更新于 2024-11-17。 查看源代码 或 报告问题。