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.

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.

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.

iterables: List[ElementBase]

A list of child stanzas whose class is included in plugin_iterables.

loaded_plugins: Set[str]

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

parent: Optional[ReferenceType[ElementBase]]

A weakref.weakref to the parent stanza, if there is one. If not, then parent is None.

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

plugins: Dict[Tuple[str, Optional[str]], ElementBase]

An ordered dictionary of plugin stanzas, mapped by their plugin_attrib value.

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

tag: str

The name of the tag for the stanza’s root element. It is the same as calling tag_name() and is formatted as '{namespace}elementname'.

xml: ET.Element

The underlying XML object for the stanza. It is a standard xml.etree.ElementTree object.