gloox  1.0.1
Classes | Public Member Functions | List of all members
Adhoc Class Reference

#include <adhoc.h>

Inheritance diagram for Adhoc:
Inheritance graph
[legend]

Classes

class  Command
 An abstraction of an Adhoc Command element (from Adhoc Commands, XEP-0050) as a StanzaExtension. More...

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 ()

Detailed Description

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:

MyClass::someFunc()
{
Adhoc* m_adhoc = new Adhoc( m_client );
// 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" );
[...]
}

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

Author
Jakob Schroeter js@ca.nosp@m.maya.nosp@m..net

Definition at line 81 of file adhoc.h.

Constructor & Destructor Documentation

Adhoc ( ClientBase parent)

Constructor. Creates a new Adhoc client that registers as IqHandler with a ClientBase.

Parameters
parentThe ClientBase used for XMPP communication.

Definition at line 216 of file adhoc.cpp.

~Adhoc ( )
virtual

Virtual destructor.

Definition at line 229 of file adhoc.cpp.

Member Function Documentation

void checkSupport ( const JID remote,
AdhocHandler ah,
int  context = 0 
)

This function queries the given remote entity for Adhoc Commands support.

Parameters
remoteThe remote entity's JID.
ahThe object handling the result of this request.
contextA user defined context.

Definition at line 414 of file adhoc.cpp.

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.

Parameters
remoteThe remote entity's JID.
commandThe command to execute.
ahThe object handling the result of this request.
contextA user defined context.

Definition at line 448 of file adhoc.cpp.

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().

Parameters
remoteThe remote entity's JID.
ahThe object handling the result of this request.
contextA user defined context.

Definition at line 431 of file adhoc.cpp.

void handleDiscoError ( const JID from,
const Error error,
int  context 
)
virtual

Reimplement this function to receive disco error notifications.

Parameters
fromThe sender of the error result.
errorThe Error. May be 0.
contextA context identifier.
Since
1.0

Implements DiscoHandler.

Definition at line 398 of file adhoc.cpp.

void handleDiscoInfo ( const JID from,
const Disco::Info info,
int  context 
)
virtual

Reimplement this function if you want to be notified about the result of an disco::info query.

Parameters
fromThe sender of the disco::info result.
infoThe Info.
contextA context identifier.
Since
1.0

Implements DiscoHandler.

Definition at line 353 of file adhoc.cpp.

void handleDiscoItems ( const JID from,
const Disco::Items items,
int  context 
)
virtual

Reimplement this function if you want to be notified about the result of a disco::items query.

Parameters
fromThe sender of the disco::items result.
itemsThe Items.
contextA context identifier.
Since
1.0

Implements DiscoHandler.

Definition at line 371 of file adhoc.cpp.

StringList handleDiscoNodeFeatures ( const JID from,
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.

Parameters
fromThe sender of the request.
nodeThe node this handler is supposed to handle.
Returns
A list of features supported by this node.

Implements DiscoNodeHandler.

Definition at line 246 of file adhoc.cpp.

Disco::IdentityList handleDiscoNodeIdentities ( const JID from,
const std::string &  node 
)
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.

Parameters
fromThe sender of the request.
nodeThe node this handler is supposed to handle.
Returns
A list of identities for the given node. The caller will own the identities.

Implements DiscoNodeHandler.

Definition at line 278 of file adhoc.cpp.

Disco::ItemList handleDiscoNodeItems ( const JID from,
const JID to,
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.

Parameters
fromThe sender of the request.
toThe receiving JID (useful for transports).
nodeThe node this handler is supposed to handle.
Returns
A list of items supported by this node.

Implements DiscoNodeHandler.

Definition at line 254 of file adhoc.cpp.

bool handleIq ( const IQ iq)
virtual

Reimplement this function if you want to be notified about incoming IQs.

Parameters
iqThe complete IQ stanza.
Returns
Indicates whether a request of type 'get' or 'set' has been handled. This includes the obligatory 'result' answer. If you return false, a 'error' will be sent.
Since
1.0

Implements IqHandler.

Definition at line 288 of file adhoc.cpp.

void handleIqID ( const IQ iq,
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.

Parameters
iqThe complete IQ stanza.
contextA value to restore context, stored with ClientBase::trackID().
Note
Only IQ stanzas of type 'result' or 'error' can arrive here.
Since
1.0

Implements IqHandler.

Definition at line 309 of file adhoc.cpp.

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.

Parameters
acpThe object to register as handler for the specified command.
commandThe node name of the command. Will be announced in disco::items.
nameThe natural-language name of the command. Will be announced in disco::items.

Definition at line 342 of file adhoc.cpp.

void removeAdhocCommandProvider ( const std::string &  command)

Use this function to unregister an adhoc command previously registered using registerAdhocCommandProvider().

Parameters
commandThe command to unregister.

Definition at line 487 of file adhoc.cpp.

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, DataForm* ) to construct the command object. Optionally, an Error object can be included. In that case the IQ sent is of type error.

Parameters
remoteThe requester's JID.
commandThe response. The Adhoc object will own and delete the command object pointed to.
errorAn optional Error obejct to include.

Definition at line 470 of file adhoc.cpp.


The documentation for this class was generated from the following files: