使用 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 类型签名创建类型定义。
   要了解根据 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 代码中实例化。

还有许多 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.5.3。页面最后更新于 2024-05-30。 查看源代码 或 报告问题.