=======================
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::

  $ jp 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::

  $ jp 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)::

  $ jp ad-hoc run uptime

Run the commands available at the service with the jid ``someservice.example.org``::

  $ jp 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::

  $ jp ad-hoc run -v

.. _XEP-0133: https://xmpp.org/extensions/xep-0133.html

list
====

List ad-hoc commands available at a service.

examples
--------

List ad-hoc commands available at your server::

  $ jp ad-hoc list

List ad-hoc commands available at a chat service::

  $ jp 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::

   SàT 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::

  $ jp ad-hoc remote vlc -l

Create a remote control for a running SMPlayer instance, and allowing anybody from your
``housemates`` group to use it::

  $ jp ad-hoc remote smplayer -g housemates -l