Native class - dart:ffi library (original) (raw)

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 thesymbol 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 @Nativevariable, will try to resolve the symbol in (in the order):