Ad-Hoc Commands

If you want to implement your own adhoc command, just register your adhoc command module with module:add_item providing a descriptor for your command.

A descriptor can be created and added like this:

local adhoc_new = module:require "adhoc".new;
local descriptor = adhoc_new("Name", "node", handler);
module:add_item ("adhoc", descriptor)

A handler gets 2 parameters. A data table and a state.

The data table has 4 fields:

to The to attribute of the stanza to be handled
from The from attribute of the stanza to be handled
action The action to be performed as specified in the stanza to be handled
form If the to be handled stanza contains a form this will contain the form element

The handler should return two items. A data table and a state. The state will be saved and passed to the handler on invocation for any adhoc stanza with the same session id. If a session has ended the state returned should be nil.

The returned table can have the following fields:

Name Explanation Required?
status Status of the command (One of: "completed", "canceled", "error") yes
error A table with the fields "type", "condition" and "message" when status is "error"
info Informational text for display to the user no
warn A warning for the user no
actions The actions available to the client no
form A dataform to be filled out by the user no
result A dataform of type result to be presented to the user no
other Any other XML to be included in the response to the user no

For a simple module and details have a look at mod_ping.