diff --git a/README.md b/README.md index 188fb3a..f9bfe07 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ dnf install -y meson gcc ninja-build pkg-config egl-wayland egl-wayland-devel \ mesa-libEGL-devel mesa-libEGL libwayland-egl libglvnd-devel \ libglvnd-core-devel libglvnd mesa-libGLES-devel mesa-libGLES \ libxkbcommon-devel libxkbcommon libwayland-client libwayland \ - wayland-devel gnutls-devel jansson-devel + wayland-devel gnutls-devel jansson-devel ``` #### For Debian (unstable / testing) @@ -130,3 +130,44 @@ password=p455w0rd private_key_file=/path/to/key.pem certificate_file=/path/to/cert.pem ``` + +### wayvncctl control socket + +To facilitate runtime interaction and control, wayvnc opens a unix domain socket +at *$XDG_RUNTIME_DIR*/wayvncctl (or a fallback of /tmp/wayvncctl-*$UID*). A +client can connect and exchange json-formatted IPC messages to query and control +the running wayvnc instance. + +Use the `wayvncctl` utility to interact with this control socket from the +command line. + +The `help` command can interactively query the available IPC commands: + +``` +$ wayvncctl help +{ + "commands": [ + "help", + "version", + "set-output", + ... + ] +} +``` + +``` +$ wayvncctl help command=help +{ + "help": { + "description": "List all commands, or show usage of a specific command", + "params": [ + { + "command": "The command to show (optional)" + } + ] + } +} +``` + +See the `wayvnc(1)` manpage for an in-depth description of the IPC protocol and +the available commands. diff --git a/meson.build b/meson.build index 320337c..5c13b6c 100644 --- a/meson.build +++ b/meson.build @@ -172,17 +172,21 @@ if scdoc.found() scdoc_prog = find_program(scdoc.get_pkgconfig_variable('scdoc'), native: true) sh = find_program('sh', native: true) mandir = get_option('mandir') - input = 'wayvnc.scd' - output = 'wayvnc.1' + manpages = { + 'wayvnc.scd': 'wayvnc.1', + 'wayvncctl.scd': 'wayvncctl.1', + } - custom_target( - output, - input: input, - output: output, - command: [ - sh, '-c', '@0@ <@INPUT@ >@1@'.format(scdoc_prog.path(), output) - ], - install: true, - install_dir: '@0@/man1'.format(mandir) - ) + foreach input, output : manpages + custom_target( + output, + input: input, + output: output, + command: [ + sh, '-c', '@0@ <@INPUT@ >@1@'.format(scdoc_prog.path(), output) + ], + install: true, + install_dir: '@0@/man1'.format(mandir) + ) + endforeach endif diff --git a/wayvnc.scd b/wayvnc.scd index da69f5f..0a11b63 100644 --- a/wayvnc.scd +++ b/wayvnc.scd @@ -25,6 +25,10 @@ wayvnc - A VNC server for wlroots based Wayland compositors. *-s, --seat=* Select seat by name. +*-S, --socket=* + Set wayvnc control socket path. Default: $XDG_RUNTIME_DIR/wayvncctl + or /tmp/wayvncctl-$UID + *-r, --render-cursor* Enable overlay cursor rendering. @@ -148,6 +152,101 @@ private_key_file=/path/to/key.pem certificate_file=/path/to/cert.pem ``` +# WAYVNCCTL CONTROL SOCKET + +To facilitate runtime interaction and control, wayvnc opens a unix domain socket +at *$XDG_RUNTIME_DIR*/wayvncctl (or a fallback of /tmp/wayvncctl-*$UID*). A +client can connect and exchange json-formatted IPC messages to query and control +the running wayvnc instance. + +## IPC COMMANDS + +_HELP_ + +The *help* command, when issued without any parameters, lists the names of all +available commands. + +If an optional *command* parameter refers to one of those commands by name, the +response data will be a detailed description of that command and its parameters. + +_VERSION_ + +The *version* command queries the running wayvnc instance for its version +information. Much like the _-V_ option, the response data will contain the +version numbers of wayvnc, as well as the versions of the neatvnc and aml +components. + +_SET-OUTPUT_ + +For multi-output wayland displays, this command switches which output is +actively captured by wayvnc. This operates in 2 different modes, depending on +which parameters are supplied: + +*cycle=next|prev* + Cycle to the next/prev output in the output list, wrapping back to the + first/last if the end of the list is reached. + +*switch-to=output-name* + Switch to a specific output by name. + +## IPC MESSAGE FORMAT + +The *wayvncctl(1)* command line utility will construct properly-formatted json +ipc messages, but any client will work. The client initiates the connection and +sends one or more request objects, each of which will receive a corresponding +response object. + +*Note* This message format is unstable and may change substantially over the +next few releases. + +_REQUEST_ + +The general form of a json-ipc request message +is: + +``` +{ + "method": "command-name", + "id": 123, + "params": { + "key1": "value1", + "key2": "value2", + } +} +``` + +The *method* is the name of the command to be executed. Use the *help* method to +query a list of all valid method names. + +The *id* field is optional and may be any valid json number or string. If +provided, the response to this request will contain the identical id value, +which the client may use to coordinate multiple requests and responses. + +The *params* object supplies optional parameters on a per-method basis, and may +be omitted if empty. + +_RESPONSE_ + +``` +{ + "id": 123, + "code": 0, + "data": { + ... + } +} +``` + +If the request had an id, the response will have an identical value for *id*. + +The numerical *code* provides an indication of how the request was handled. A +value of *0* always signifies success. Any other value means failure, and varies +depending on the method in question. + +The *data* object contains method-specific return data. This may be structured +data in response to a query, a simple error string in the case of a failed +request, or it may be omitted entirely if the error code alone is sufficient. + # ENVIRONMENT The following environment variables have an effect on wayvnc: @@ -159,6 +258,9 @@ _WAYLAND_DISPLAY_ _XDG_CONFIG_HOME_ Specifies the location of configuration files. +_XDG_RUNTIME_DIR_ + Specifies the default location for the wayvncctl control socket. + # FAQ *Wayvnc complains that a protocol is not supported* @@ -210,3 +312,7 @@ _XDG_CONFIG_HOME_ Maintained by Andri Yngvason . Up-to-date sources can be found at https://github.com/any1/wayvnc and bugs reports or patches can be submitted to GitHub's issue tracker. + +# SEE ALSO + +*wayvncctl(1)* diff --git a/wayvncctl.scd b/wayvncctl.scd new file mode 100644 index 0000000..c2d20d7 --- /dev/null +++ b/wayvncctl.scd @@ -0,0 +1,82 @@ +wayvncctl(1) + +# NAME + +wayvncctl - A control client for wayvnc(1) + +# SYNOPSIS + +*wayvncctl* [options] [command [--parameter value ...]] + +# OPTIONS + +*-S, --socket=* + Set wayvnc control socket path. Default: $XDG_RUNTIME_DIR/wayvncctl + or /tmp/wayvncctl-$UID + +*-V, --version* + Show version info. + +*-v,--verbose* + Be more verbose. + +*-h, --help* + Get help. + +# DESCRIPTION + +*wayvnc(1)* allows runtime interaction via a unix socket json-ipc mechanism. +This command line utility provides easy interaction with those commands. + +For a full list of currently supported commands, see +*wayvnc(1)* section _IPC COMMANDS_, or use the +*wayvncctl help* command. + +# EXAMPLES + +Query the server for all available command names: + +``` +$ wayvncctl help +{ + "commands": [ + "help", + "version", + "set-output", + ... + ] +} +``` + +Get help on the "help" command: + +``` +$ wayvncctl help --command help +{ + "help": { + "description": "List all commands, or show usage of a specific command", + "params": [ + { + "command": "The command to show (optional)" + } + ] + } +} +``` + +Cycle to the next active output: + +``` +$ wayvncctl set-output --cycle=forward +``` + +# ENVIRONMENT + +The following environment variables have an effect on wayvncctl: + +_XDG_RUNTIME_DIR_ + Specifies the default location for the wayvncctl control socket. + +# SEE ALSO + +*wayvnc(1)*