QtEDM Plugin API Version 1

QtEDM version 1 plugins are local Qt libraries that implement one or more interfaces from qtedm/qtedm_plugin_api.h. The supported extension points are display objects, data providers, and archive providers. This API deliberately does not provide filesystem, process-launch, or unrestricted application access.

Installation and discovery

Install a plugin library and its metadata sidecar in either:

• the plugins directory next to the QtEDM executable; or
• an absolute local directory listed in QTEDM_PLUGIN_PATH.

QTEDM_PLUGIN_PATH uses the platform path-list separator (: on Unix and ; on Windows). Relative paths, missing directories, non-library files, and libraries without valid metadata are rejected. Remote loading is not supported.

For a library named libfacility_widgets.so, the required sidecar is libfacility_widgets.so.qtedm-plugin.json. The suffix is appended to the full platform library name, including .dll, .dylib, or .so.

{
  "schema": "org.aps.qtedm.plugin-metadata",
  "schema_version": 1,
  "plugin_id": "org.example.facility.widgets",
  "interfaces": [
    "display",
    "data",
    "archive"
  ]
}

The loader limits metadata to 64 KiB. plugin_id and interfaces must exactly match the interfaces exposed by the Qt object. Unknown schemas, duplicate interfaces, and metadata/binary disagreement reject the library before it is registered.

Binary compatibility

Every implemented interface returns qtedmCurrentPluginCompatibility(). QtEDM requires an exact match for:

• QTEDM_PLUGIN_INTERFACE_VERSION;
• the Qt major version;
• the build CPU architecture; and
• compiler family and version ABI.

Rebuild plugins for each QtEDM toolchain and target architecture. A library compiled for another Qt major, compiler version, or architecture is rejected with a diagnostic rather than loaded optimistically.

The Qt plugin class needs Q_OBJECT, one Q_PLUGIN_METADATA declaration, and all implemented interfaces in Q_INTERFACES. The checked-in qtedm/tests/plugin_api_discovery_plugin.cc is the smallest buildable display plugin example. qtedm/tests/plugin_api_pv_thumbs_plugin.cc is a live-PV example: its PV Thumbs Indicator displays a thumbs-down emoji for zero and a thumbs-up emoji for any nonzero numeric value. It reports its channel through the display-plugin API, subscribes through QtedmPluginHost, and cancels the subscription when its runtime stops. Its default test channel is led:test:binary_live.

Build both examples and their metadata sidecars with:

make -C qtedm build-tests

The resulting libraries are placed in the plugins directory beside the unit test executable, where a QtEDM executable in that same build directory will discover them automatically. Open tests/test_QtEDMPluginExamples.adl with that executable to see the Discovery Label and PV Thumbs Indicator together.

Display-object plugins

Implement QtedmDisplayObjectPluginInterface and register stable, lowercase type IDs. Each QtedmDisplayObjectType supplies palette name/category, default size, schema version, and typed property declarations. Version 1 property types are Boolean, integer, double, string, color, and string list.

QtEDM calls the plugin to:

1. construct the child QWidget;
2. apply and serialize typed properties;
3. enumerate all PV or provider channels used by the object; and
4. create an optional execute-mode QtedmPluginRuntime.

Runtime code receives only QtedmPluginHost. Use it for subscriptions, diagnostics, and writes. Never retain a widget or host subscription past stop(). Construction, property, serialization, channel, and runtime exceptions are contained and reported as plugin diagnostics.

Saved objects use an explicit extension block:

qtedm_plugin {
  pluginId="org.example.facility.widgets"
  typeId="vacuum_summary"
  schemaVersion=1
  object { x=20 y=40 width=220 height=90 }
  property { name="title" type="string" value="Sector 4" }
  property { name="channel" type="string" value="VAC:S4:STATE" }
}

Unknown properties and children are retained. A missing plugin or a newer unsupported object schema produces a visible diagnostic placeholder, and the original raw node survives save, reopen, copy/paste, and undo/redo.

Data-provider plugins

Implement QtedmDataProviderPluginInterface and register one or more URI schemes such as facility://. The built-in ca and pva schemes are reserved. Subscriptions return a QtedmDataSubscription; cancel() must be idempotent and promptly detach provider callbacks.

The provider reports value, connection, and access-right changes with QtedmChannelCallbacks. It must honor the requested passive or realtime delivery mode and keep callback work bounded.

All plugin-provider puts pass through PvChannelManager before the provider's put() implementation. Consequently observe-only mode blocks them before the plugin sees a value, and both blocked and successful operations use the common audit path. Display plugins must also write only through QtedmPluginHost::put(); direct CA/PVA client writes are outside the supported contract.

Archive-provider plugins

Implement QtedmArchiveProviderPluginInterface and return an ArchiveProvider from qtedm/archive_provider.h. The query supplies explicit time bounds, maximum points, timeout, and response-byte limits. Providers must respect those bounds, complete asynchronously, observe owner/request cancellation, and return partial/failure state through ArchiveResult.

Choose a provider for qtedm_archive_plot with QTEDM_ARCHIVER_PROVIDER=<provider-id>. An empty value or archiver-appliance selects the built-in provider. A missing plugin provider leaves live plotting active and displays the archive diagnostic.

Diagnostics and shutdown

Rejected libraries, duplicate plugin/type/scheme/provider IDs, construction failures, and provider errors appear in QtEDM test-state and application diagnostics. QtEDM cancels data subscriptions before unregistering types and unloading libraries. Plugin shutdown and subscription cancellation must be idempotent because handles can be released during display close as well as application teardown.

Security boundary

Plugin libraries are native code and therefore trusted local extensions. QtEDM does not download, discover, or sandbox remote plugins. Facilities should install reviewed binaries in administrator-controlled paths. Declarative rules are the sandboxed automation mechanism for ordinary display authors; they are not a substitute for native-plugin review.