RPJosh
/
wayvnc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Manpage updates for wayvnc and wayvncctl 

Signed-off-by: Jim Ramsay <i.am@jimramsay.com>
pull/178/head
Jim Ramsay 2022-10-31 03:22:29 -04:00 committed by Andri Yngvason
parent 15735b3256
commit 4b1fbf9508
4 changed files with 246 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@ -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.

28
meson.build
View File

@ -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

106
wayvnc.scd
View File

@ -25,6 +25,10 @@ wayvnc - A VNC server for wlroots based Wayland compositors.
*-s, --seat=<name>*
Select seat by name.
*-S, --socket=<path>*
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 <andri@yngvason.is>. 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)*

82
wayvncctl.scd 100644
View File

@ -0,0 +1,82 @@
wayvncctl(1)
# NAME
wayvncctl - A control client for wayvnc(1)
# SYNOPSIS
*wayvncctl* [options] [command [--parameter value ...]]
# OPTIONS
*-S, --socket=<path>*
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)*