gloox
1.0.28
|
#include <adhoc.h>
Classes | |
class | Command |
Public Member Functions | |
Adhoc (ClientBase *parent) | |
virtual | ~Adhoc () |
void | checkSupport (const JID &remote, AdhocHandler *ah, int context=0) |
void | getCommands (const JID &remote, AdhocHandler *ah, int context=0) |
void | execute (const JID &remote, const Adhoc::Command *command, AdhocHandler *ah, int context=0) |
void | respond (const JID &remote, const Adhoc::Command *command, const Error *error=0) |
void | registerAdhocCommandProvider (AdhocCommandProvider *acp, const std::string &command, const std::string &name) |
void | removeAdhocCommandProvider (const std::string &command) |
virtual StringList | handleDiscoNodeFeatures (const JID &from, const std::string &node) |
virtual Disco::IdentityList | handleDiscoNodeIdentities (const JID &from, const std::string &node) |
virtual Disco::ItemList | handleDiscoNodeItems (const JID &from, const JID &to, const std::string &node) |
virtual bool | handleIq (const IQ &iq) |
virtual void | handleIqID (const IQ &iq, int context) |
virtual void | handleDiscoInfo (const JID &from, const Disco::Info &info, int context) |
virtual void | handleDiscoItems (const JID &from, const Disco::Items &items, int context) |
virtual void | handleDiscoError (const JID &from, const Error *error, int context) |
Public Member Functions inherited from DiscoNodeHandler | |
virtual | ~DiscoNodeHandler () |
Public Member Functions inherited from DiscoHandler | |
virtual | ~DiscoHandler () |
virtual bool | handleDiscoSet (const IQ &iq) |
Public Member Functions inherited from IqHandler | |
virtual | ~IqHandler () |
This class implements a provider for XEP-0050 (Ad-hoc Commands).
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.
To offer commands to remote entities, 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:
In this example, MyClass is AdhocCommandProvider-derived so it is obviously the command handler, too.
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.
To execute commands offered by a remote entity:
...TBC...
XEP version: 1.2
Adhoc | ( | ClientBase * | parent | ) |
Constructor. Creates a new Adhoc client that registers as IqHandler with a ClientBase.
parent | The ClientBase used for XMPP communication. |
void checkSupport | ( | const JID & | remote, |
AdhocHandler * | ah, | ||
int | context = 0 |
||
) |
void execute | ( | const JID & | remote, |
const Adhoc::Command * | command, | ||
AdhocHandler * | ah, | ||
int | context = 0 |
||
) |
Executes or continues the given command on the given remote entity. To construct the command
object, it is recommended to use either Command( const std::string&, Action ) to begin execution of a command, or Command( const std::string&, const std::string&, Action ) to continue execution of a command.
remote | The remote entity's JID. |
command | The command to execute. |
ah | The object handling the result of this request. |
context | A user defined context. |
void getCommands | ( | const JID & | remote, |
AdhocHandler * | ah, | ||
int | context = 0 |
||
) |
Retrieves a list of commands from the remote entity. You should check whether the remote entity actually supports Adhoc Commands by means of checkSupport().
remote | The remote entity's JID. |
ah | The object handling the result of this request. |
context | A user defined context. |
Reimplement this function to receive disco error notifications.
from | The sender of the error result. |
error | The Error. May be 0. |
context | A context identifier. |
Implements DiscoHandler.
|
virtual |
Reimplement this function if you want to be notified about the result of an disco::info query.
from | The sender of the disco::info result. |
info | The Info. |
context | A context identifier. |
Implements DiscoHandler.
|
virtual |
Reimplement this function if you want to be notified about the result of a disco::items query.
from | The sender of the disco::items result. |
items | The Items. |
context | A context identifier. |
Implements DiscoHandler.
|
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.
from | The sender of the request. |
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
|
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.
from | The sender of the request. |
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
|
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.
from | The sender of the request. |
to | The receiving JID (useful for transports). |
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
|
virtual |
Reimplement this function if you want to be notified about incoming IQs.
iq | The complete IQ stanza. |
Implements IqHandler.
|
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 empty positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.
iq | The complete IQ 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 XEP-0050.
acp | The object 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. |
void respond | ( | const JID & | remote, |
const Adhoc::Command * | command, | ||
const Error * | error = 0 |
||
) |
Use this function to respond to an execution request submitted by means of AdhocCommandProvider::handleAdhocCommand(). It is recommended to use Command( const std::string&, const std::string&, Status, AdhocPlugin* ) to construct the command
object. Optionally, an Error object can be included. In that case the IQ sent is of type error
.