description

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

Annotations
  - @Since.new('2.19')

## Constructors

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

## Properties

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

## Methods

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

## Operators

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

## Static Methods

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