استدعاء مكتبات C باستخدام dart:ffi

dart:ffi is Dart's Foreign Function Interface. It lets your Flutter app call functions in native C shared libraries (.so, .dylib, .dll, or the iOS process image) directly, with no platform-channel round-trip.

• Synchronous by default and very low overhead, unlike MethodChannel which serializes messages across an async boundary.
• Ideal for CPU-heavy code, existing C/C++/Rust libraries, and OS-level APIs (sqlite, libsodium, image codecs).
• You bind a C signature to a Dart signature, then call it like an ordinary function.

The cost: you manage memory and types yourself. Get a pointer or a struct layout wrong and you crash the whole process.

Everything starts with a DynamicLibrary. It is the handle to the loaded native code from which you look up symbols.

• DynamicLibrary.open(path) loads a shared library by file name. On Android use 'libfoo.so'; on iOS/macOS code is usually statically linked, so use DynamicLibrary.process() or DynamicLibrary.executable().
• Pick the right name per platform with Platform.isAndroid / Platform.isIOS.

FFI uses two type universes. The native type describes the C ABI; the Dart type is what your Dart code actually sees.

• Int32, Int64, Uint8, Double, Float are native marker types — you never instantiate them, they map to Dart int/double.
• Pointer<T> is a native address. Void marks no value.
• The C function type is written with Function using native types; the Dart-facing type uses plain Dart types.

Example: C int32_t add(int32_t, int32_t) becomes native Int32 Function(Int32, Int32) and Dart int Function(int, int).

Use lookupFunction to bind a C symbol to a Dart function in one call. It takes two generic parameters: the native signature and the Dart signature.

• The first type argument must use native types (Int32, Double, …).
• The second is the callable Dart type returned to you.

Below, a pure-Dart simulation shows the call shape that FFI mirrors at runtime.

Real bindings declare the two signatures as typedefs. This keeps lookupFunction readable and lets you reuse signatures.

• Native typedef uses native marker types and the suffix convention ...Native.
• Dart typedef uses Dart types.
• The string passed to lookupFunction is the exact exported C symbol name.

To pass pointers you must allocate native (off-heap) memory. The package:ffi library provides malloc (a calloc variant also exists) plus extensions for strings.

• malloc<Int32>() returns a Pointer<Int32>; use .value to read/write.
• malloc<Int32>(n) allocates an array of n elements; index with ptr[i] or ptr.elementAt(i).
• You must free what you allocate with malloc.free(ptr) — the GC does not track native memory.

C strings are null-terminated char*, represented as Pointer<Utf8> (from package:ffi). Conversion goes both ways:

• Dart → C: myString.toNativeUtf8() allocates a native buffer (free it later).
• C → Dart: ptr.toDartString() copies the bytes into a Dart String.

If the native function returns a pointer it allocated, you typically must call its matching free export — never malloc.free memory you did not allocate with malloc.

To marshal C structs, declare a Dart class extending Struct. Each field is annotated with its native type so the FFI runtime computes the exact memory layout/offsets.

• Scalar fields get annotations like @Int32(), @Double().
• Field order and types must match the C struct exactly, including padding/alignment rules.
• You never construct a Struct with new; you obtain one via a Pointer<T>.ref backed by native memory.

Most C APIs take a Point*. Allocate the struct, fill it through .ref, pass the pointer, then read results back.

• malloc<Point>() gives a Pointer<Point> sized correctly for the layout.
• ptr.ref is a view onto that native memory; writing ptr.ref.x = 3.0 mutates the C struct in place.
• The native function reads/writes the same memory — this is how you get values out by reference.

FFI calls are synchronous: they run on the calling isolate's thread. A long native computation called from the main isolate freezes Flutter's UI.

• For heavy work, run the FFI call inside an Isolate (e.g. Isolate.run on modern Dart) or a worker isolate.
• Note: a DynamicLibrary handle and native pointers can be passed between isolates as addresses, but each isolate must re-open or share carefully — treat pointers as plain integers across boundaries.
• Native code that calls back into Dart must use NativeCallable / send ports, not arbitrary threads.

FFI bugs are process crashes, not exceptions. Discipline matters:

• Ownership: whoever allocates must free. Memory from malloc → malloc.free. Memory from a C library → that library's destructor export.
• Wrap allocate/use/free in try/finally so you free even on error.
• For long-lived native objects, attach a NativeFinalizer so the destructor runs when the Dart wrapper is GC'd.
• Never read .ref/.value on a pointer after it is freed — that is a use-after-free.

Answer based on dart:ffi struct and memory rules.

You can now bind to native C libraries from Flutter with dart:ffi:

• Load code with DynamicLibrary.open / .process(), choosing the path per platform.
• Bind symbols with lookupFunction<Native, Dart>, declaring native vs Dart typedefs.
• Allocate off-heap memory with malloc, marshal strings via toNativeUtf8 / toDartString, and pass arrays as pointers.
• Define structs by extending Struct with native-type annotations; pass them by pointer and read results through .ref.
• Keep heavy calls off the UI isolate, and enforce strict ownership: free what you allocate, use try/finally and NativeFinalizer, and never touch freed pointers.

FFI trades safety for speed and reach — correct types, layout, and lifetimes are entirely your responsibility.