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.

When used on a function, T must be a function type that represents the native function's parameter and return types. The parameter and return types must be subtypes of NativeType.

When used on a variable, T must be a compatible native type. For example, an int field can be annotated with Int32.

If the type argument T is omitted in the @Native annotation, it is inferred from the static type of the declaration, which must meet the following constraints:

For function or method declarations:

• The return type must be one of the following:
  • Pointer
  • void
  • Subtype of compound types, such as Struct or Union
• The parameter types must be subtypes of compound types or Pointer

For variable declarations, the type can be any of the following:

• Pointer
• Subtype of compound types, such as Struct or Union

For native global variables that cannot be reassigned, a final variable in Dart or a getter can be used to prevent modifications to the native field.

Example:

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

@Native()
external void free(Pointer p);

@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.