node_app_api/
context.rs

1//! Host context passed to native apps during initialization
2//!
3//! The NodeAppContext provides callback function pointers that apps
4//! use to interact with the host (logging, config, storage, capabilities).
5
6use std::ffi::c_char;
7use std::os::raw::c_void;
8
9use crate::ffi::FfiResult;
10
11/// Host context provided to native apps.
12///
13/// Contains function pointers for callbacks into the host.
14/// The context pointer is valid for the lifetime of the app.
15#[repr(C)]
16pub struct NodeAppContext {
17    /// Opaque pointer to host-side state (passed as first arg to callbacks)
18    pub host_data: *const c_void,
19    /// Log a message at the specified level.
20    /// `level`: 0=trace, 1=debug, 2=info, 3=warn, 4=error
21    /// `message`: null-terminated UTF-8 string
22    pub host_log: unsafe extern "C" fn(host_data: *const c_void, level: u32, message: *const c_char),
23    /// Get a configuration value by key.
24    /// Returns null if key not found. Caller must NOT free the returned pointer.
25    pub host_get_config:
26        unsafe extern "C" fn(host_data: *const c_void, key: *const c_char) -> *const c_char,
27    /// Set a storage value (scoped to this app).
28    /// Both key and value are null-terminated UTF-8 strings.
29    pub host_set_storage: unsafe extern "C" fn(
30        host_data: *const c_void,
31        key: *const c_char,
32        value: *const c_char,
33    ),
34    /// Get a storage value by key (scoped to this app).
35    /// Returns null if key not found. Caller must NOT free the returned pointer.
36    pub host_get_storage:
37        unsafe extern "C" fn(host_data: *const c_void, key: *const c_char) -> *const c_char,
38    /// Invoke a capability on the host via the capability router.
39    /// `request_json` is a pointer to UTF-8 JSON bytes (CapabilityRequest) of length `request_len`.
40    /// Returns FfiResult with CapabilityResponse JSON in `data`/`data_len`.
41    /// The caller must free the returned data using the host's free function.
42    pub host_invoke_capability: unsafe extern "C" fn(
43        host_data: *const c_void,
44        request_json: *const u8,
45        request_len: usize,
46    ) -> FfiResult,
47    /// Publish a domain event to the host event bus.
48    /// `event_name` is a pointer to UTF-8 bytes of length `event_name_len` (max 256 bytes).
49    /// `event_data` is a pointer to UTF-8 JSON bytes of length `event_data_len` (max 64KB).
50    /// Returns 0 on success, negative error code on failure.
51    /// Fire-and-forget semantics: the event is queued asynchronously.
52    pub host_publish_event: unsafe extern "C" fn(
53        host_data: *const c_void,
54        event_name: *const u8,
55        event_name_len: usize,
56        event_data: *const u8,
57        event_data_len: usize,
58    ) -> i32,
59}
node_app_api/context.rs

node_app_api/
context.rs
