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.


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

external int aGlobalInt;

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.

  • @Since('2.19')


Native({String? assetId, bool isLeaf = false, String? symbol})


assetId String?
The ID of the asset in which symbol is resolved, if not using the default.
hashCode int
The hash code for this object.
no setterinherited
isLeaf bool
Whether the function is a leaf function.
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
symbol String?
The native symbol to be resolved, if not using the default.


noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
toString() String
A string representation of this object.


operator ==(Object other) bool
The equality operator.

Static Methods

addressOf<T extends NativeType>(Object native) Pointer<T>
The native address of the implementation of native.