Struct abstract base

abstract base class Struct extends _Compound implements SizedNativeType, NativeType

The supertype of all FFI struct types.

FFI struct types should extend this class and declare fields corresponding to the underlying native structure.

Field declarations in a Struct subclass declaration are automatically given a setter and getter implementation which accesses the native struct's field in memory.

All field declarations in a Struct subclass declaration must either have type int or double and be annotated with a NativeType representing the native type, or must be of type Pointer, Array or a subtype of Struct or Union. For example:

typedef struct {
 int a;
 float b;
 void* c;
} my_struct;

final class MyStruct extends Struct {
  @Int32()
  external int a;

  @Float()
  external double b;

  external Pointer<Void> c;
}

The field declarations of a Struct subclass must be marked external. A struct subclass points directly into a location of native memory (Pointer) or Dart memory (TypedData), and the external field's getter and setter implementations directly read and write bytes at appropriate offsets from that location. This does not allow for non-native fields to also exist.

An instance of a struct subclass cannot be created with a generative constructor. Instead, an instance can be created by StructPointer.ref, Struct.create, FFI call return values, FFI callback arguments, StructArray, and accessing Struct fields. To create an instance backed by native memory, use StructPointer.ref. To create an instance backed by Dart memory, use Struct.create.

Implemented types

• SizedNativeType
• NativeType

Available Extensions

• StructAddress<T extends Struct>

Constructors

Struct()

Struct()

Construct a reference to the nullptr.

Use StructPointer's .ref to gain references to native memory backed structs.

Implementation

Struct() : super._();

Properties

address extension no setter

Pointer<T> get address

The memory address of the underlying data.

An expression of the form expression.address denoting this address can only occurr as an entire argument expression in the invocation of a leaf Native external function.

Example:

@Native<Void Function(Pointer<MyStruct>)>(isLeaf: true)
external void myFunction(Pointer<MyStruct> pointer);

final class MyStruct extends Struct {
  @Int8()
  external int x;
}

void main() {
  final myStruct = Struct.create<MyStruct>();
  myFunction(myStruct.address);
}

The expression before .address is evaluated like the left-hand-side of an assignment, to something that gives access to the storage behind the expression, which can be used both for reading and writing. The .address then gives a native pointer to that storage.

The .address is evaluated just before calling into native code when invoking a leaf Native external function. This ensures the Dart garbage collector will not move the object that the address points in to.

Available on T extends Struct, provided by the StructAddress<T extends Struct> extension

Implementation

external Pointer<T> get address;

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

external String toString();

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);

Static Methods

create()

T create<T extends Struct>([TypedData typedData, int offset])

Creates a struct view of bytes in typedData.

The created instance of the struct subclass will then be backed by the bytes at TypedData.offsetInBytes plus offset times TypedData.elementSizeInBytes. That is, the getters and setters of the external instance variables declared by the subclass, will read an write their values from the bytes of the TypedData.buffer of typedData, starting at TypedData.offsetInBytes plus offset times TypedData.elementSizeInBytes. The TypedData.lengthInBytes of typedData must be sufficient to contain the sizeOf of the struct subclass. It doesn't matter whether the typedData is, for example, a Uint8List, a Float64List, or any other TypedData, it's only treated as a view into a ByteBuffer, through its TypedData.buffer, TypedData.offsetInBytes and TypedData.lengthInBytes.

If typedData is omitted, a fresh ByteBuffer, with precisely enough bytes for the sizeOf of the created struct, is allocated on the Dart heap, and used as memory to store the struct fields.

If offset is provided, the indexing into typedData is offset by offset times TypedData.elementSizeInBytes.

Example:

final class Point extends Struct {
  @Double()
  external double x;

  @Double()
  external double y;

  /// Creates Dart managed memory to hold a `Point` and returns the
  /// `Point` view on it.
  factory Point(double x, double y) {
    return Struct.create()
      ..x = x
      ..y = y;
  }

  /// Creates a [Point] view on [typedData].
  factory Point.fromTypedData(TypedData typedData) {
    return Struct.create(typedData);
  }
}

To create a struct object from a Pointer, use StructPointer.ref.

Implementation

@Since('3.4')
external static T create<T extends Struct>([TypedData typedData, int offset]);