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

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

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

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

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

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

还有许多扩展 AbiSpecificInteger 的 ABI 特定标记原生类型。要了解这些类型如何在特定平台上映射，请查阅下表中的 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.7.1 版本。页面上次更新于 2024-11-17。 查看源代码 或 报告问题。