Skip to content
Back to top
View this page

# XEP-0050: Ad-Hoc Commands

XEP-0050 on xmpp.org

class slixmpp.plugins.xep_0050.XEP_0050(xmpp, config=None)

  XEP-0050: Ad-Hoc Commands

  XMPP’s Adhoc Commands provides a generic workflow mechanism for interacting with applications. The result is similar to menu selections and multi-step dialogs in normal desktop applications. Clients do not need to know in advance what commands are provided by any particular application or agent. While adhoc commands provide similar functionality to Jabber-RPC, adhoc commands are used primarily for human interaction.

  Also see <http://xmpp.org/extensions/xep-0050.html>

  Events:

    - command_execute: Received a command with action=”execute”

    - command_next: Received a command with action=”next”

    - command_complete: Received a command with action=”complete”

    - command_cancel: Received a command with action=”cancel”

  Attributes:
    - `commands`: A dictionary mapping JID/node pairs to command

        names and handlers. Only used with the default API handlers.

    - `sessions`: A dictionary or equivalent backend mapping

        session IDs to dictionaries containing data relevant to a command’s session.

  Slixmpp API:

    A basic default static implementation is provided for those using the `self.commands` attribute.

    - set_command: Set handler for a `jid/node/ifrom` combo

    - get_command: Get handler for a `jid/node/ifrom` combo

  add_command(jid=None, node=None, name='', handler=None, *, timeout=0, timeout_handler=None)

    Make a new command available to external entities.

    Access control may be implemented in the provided handler.

    Command workflow is done across a sequence of command handlers. The first handler is given the initial Iq stanza of the request in order to support access control. Subsequent handlers are given only the payload items of the command. All handlers will receive the command’s session data.

    Parameters:

      - jid (`str` | `JID` | `None`) – The JID that will expose the command.

      - node (`str` | `None`) – The node associated with the command.

      - name – A human readable name for the command.

      - handler (`Callable`[[`Iq`, `dict`[`str`, `Any`]], `Awaitable`[`dict`[`str`, `Any`]] | `dict`[`str`, `Any`]] | `None`) – A function that will generate the response to the initial command request, as well as enforcing any access control policies.

      - timeout (`float`) – A timeout, in seconds, after which a session for this command will be cancelled. 0 by default, which means no timeout.

      - timeout_handler (`Callable`[[`dict`[`str`, `Any`]], `Awaitable`[`None`]] | `None`) – Optionally, a custom handler that will be called on timeout, with the session dict, before the “cancel” IQ is sent to the XMPP client.

  cancel_command(session)

    Cancel the execution of a command.

    Parameters:

      session – All stored data relevant to the current command session.

  complete_command(session)

    Finish the execution of a command workflow.

    Parameters:

      session – All stored data relevant to the current command session.

  continue_command(session, direction='next')

    Execute the next action of the command.

    Parameters:

      session – All stored data relevant to the current command session.

  default_config: ClassVar[dict[str, Any]] = {'session_db': None}

    The basic, standard configuration for the plugin, which may be overridden when initializing the plugin. The configuration fields included here may be accessed directly as attributes of the plugin. For example, including the configuration field ‘foo’ would mean accessing plugin.foo returns the current value of plugin.config[‘foo’].

  get_commands(jid, **kwargs)

    Return a list of commands provided by a given JID.

    Parameters:

      - jid – The JID to query for commands.

      - local – If true, then the query is for a JID/node combination handled by this Slixmpp instance and no stanzas need to be sent. Otherwise, a disco stanza must be sent to the remote JID to retrieve the items.

      - iterator – If True, return a result set iterator using the XEP-0059 plugin, if the plugin is loaded. Otherwise the parameter is ignored.

  new_session()

    Return a new session ID.

  prep_handlers(handlers, **kwargs)

    Prepare a list of functions for use by the backend service.

    Intended to be replaced by the backend service as needed.

    Parameters:

      - handlers – A list of function pointers

      - kwargs – Any additional parameters required by the backend.

  send_command(jid, node, ifrom=None, action='execute', payload=None, sessionid=None, flow=False, **kwargs)

    Create and send a command stanza, without using the provided workflow management APIs.

    Parameters:

      - jid – The JID to send the command request or result.

      - node – The node for the command.

      - ifrom – Specify the sender’s JID.

      - action – May be one of: execute, cancel, complete, or cancel.

      - payload – Either a list of payload items, or a single payload item such as a data form.

      - sessionid – The current session’s ID value.

      - flow – If True, process the Iq result using the command workflow methods contained in the session instead of returning the response stanza itself. Defaults to False.

  set_backend(db)

    Replace the default session storage dictionary with a generic, external data storage mechanism.

    The replacement backend must be able to interact through the same syntax and interfaces as a normal dictionary.

    Parameters:

      db – The new session storage mechanism.

  start_command(jid, node, session, ifrom=None)

    Initiate executing a command provided by a remote agent.

    The provided session dictionary should contain:

    Parameters:

      - next – A handler for processing the command result.

      - error – A handler for processing any error stanzas generated by the request.

      - jid – The JID to send the command request.

      - node – The node for the desired command.

      - session – A dictionary of relevant session data.

  terminate_command(session)

    Delete a command’s session after a command has completed or an error has occurred.

    Parameters:

      session – All stored data relevant to the current command session.

## Stanza elements

class slixmpp.plugins.xep_0050.stanza.Command(xml=None, parent=None)

  XMPP’s Adhoc Commands provides a generic workflow mechanism for interacting with applications. The result is similar to menu selections and multi-step dialogs in normal desktop applications. Clients do not need to know in advance what commands are provided by any particular application or agent. While adhoc commands provide similar functionality to Jabber-RPC, adhoc commands are used primarily for human interaction.

  Also see <http://xmpp.org/extensions/xep-0050.html>

  Example command stanzas:

      <iq type="set">
        <command xmlns="http://jabber.org/protocol/commands"
                 node="run_foo"
                 action="execute" />
      </iq>

      <iq type="result">
        <command xmlns="http://jabber.org/protocol/commands"
                 node="run_foo"
                 sessionid="12345"
                 status="executing">
          <actions>
            <complete />
          </actions>
          <note type="info">Information!</note>
          <x xmlns="jabber:x:data">
            <field var="greeting"
                   type="text-single"
                   label="Greeting" />
          </x>
        </command>
      </iq>

  Stanza Interface:

      action    -- The action to perform.
      actions   -- The set of allowable next actions.
      node      -- The node associated with the command.
      notes     -- A list of tuples for informative notes.
      sessionid -- A unique identifier for a command session.
      status    -- May be one of: canceled, completed, or executing.

  actions = {'cancel', 'complete', 'execute', 'next', 'prev'}
  add_note(msg='', ntype='info')

    Add a single note annotation to the command.

    Arguments:

      msg – A human readable message. ntype – One of: ‘info’, ‘warning’, ‘error’

  del_actions()

    Remove all allowable next actions.

  del_notes()

    Remove all notes associated with the command result.

  get_action()

    Return the value of the action attribute.

    If the Iq stanza’s type is “set” then use a default value of “execute”.

  get_actions()

    Return the set of allowable next actions.

  get_notes()

    Return a list of note information.

    Example:
      [(‘info’, ‘Some informative data’),

        (‘warning’, ‘Use caution’), (‘error’, ‘The command ran, but had errors’)]

  interfaces: ClassVar[set[str]] = {'action', 'actions', 'node', 'notes', 'sessionid', 'status'}

    The set of keys that the stanza provides for accessing and manipulating the underlying XML object. This set may be augmented with the `plugin_attrib` value of any registered stanza plugins.

  name: ClassVar[str] = 'command'

    The XML tag name of the element, not including any namespace prefixes. For example, an `ElementBase` object for `<message />` would use `name = 'message'`.

  namespace: str = 'http://jabber.org/protocol/commands'

    The XML namespace for the element. Given `<foo xmlns="bar" />`, then `namespace = "bar"` should be used. The default namespace is `jabber:client` since this is being used in an XMPP library.

  next_actions = {'complete', 'next', 'prev'}
  plugin_attrib: ClassVar[str] = 'command'

    For `ElementBase` subclasses which are intended to be used as plugins, the `plugin_attrib` value defines the plugin name. Plugins may be accessed by using the `plugin_attrib` value as the interface. An example using `plugin_attrib = 'foo'`:

        register_stanza_plugin(Message, FooPlugin)
        msg = Message()
        msg['foo']['an_interface_from_the_foo_plugin']

  set_actions(values)

    Assign the set of allowable next actions.

    Parameters:

      values – A list containing any combination of: ‘prev’, ‘next’, and ‘complete’

  set_notes(notes)

    Add multiple notes to the command result.

    Each note is a tuple, with the first item being one of: ‘info’, ‘warning’, or ‘error’, and the second item being any human readable message.

    Example:
      [(‘info’, ‘Some informative data’),

        (‘warning’, ‘Use caution’), (‘error’, ‘The command ran, but had errors’)]

    Arguments:

      notes – A list of tuples of note information.

  statuses = {'canceled', 'completed', 'executing'}