Create wrappers for VARIANT and PROPVARIANT structures

[halildurmus]

VARIANT and PROPVARIANT structures are widely used in COM APIs as containers for various types of data. These structures consist of a large union to represent different types efficiently.

For example, here’s how you would create a VARIANT struct to hold a BSTR (a COM string type):

final variant = calloc<VARIANT>();
variant.ref
  ..vt = VARENUM.VT_BSTR // Define the type of the VARIANT
  ..bstrVal = BSTR.fromString('I am a happy BSTR').ptr; // Set the value

// Do something with the VARIANT...

// Clean up
VariantClear(variant);
calloc.free(variant);

While this works, it’s verbose and prone to errors, especially when dealing with memory allocation and cleanup. We could create wrapper classes for these structures and use NativeFinalizer to handle memory management automatically. These wrappers should also include detach and free methods, giving users greater control over the object's lifecycle.

Here's how the wrapper class for VARIANT could look like:

final class Variant<T extends Object?> implements Finalizable {
  /// Creates a new empty [Variant].
  ///
  /// The constructed [VARIANT] will have the [VT_EMPTY] type.
  ///
  /// Attaches a [NativeFinalizer] to the instance to automatically free the
  /// memory when no longer used.
  factory Variant() => Variant.fromPointer(calloc<VARIANT>());

  factory Variant.from(T value) => Variant<T>()..value = value;

  Variant.fromPointer(this.ptr) {
    _finalizer.attach(
      this,
      ptr.cast(),
      detach: this,
      externalSize: sizeOf<VARIANT>(),
    );
  }

  static final _finalizer = NativeFinalizer(...);

  final Pointer<VARIANT> ptr;

  void detach() => _finalizer.detach(this);

  void free() {
    _finalizer.detach(this);
    VariantClear(ptr);
    calloc.free(ptr);
  }

  static VariantBSTR bstr(String value) => VariantBSTR(value);

  T get value {
    // ...
  }

  set value(T value) {
    // ...
  }

  // ...
}

final class VariantBSTR extends Variant<String?> {
  factory VariantBSTR(String value) {
    final variant = calloc<VARIANT>();
    variant.ref
      ..vt = VT_BSTR
      ..bstrVal = value.toBSTR();
    return VariantBSTR.fromPointer(variant);
  }

  VariantBSTR.fromPointer(super.ptr) : super.fromPointer();

  @override
  String? get value => bstrVal.isNull ? null : bstrVal.toDartString();
  @override
  set value(String? value) => bstrVal = value?.toBSTR() ?? nullptr;
}

// ...

With this wrapper, creating and using a VARIANT becomes much easier:

final variant = Variant.bstr('I am a happy BSTR');
// Or:
// final variant = Variant.from('I am a happy BSTR');

// Do something with the VARIANT...

[android-dev2015]

I just encountered this similar problem，haha