Struct CExtension 

pub struct CExtension { /* private fields */ }

A C shared library loaded as a guest extension of a Rust host.

The plugin exports kui_ext_abi and kui_ext_view (and optionally kui_ext_name, kui_ext_init, kui_ext_slots, kui_ext_on_event and kui_ext_free; include/kui.h has the prototypes). Each frame the host’s Ui reaches a slot the plugin fills, kui_ext_view is called with a context borrowing that frame and builds into it with the ordinary kui_open / kui_text / kui_close calls; events from the nodes it built go to kui_ext_on_event, never to the host, and what it answers with kui_reply reaches the host with the plugin’s origin.

It implements Extension, so it plugs into kui_native::app(..) .extension_as(namespace, ext) or a kui_core::Extensions list like any other extension. On ELF and Mach-O the plugin links against nothing and resolves kui_* from the host executable at load, which needs the host linked with --export-dynamic (this crate’s build.rs does it for the examples); on Windows the plugin links against the host’s import library or against kui_ffi.dll.

use kui_ffi::CExtension;

// SAFETY: the plugin's code runs in this process; loading it is
// trusting it as much as linking it would be.
let ext = unsafe { CExtension::open("target/debug/panel.so") }?;
let launcher = kui_native::app("host").extension_as("todos", ext);

Implementations

impl CExtension

pub unsafe fn open(path: impl AsRef<Path>) -> Result<Self, String>

Loads the shared library at path and runs its kui_ext_init.

Fails, with the reason as the error, if the library will not load, if it declares no kui_ext_abi or one other than this build’s KUI_ABI_VERSION, or if it has no kui_ext_view. The plugin’s kui_ext_free runs and the library is unloaded when the CExtension is dropped.

Safety

The library’s entry points are called on the host’s frame and its code runs in the host’s process: loading one is trusting it exactly as much as linking it would be.

Trait Implementations

impl Drop for CExtension

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Extension for CExtension

fn name(&self) -> &str

fn slots(&self) -> &[String]

The slot names this extension fills; empty means "root". The one entry crate::slot::ANY_SLOT ("*") means every name declared under its namespace, for an extension whose slots are not known when it loads — a Lua host whose init.lua registers views at runtime, one slot per view — and it then gets no unknown-slot warning, since there is no list to check against.

fn view(&mut self, slot: &Slot<'_>, ui: &mut Ui<'_>) -> Result<(), String>

fn on_event(&mut self, ev: &UiEvent) -> Vec<Value>

One of this extension’s events; the values returned are replies to the host, delivered in order.