使用 dart:ffi 的 C 語言互通性

在 Dart Native 平台上執行的 Dart 行動、命令列和伺服器應用程式可以使用 dart:ffi 函式庫來呼叫原生 C API，以及讀取、寫入、分配和釋放原生記憶體。FFI 代表外部函式介面 (foreign function interface)。類似功能的其他術語包括原生介面和語言綁定。

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 的 typedef，以及步驟 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 套件發布相關的許多問題。它透過提供統一的 hook 來與建置 Flutter 和獨立 Dart 應用程式所涉及的各種建置系統整合來實現這一點。

此功能應簡化 Dart 套件依賴和使用原生程式碼的方式。原生資源應提供以下優點

• 使用套件的 hook/build.dart 建置 hook 來建置原生程式碼或取得二進位檔。
• 捆綁 build.dart 建置 hook 報告的原生 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 建置 hook。native_add_app 範例展示了 native_add_library 的用法。

以下套件的 API 文件可在以下位置找到

• 若要瞭解 Dart FFI 中的原生資源，請參閱 Native 和 DefaultAsset 的 dart:ffi API 參考。
• 若要瞭解 hook/build.dart 建置 hook，請參閱 package:native_assets_cli API 參考。

若要瞭解如何啟用實驗性功能並提供意見回饋，請參閱這些追蹤問題

• Dart 原生資源
• Flutter 原生資源

除非另有說明，否則本網站上的文件反映 Dart 3.7.1 版本。頁面最後更新於 2024-11-17。 檢視原始碼 或 回報問題。