//! The methods of the control channel: names and documentation. //! //! Every request is `{"id", "method", "params"}` and gets one response line //! (see [`crate::protocol`]). After `events.subscribe` the connection also //! receives event lines `{"event": {...}}` between responses; each line is //! written whole, so lines never interleave. /// `app.ping`: liveness check. pub const APP_PING: &str = "app.ping"; /// `engine.execute`: runs an engine command. pub const ENGINE_EXECUTE: &str = "engine.execute"; /// `engine.listCommands`: lists the engine's commands. pub const ENGINE_LIST_COMMANDS: &str = "engine.listCommands"; /// `ui.screenshot`: writes a PNG of the main window without focusing it. /// A relative `path` is resolved against the app's working directory; the /// result names the absolute path written. pub const UI_SCREENSHOT: &str = "ui.screenshot"; /// `events.subscribe`: streams engine events on this connection. pub const EVENTS_SUBSCRIBE: &str = "events.subscribe"; /// `app.auth`: authenticates a connection to the rendezvous listener. pub const APP_AUTH: &str = "app.auth"; /// `app.focus`: brings the main window to the front; the only method that /// changes focus. pub const APP_FOCUS: &str = "app.focus"; /// Documentation of one method. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct MethodDoc { /// Method name. pub name: &'static str, /// Params. pub params: &'static str, /// Result. pub result: &'static str, } /// Every method, for help output and agents. pub const METHODS: &[MethodDoc] = &[ MethodDoc { name: APP_AUTH, params: "{ token: string }", result: "{ authenticated: true }. On the rendezvous listener it must be the first request; any other first request or a wrong token gets error unauthorized and the connection is closed. On the --control listener it always succeeds", }, MethodDoc { name: APP_FOCUS, params: "none", result: "{ focused: true }; error focus_failed if there is no window", }, MethodDoc { name: APP_PING, params: "none", result: "{ pong: true, version }", }, MethodDoc { name: ENGINE_EXECUTE, params: "{ command: string, params?: object }", result: "the command's result; errors carry the engine's code (unknown_command, disabled, invalid_params, stale_version, unsaved_changes, failed, internal)", }, MethodDoc { name: ENGINE_LIST_COMMANDS, params: "none", result: "[{ id, label, menuPath, defaultShortcut, params, enabled }]", }, MethodDoc { name: UI_SCREENSHOT, params: "{ path: string }", result: "{ path }; error screenshot_failed if the window cannot be captured. Never focuses, raises or shows the window", }, MethodDoc { name: EVENTS_SUBSCRIBE, params: "none", result: "{ subscribed: true }; then {\"event\": {kind, ...}} lines for every engine event until the connection closes. A subscriber that falls more than 4096 events behind is dropped and gets an {\"event\": {\"kind\": \"subscriptionLost\"}} line if possible", }, ];