Refactor bindgen templates and UrlOpener bindings

Add richer bindgen features and generate safer Dart wrappers: dump context JSON, add reference_format and type mappings in config, and implement pre/post-call handling, native->Dart conversion helpers, enum native-value mapping, struct/string ownership handling, and singleton class support in templates. Update generated ffigen bindings to remove explicit UrlOpener create/destroy and switch URL opener functions to handle-less signatures. Update UrlOpener API to a singleton (UrlOpener.instance), introduce UrlOpenResult.fromNative and UrlOpenErrorCode with native mappings, and ensure proper malloc/free of returned native structs and strings. Also update an example to use the singleton and advance the cnativeapi cxx_impl submodule commit.

Author: lijy91

bindgen/README.md

@@ -13,10 +13,12 @@ cd nativeapi-flutter
 PYTHONPATH=packages/cnativeapi/cxx_impl/tools python3 -m bindgen \
   --config bindgen/config.yaml \
   --dump-ir bindgen/out/ir.json \
+  --dump-context bindgen/out/context.json \
   --out bindgen/out
 ```
 
 ## Notes
 
 - This does **not** regenerate `lib/src/bindings_generated.dart`.
 - Add symbol exceptions in `mapping.options.symbol_overrides`.
+- `bindgen/out/context.json` is the mapped template input after IR -> API/config transformation.

bindgen/config.yaml

@@ -8,26 +8,32 @@ entry_headers:
 
 mapping:
   output_note: Generated wrapper from C++ API. Calls existing ffigen bindings.
+  reference_format: "{inner}"
 
   naming:
     enum_value_name: camel_case
     method_name: camel_case
     field_name: camel_case
 
   types:
+    void: void
     bool: bool
+    int32: int
+    uint32: int
+    int64: int
+    uint64: int
+    float32: double
+    float64: double
+    size_t: int
+    cstring: String
+    string: String
 
   default_type: dynamic
   passthrough_unknown: false
 
   options:
-    bindings_import: package:cnativeapi/src/bindings_generated.dart
-    api_type_rules:
-      contains:
-        - match: "&"
-          type: dynamic
-    force_instance_methods:
-      - nativeapi::UrlOpener::IsSupported
+    singleton_classes:
+      - UrlOpener
     formatters:
       - name: dart-format-generated
         cmd:

bindgen/template/file/dart.j2

@@ -10,13 +10,19 @@
 // {{ mapping.options.output_note | default("Generated by bindgen") }}
 // =============================================================================
 
+{%- if uses_ffi %}
 import 'dart:ffi' as ffi;
+{%- endif %}
+{%- if uses_ui %}
 import 'dart:ui' as ui;
+{%- endif %}
+{%- if uses_pkgffi %}
 import 'package:ffi/ffi.dart' as pkgffi;
-import 'package:cnativeapi/cnativeapi.dart';
-import '{{ mapping.options.bindings_import }}';
+{%- endif %}
 import 'package:nativeapi/src/foundation/cnativeapi_bindings_mixin.dart';
+{%- if has_handle_classes %}
 import 'package:nativeapi/src/foundation/native_handle_wrapper.dart';
+{%- endif %}
 
 {%- if has_types %}
 {% for item in types %}

bindgen/template/partials/class.j2

@@ -1,69 +1,98 @@
 {%- macro render_method_call(method) -%}
-{%- if method.return_bridge == 'string' %}
-    final cString = bindings.{{ method.call_symbol }}(
+bindings.{{ method.call_symbol }}(
 {%- if method.needs_instance_handle %}
-      _nativeHandle{% if method.call_args|length > 0 %},{% endif %}
+  _nativeHandle{% if method.call_args|length > 0 %}, {% endif %}
 {%- endif %}
 {%- for arg in method.call_args %}
-      {{ arg }}{% if not loop.last %}, {% endif %}
+  {{ arg }}{% if not loop.last %}, {% endif %}
 {%- endfor %}
-    );
+)
+{%- endmacro -%}
+
+{%- macro render_method_body(method) -%}
+{%- if method.return_bridge == 'string' %}
+    final cString = {{ render_method_call(method) }};
     if (cString == ffi.nullptr) return '';
     final value = cString.cast<pkgffi.Utf8>().toDartString();
     bindings.{{ method.string_free_symbol }}(cString);
     return value;
+{%- elif method.return_bridge == 'enum' %}
+    final nativeValue = {{ render_method_call(method) }};
+    return {{ method.api_return_type }}.fromNativeValue(nativeValue);
+{%- elif method.return_bridge == 'struct' %}
+    final nativeValue = {{ render_method_call(method) }};
+  {%- if method.struct_free_symbol %}
+    try {
+      return {{ method.api_return_type }}.fromNative(nativeValue);
+    } finally {
+      final nativeValuePtr = pkgffi.malloc<{{ method.native_return_type }}>();
+      nativeValuePtr.ref = nativeValue;
+      bindings.{{ method.struct_free_symbol }}(nativeValuePtr);
+      pkgffi.malloc.free(nativeValuePtr);
+    }
+  {%- else %}
+    return {{ method.api_return_type }}.fromNative(nativeValue);
+  {%- endif %}
 {%- elif method.return_bridge == 'offset' %}
-    final nativeValue = bindings.{{ method.call_symbol }}(
-{%- if method.needs_instance_handle %}
-      _nativeHandle{% if method.call_args|length > 0 %},{% endif %}
-{%- endif %}
-{%- for arg in method.call_args %}
-      {{ arg }}{% if not loop.last %}, {% endif %}
-{%- endfor %}
-  );
+    final nativeValue = {{ render_method_call(method) }};
     return ui.Offset(nativeValue.x, nativeValue.y);
 {%- elif method.return_bridge == 'size' %}
-    final nativeValue = bindings.{{ method.call_symbol }}(
-{%- if method.needs_instance_handle %}
-      _nativeHandle{% if method.call_args|length > 0 %},{% endif %}
-{%- endif %}
-{%- for arg in method.call_args %}
-      {{ arg }}{% if not loop.last %}, {% endif %}
-{%- endfor %}
-    );
+    final nativeValue = {{ render_method_call(method) }};
     return ui.Size(nativeValue.width, nativeValue.height);
 {%- elif method.return_bridge == 'rect' %}
-    final nativeValue = bindings.{{ method.call_symbol }}(
-{%- if method.needs_instance_handle %}
-      _nativeHandle{% if method.call_args|length > 0 %},{% endif %}
-{%- endif %}
-{%- for arg in method.call_args %}
-      {{ arg }}{% if not loop.last %}, {% endif %}
-{%- endfor %}
-    );
+    final nativeValue = {{ render_method_call(method) }};
     return ui.Rect.fromLTWH(nativeValue.x, nativeValue.y, nativeValue.width, nativeValue.height);
 {%- elif method.return_bridge == 'void' %}
-    bindings.{{ method.call_symbol }}(
-{%- if method.needs_instance_handle %}
-      _nativeHandle{% if method.call_args|length > 0 %},{% endif %}
-{%- endif %}
-{%- for arg in method.call_args %}
-      {{ arg }}{% if not loop.last %}, {% endif %}
-{%- endfor %}
-    );
+    {{ render_method_call(method) }};
 {%- else %}
-    return bindings.{{ method.call_symbol }}(
-{%- if method.needs_instance_handle %}
-      _nativeHandle{% if method.call_args|length > 0 %},{% endif %}
+    return {{ render_method_call(method) }};
 {%- endif %}
-{%- for arg in method.call_args %}
-      {{ arg }}{% if not loop.last %}, {% endif %}
+{%- endmacro -%}
+
+{%- macro render_callable(method) -%}
+{%- for line in method.pre_call_lines %}
+    {{ line }}
+{%- endfor %}
+{%- if method.post_call_lines %}
+    try {
+{{ render_method_body(method) }}
+    } finally {
+{%- for line in method.post_call_lines %}
+      {{ line }}
 {%- endfor %}
-    );
+    }
+{%- else %}
+{{ render_method_body(method) }}
 {%- endif %}
 {%- endmacro -%}
 
 {%- macro render_class(item, mapping) -%}
+{%- if item.is_singleton and not item.singleton_has_handle %}
+class {{ item.name }} with CNativeApiBindingsMixin {
+  static final {{ item.name }} instance = {{ item.name }}._();
+
+  {{ item.name }}._();
+
+{%- for method in item.methods %}
+{%- if not method.skip %}
+  {%- if method.is_property %}
+  {{ 'static ' if method.static else '' }}{{ method.api_return_type }} get {{ method.property_name }} {
+{{ render_callable(method) }}
+  }
+  {%- else %}
+  {{ 'static ' if method.static else '' }}{{ method.api_return_type }} {{ method.api_name }}(
+  {%- for param in method.params %}
+    {{ param.api_type }} {{ param.name }}{% if not loop.last %}, {% endif %}
+  {%- endfor %}
+  ) {
+{{ render_callable(method) }}
+  }
+  {%- endif %}
+
+{%- endif %}
+{%- endfor %}
+}
+{%- else %}
 class {{ item.name }} with CNativeApiBindingsMixin implements NativeHandleWrapper<{{ item.handle_alias }}> {
   {%- if item.is_singleton %}
   static final {{ item.name }} instance = {{ item.name }}._();
@@ -74,9 +103,13 @@ class {{ item.name }} with CNativeApiBindingsMixin implements NativeHandleWrappe
     _nativeHandle = bindings.{{ item.singleton_symbol }}();
   }
   {%- else %}
-  final {{ item.handle_alias }} _nativeHandle;
+  late final {{ item.handle_alias }} _nativeHandle;
+  final bool _ownsHandle;
 
-  {{ item.name }}(this._nativeHandle);
+  {{ item.name }}([{{ item.handle_alias }}? nativeHandle])
+      : _ownsHandle = nativeHandle == null {
+    _nativeHandle = nativeHandle ?? bindings.{{ item.create_symbol }}();
+  }
   {%- endif %}
 
   @override
@@ -86,15 +119,15 @@ class {{ item.name }} with CNativeApiBindingsMixin implements NativeHandleWrappe
 {%- if not method.skip %}
   {%- if method.is_property %}
   {{ 'static ' if method.static else '' }}{{ method.api_return_type }} get {{ method.property_name }} {
-{{ render_method_call(method) }}
+{{ render_callable(method) }}
   }
   {%- else %}
   {{ 'static ' if method.static else '' }}{{ method.api_return_type }} {{ method.api_name }}(
   {%- for param in method.params %}
     {{ param.api_type }} {{ param.name }}{% if not loop.last %}, {% endif %}
   {%- endfor %}
   ) {
-{{ render_method_call(method) }}
+{{ render_callable(method) }}
   }
   {%- endif %}
 
@@ -103,7 +136,14 @@ class {{ item.name }} with CNativeApiBindingsMixin implements NativeHandleWrappe
 
   @override
   void dispose() {
-    // Generated wrappers are non-owning by default.
+  {%- if item.is_singleton %}
+    // Singleton handles are managed by native code.
+  {%- else %}
+    if (_ownsHandle) {
+      bindings.{{ item.destroy_symbol }}(_nativeHandle);
+    }
+  {%- endif %}
   }
 }
+{%- endif %}
 {%- endmacro -%}

bindgen/template/partials/enum.j2

@@ -9,7 +9,18 @@
 {%- macro render_enum(item, mapping) -%}
 enum {{ item.name }} {
 {%- for value in item.values %}
-  {{ enum_case_name(value.name) }}{% if not loop.last %},{% endif %}
+  {{ enum_case_name(value.name) }}({{ value.value }}){% if not loop.last %},{% endif %}
+{%- endfor %};
+
+  const {{ item.name }}(this.nativeValue);
+
+  final int nativeValue;
+
+  static {{ item.name }} fromNativeValue(int value) => switch (value) {
+{%- for value in item.values %}
+    {{ value.value }} => {{ item.name }}.{{ enum_case_name(value.name) }},
 {%- endfor %}
+    _ => throw ArgumentError('Unknown value for {{ item.name }}: $value'),
+  };
 }
 {%- endmacro -%}