Hooks

This is the hooks section of niso_runtime.h, owned by niso-core and kept in crates/niso-core/include/hooks.h. The build composes it with the other sections in the order crates/niso-compose/sections.txt gives.

The binding’s hooks: the C surface of niso-core’s DocumentHooks trait (hooks.rs), which a Rust binding implements directly. Each setter sets its own hook and leaves the others as they were; a null hook is none, and the document does the work a hook needs only while it is set. The userdata stays the binding’s.

Called after a call connects a subtree to the document or disconnects it from the document: new_root is the root of the tree the subtree now belongs to. Moves that leave it in the document, or out of it, are not reported. The hook may call into the C API, but is not called again from inside itself: the moves those calls make are delivered after it returns, in the order they were made.

typedef void (*niso_tree_hook_fn)(void* userdata, niso_handle subtree, niso_handle new_root);

Called at the end of each task the DOM runs: a timer, an animation frame callback, a rendering update’s scroll events, and a host’s input (niso_dom_tap and the other user input calls below). No binding code is on the stack then, so a binding performs its microtask checkpoint here.

typedef void (*niso_task_hook_fn)(void* userdata);

Loads the resource at url (a UTF-8 absolute URL) for the document: returns 0 and its bytes in *out, valid until the loader is called again, or nonzero when there is none. Loaders must not call back into the DOM. The C surface of niso-core’s ResourceLoader trait (loading.rs): a null loader is none, and the document’s own loads are then the network’s.

typedef int32_t (*niso_loader_fn)(void* userdata, const char* url, size_t len, niso_bytes* out);

Called after a call connects script elements that have not started, once per script in tree order; the binding runs them. Scripts parsed by niso_dom_load_html come with parser_inserted set, followed by a null script once parsing has finished. Scripts parsed into innerHTML or outerHTML never start.

typedef void (*niso_script_hook_fn)(void* userdata, niso_handle script, bool parser_inserted);
typedef void (*niso_microtask_hook_fn)(void* userdata);

Called before a MessageEvent the platform made (a message from a port, a worker, a BroadcastChannel, window.postMessage or a WebSocket) is dispatched: the binding deserializes niso_message_event_serialized_data, or takes niso_message_event_native_data (what the platform made the data from, a WebSocket’s frame) when there is no serialization, into a value and sets it with niso_message_event_set_data. Returns false when it cannot, and messageerror fires instead. Native code that is no binding reads those two instead of data, with no hook.

typedef bool (*niso_message_hook_fn)(void* userdata, niso_handle event);

An event handler the handler hook compiled, as an EventHandler setter takes it.

typedef struct niso_event_handler {
    int32_t (*fn)(void* userdata, niso_handle event);
    void* userdata;
    niso_drop_fn drop;
} niso_event_handler;

Compiles an event handler content attribute when its handler’s value is first needed: source is element’s attribute name (like “onclick”), whose event handler is target’s, the element’s or, for body and frameset, its window’s. form is the element’s form owner, were it form-associated, or 0. The binding compiles it with the element’s scope, fills in out and returns true, or returns false after reporting a compile error. With no hook, content attributes are inert.

typedef bool (*niso_handler_hook_fn)(void* userdata, niso_handle target, niso_handle element, niso_handle form, const char* name,
                                     size_t name_len, const char* source, size_t source_len, niso_event_handler* out);