ad-hoc: Ad-Hoc commands¶
Ad-Hoc commands is a generic mechanism of XMPP to control an entity. They can be used either by humans, or automated. Ad-Hoc commands can be used for administration (e.g. get list of connected users, send a service announcement, restart parts of the server), or execute about anything (e.g. control a physical robot with XMPP).
run¶
Run an ad-hoc command. You may specify the node to run as positional argument, or let it empty to list available commands.
By default the commands from your server are used, but with -j JID, --jid JID
you can
specify a different entity.
You can automatically execute commands by using -f KEY VALUE, --field KEY VALUE
and
-S, --submit
as many time as needed. --field
expect a KEY
which is the name
of the field to set. If you don’t know which name to use, you can run the command to
automatise a first time manually with --verbose, -v
flag, this will display fields
names when you have to fill them.
Once all fields of a page are specified, you may use -S, --submit
to validate it, then
if suitable use again --field
to set fields of next page and --submit
again, and
so on as many times as you need.
Don’t forget that you can use your shell substitution capabilities if necessary, for instance if you have a pre-registered announce to send.
examples¶
Get a list of available commands on your server to launch a command:
$ li ad-hoc run
If your server supports XEP-0133 and you’re an admin on it, you can send announcements
to online users. This can be useful to notify an imminent maintenance of the server. Here
we notify online users that the server will be shutdown in 30 min, using a shell
substitution capabilities with a pre-registered message in the file
~/announces/maintenance_30.txt
, then we submit it:
$ li ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S
Get your server uptime (if supported by your server):
$ li ad-hoc run uptime
Run the commands available at the service with the jid someservice.example.org
:
$ li ad-hoc run -s someservice.example.org
Run you server commands with verbosity so you get the name of the fields that you can fill automatically later:
$ li ad-hoc run -v
list¶
List ad-hoc commands available at a service.
examples¶
List ad-hoc commands available at your server:
$ li ad-hoc list
List ad-hoc commands available at a chat service:
$ li ad-hoc list -j conference.example.org
remote¶
Create a remote control from launched media players. Ad-hoc commands to control the media
player will be added to your device, allowing anybody allowed (including yourself from an
other device, e.g. a phone) to remotely do action like play
, pause
, etc.
To add a device, just use the name of the software (e.g. vlc
, smplayer
). You can
specify who is allowed to control this media player with the following options:
-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]
jids of entities allowed to control the media player
g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]
groups (from your roster) allowed to control you remote
--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]
groups (from your roster) which are NOT allowed to control your media player
--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]
jids of entities which are NOT allowed to control your media player
If you want the commands to run repeatedly (in opposition of stopping after first action
is sent), you may use the -l, --loop
option. Most of time you’ll want to use it.
Note
Libervia already creates automatically a remote control if it finds a media player. This manual way to create a remote control predate the automatic remote control, and is currently more flexible in that you can specify who can access the remote control (automatic remote control is only accessible by the jid of the profile).
examples¶
Create a remote control for a running VLC instance:
$ li ad-hoc remote vlc -l
Create a remote control for a running SMPlayer instance, and allowing anybody from your
housemates
group to use it:
$ li ad-hoc remote smplayer -g housemates -l