Annotation binding an external declaration to its native implementation.
Can only be applied to
external declarations of static and top-level
functions and variables.
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.
@Native<Int64 Function(Int64, Int64)>()
external int sum(int a, int b);
external int aGlobalInt;
external final Pointer<Char> aGlobalString;
@Native function, as well as reading or writing to a
variable, will try to resolve the symbol in (in the order):
- the provided or default assetId,
- the native resolver set with
- 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.
- assetId → String?
The ID of the asset in which symbol is resolved, if not using the
- hashCode → int
The hash code for this object.
- isLeaf → bool
Whether the function is a leaf function.
- runtimeType → Type
A representation of the runtime type of the object.
- symbol → String?
The native symbol to be resolved, if not using the default.