XEP-0050: Ad-Hoc Commands#
- class slixmpp.plugins.xep_0050.XEP_0050(xmpp, config=None)[source]#
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)[source]#
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)[source]#
Cancel the execution of a command.
- Parameters
session – All stored data relevant to the current command session.
- complete_command(session)[source]#
Finish the execution of a command workflow.
- Parameters
session – All stored data relevant to the current command session.
- continue_command(session, direction='next')[source]#
Execute the next action of the command.
- Parameters
session – All stored data relevant to the current command session.
- get_commands(jid, **kwargs)[source]#
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.
- prep_handlers(handlers, **kwargs)[source]#
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)[source]#
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)[source]#
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)[source]#
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.
Stanza elements#
- class slixmpp.plugins.xep_0050.stanza.Command(xml=None, parent=None)[source]#
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')[source]#
Add a single note annotation to the command.
- Arguments:
msg – A human readable message. ntype – One of: ‘info’, ‘warning’, ‘error’
- get_action()[source]#
Return the value of the action attribute.
If the Iq stanza’s type is “set” then use a default value of “execute”.
- get_notes()[source]#
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
.
- name: ClassVar[str] = 'command'#
The XML tag name of the element, not including any namespace prefixes. For example, an
ElementBase
object for<message />
would usename = 'message'
.
- namespace: str = 'http://jabber.org/protocol/commands'#
The XML namespace for the element. Given
<foo xmlns="bar" />
, thennamespace = "bar"
should be used. The default namespace isjabber: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, thenparent
isNone
.
- plugin_attrib: ClassVar[str] = 'command'#
For
ElementBase
subclasses which are intended to be used as plugins, theplugin_attrib
value defines the plugin name. Plugins may be accessed by using theplugin_attrib
value as the interface. An example usingplugin_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)[source]#
Assign the set of allowable next actions.
- Parameters
values – A list containing any combination of: ‘prev’, ‘next’, and ‘complete’
- set_notes(notes)[source]#
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.