XEP-0050: Ad-Hoc Commands

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.

sessions – A dictionary or equivalent backend mapping

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

add_command(jid=None, node=None, name='', 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 – The JID that will expose the command.

• node – The node associated with the command.

• name – A human readable name for the command.

• handler – A function that will generate the response to the initial command request, as well as enforcing any access control policies.

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’].

dependencies: ClassVar[Set[str]] = {'xep_0004', 'xep_0030'}

Some plugins may depend on others in order to function properly. Any plugin names included in dependencies will be initialized as needed if this plugin is enabled.

description: str = 'XEP-0050: Ad-Hoc Commands'

A longer name for the plugin, describing its purpose. For example, a plugin for XEP-0030 would use ‘Service Discovery’ as its description value.

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

name: str = 'xep_0050'

A short name for the plugin based on the implemented specification. For example, a plugin for XEP-0030 would use ‘xep_0030’.

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'}