#include <adhoc.h>
Inherits DiscoNodeHandler, and IqHandler.
Inheritance diagram for Adhoc:
Public Member Functions | |
Adhoc (ClientBase *parent, Disco *disco) | |
virtual | ~Adhoc () |
virtual StringList | handleDiscoNodeFeatures (const std::string &node) |
virtual StringMap | handleDiscoNodeIdentities (const std::string &node, std::string &name) |
virtual StringMap | handleDiscoNodeItems (const std::string &node) |
virtual bool | handleIq (Stanza *stanza) |
virtual bool | handleIqID (Stanza *stanza, int context) |
void | registerAdhocCommandProvider (AdhocCommandProvider *acp, const std::string &command, const std::string &name) |
void | removeAdhocCommandProvider (const std::string &command) |
The current, not complete, implementation is probably best suited for fire-and-forget type of commands. Any additional feature, like multiple stages, etc., would have to be added separately.
Use this class as follows: Create a class that will handle command execution requests and derive it from AdhocCommandProvider. Instantiate an Adhoc object and register your AdhocCommandProvider-derived object with the Adhoc object using registerAdhocCommandProvider(). The additional parameters to that method are the internal name of the command as used in the code, and the public name of the command as it will be shown to an end user:
MyClass::someFunc() { Adhoc *m_adhoc = new Adhoc( m_client, m_client->disco() ); // this might be a bot monitoring a weather station, for example m_adhoc->registerAdhocCommandProvider( this, "getTemp", "Retrieve current temperature" ); m_adhoc->registerAdhocCommandProvider( this, "getPressure", "Retrieve current air pressure" ); [...] }
And that's about it you can do with the Adhoc class. Of course you can have a AdhocCommandProvider handle more than one command, just register it with the Adhoc object for every desired command, like shown above.
What the Adhoc object does when you install a new command is tell the supplied Disco object to advertise these commands to clients using the 'Service Discovery' protocol to learn about this implementation's features. These clients can then call and execute the command. Of course you are free to implement access restrictions to not let anyone mess with your bot, for example. However, the commands offered using Service Discovery are publically visible in any case.
Definition at line 72 of file adhoc.h.
Adhoc | ( | ClientBase * | parent, | |
Disco * | disco | |||
) |
Constructor. Creates a new Adhoc client that registers as IqHandler with a ClientBase.
parent | The ClientBase used for XMPP communication. | |
disco | The Disco object used to announce available commands. |
StringList handleDiscoNodeFeatures | ( | const std::string & | node | ) | [virtual] |
In addition to handleDiscoNodeIdentities
, this function is used to gather more information on a specific node. It is called when a disco::info query arrives with a node attribute that matches the one registered for this handler.
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
StringMap handleDiscoNodeIdentities | ( | const std::string & | node, | |
std::string & | name | |||
) | [virtual] |
In addition to handleDiscoNodeFeatures
, this function is used to gather more information on a specific node. It is called when a disco::info query arrives with a node attribute that matches the one registered for this handler.
node | The node this handler is supposed to handle. | |
name | This parameter is currently used as additional return value. Just fill in the name of the node. |
Implements DiscoNodeHandler.
StringMap handleDiscoNodeItems | ( | const std::string & | node | ) | [virtual] |
This function is used to gather more information on a specific node. It is called when a disco::items query arrives with a node attribute that matches the one registered for this handler. If node is empty, items for the root node (no node) shall be returned.
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
bool handleIq | ( | Stanza * | stanza | ) | [virtual] |
Reimplement this function if you want to be notified about incoming IQs.
stanza | The complete Stanza. |
Implements IqHandler.
bool handleIqID | ( | Stanza * | stanza, | |
int | context | |||
) | [virtual] |
Reimplement this function if you want to be notified about incoming IQs with a specific value of the id
attribute. You have to enable tracking of those IDs using Client::trackID()
. This is usually useful for IDs that generate a positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.
stanza | The complete Stanza. | |
context | A value to restore context, stored with ClientBase::trackID(). |
Implements IqHandler.
void registerAdhocCommandProvider | ( | AdhocCommandProvider * | acp, | |
const std::string & | command, | |||
const std::string & | name | |||
) |
Using this function, you can register a AdhocCommandProvider -derived object as handler for a specific Ad-hoc Command as defined in JEP-0050.
acp | The obejct to register as handler for the specified command. | |
command | The node name of the command. Will be announced in disco::items. | |
name | The natural-language name of the command. Will be announced in disco::items. |
void removeAdhocCommandProvider | ( | const std::string & | command | ) |
Use this function to unregister an adhoc command previously registered using registerAdhocCommandProvider().
command | The command to unregister. |