Native<T> class final

Annotation binding an external declaration to its native implementation.

Can only be applied to external declarations of static and top-level functions and variables.

A Native-annotated external function is implemented by native code. The implementation is found in the native library denoted by assetId. Similarly, a Native-annotated external variable is implemented by reading from or writing to native memory.

The compiler and/or runtime provides a binding from assetId to native library, which depends on the target platform. The compiler/runtime can then resolve/lookup symbols (identifiers) against the native library, to find a native function or a native global variable, and bind an external Dart function or variable declaration to that native declaration. By default, the runtime expects a native symbol with the same name as the annotated function or variable in Dart. This can be overridden with the symbol parameter on the annotation.

If this annotation is used on a function, then the type argument T to the Native annotation must be a function type representing the native function's parameter and return types. The parameter and return types must be subtypes of NativeType.

If this annotation is used on an external variable, then the type argument T must be a compatible native type. For example, an int field can be annotated with Int32. If the type argument to @Native is omitted, it defaults to the Dart type of the annotated declaration, which must then be a native type too. This will never work for function declarations, but can apply to variables whose type is some of the types of this library, such as Pointer. For native global variables that cannot be re-assigned, a final variable in Dart or a getter can be used to prevent assignments to the native field.

Example:

@Native<Int64 Function(Int64, Int64)>()
external int sum(int a, int b);

@Native<Int64>()
external int aGlobalInt;

@Native()
external final Pointer<Char> aGlobalString;

Calling a @Native function, as well as reading or writing to a @Native variable, will try to resolve the symbol in (in the order):

1. the provided or default assetId,
2. the native resolver set with Dart_SetFfiNativeResolver in dart_api.h, and
3. the current process.

At least one of those three must provide a binding for the symbol, otherwise the method call or the variable access fails.

NOTE: This is an experimental feature and may change in the future.