Manpage updates for wayvnc and wayvncctl

Signed-off-by: Jim Ramsay <[email protected]>

README.md

@@ -131,5 +131,45 @@ 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 commandline.
+
+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.
+
 ## Compatible Software
 See https://github.com/any1/neatvnc#client-compatibility

meson.build

@@ -165,17 +165,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'
-
-	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)
-	)
+	manpages = {
+		'wayvnc.scd': 'wayvnc.1',
+		'wayvncctl.scd': 'wayvncctl.1',
+	}
+
+	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

wayvnc.scd

@@ -25,6 +25,10 @@ wayvnc - A VNC server for wlroots based Wayland compositors.
 *-s, --seat=<name>*
 	Select seat by name.
 
+*-S, --socket=<path>*
+	Set wayvncctl 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 dara 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=forward|reverse*
+	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=$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 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, or a simple error string in the case of a failed
+request.
+
 # 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
 
 *How can I run wayvnc in headless mode/over an SSH session?*
@@ -197,3 +299,7 @@ _XDG_CONFIG_HOME_
 Maintained by Andri Yngvason <[email protected]>. 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)*

wayvncctl.scd

@@ -0,0 +1,86 @@
+wayvncctl(1)
+
+# NAME
+
+wayvncctl - A control client for wayvnc(1)
+
+# SYNOPSIS
+
+*wayvncctl* [options] [command [parameter=value...]]
+
+# OPTIONS
+
+*-S, --socket=<path>*
+	Set wayvncctl control socket path. Default: $XDG_RUNTIME_DIR/wayvncctl
+	or /tmp/wayvncctl-$UID
+
+*-V, --version*
+	Show version info.
+
+*-v,--verbose*
+	Be more verbose. Same as setting `--log-level=info`.
+
+*-L,--log-level*
+	Set log level. The levels are: error, warning, info, debug, trace and
+	quiet.
+
+*-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)*