PlatformModule API

Declared by <huxerui/platform_module.h>.

PlatformPayload

Immutable shared recursive value. PlatformPayloadKind is Null, Boolean, Integer, Double, String, Bytes, List, Object, or ExternalTexture. Constructors accept each alternative; integral constructors validate signed 64-bit range. Accessors are Kind, IsNull, and AsBoolean/Integer/Double/String/Bytes/List/Object/ExternalTexture; a type mismatch throws.

Results and keys

• PlatformRequestId: unsigned 64-bit request identity.
• PlatformError: string code, message, and details payload.
• PlatformResult<Result>: result-or-error variant.
• PlatformEventSink and PlatformResultSink: erased event and method-completion callbacks used by platform factories.
• A method key defines public nested Request and Result types plus static Name, Encode, and Decode members.
• A platform event key derives its signature from Event<...> and adds static Name and Decode members compatible with that signature.

The concepts that validate these shapes live in huxerui::detail; applications provide conforming key types rather than naming those concepts.

Factory and instance

PlatformModuleFactory creates an Instance from options and an event sink. The instance supplies method-call and disposal functions; a method call returns a cancellation cleanup.

PlatformInstance is move-only. Call<Method>(request, completion) returns a request ID; On<Key>(handler) registers an event handler; Cancel(id) and Close() end work.

Registry

PlatformModules::Register(type, registration) stores one typed registration per name. Find<Registration>(type) validates registration type. Open(type, options = {}) creates a shared PlatformModuleFactory instance. Platform adapters construct the registry and dispatch completion/event work onto the UI thread.

Complete typed method example

#include <huxerui/huxerui.h>

using namespace huxerui;

struct ReadBatteryLevel {
  using Request = std::monostate;
  using Result = double;
  static constexpr std::string_view Name = "readBatteryLevel";

  static PlatformPayload Encode(const Request&) {
    return nullptr;
  }

  static Result Decode(const PlatformPayload& payload) {
    return payload.AsDouble();
  }
};

void ReadBattery(PlatformInstance& device) {
  device.Call<ReadBatteryLevel>({}, [](PlatformResult<double> result) {
    if (const auto* level = std::get_if<double>(&result)) {
      static_cast<void>(*level);
    }
  });
}

The method key owns wire conversion. Application code sees a typed result while the native implementation remains behind the registered module factory.