Adhoc Class Reference

This class implements a provider for XEP-0050 (Ad-hoc Commands). More...

#include <adhoc.h>

Inheritance diagram for Adhoc:

Inheritance graph
[legend]
Collaboration diagram for Adhoc:

Collaboration graph
[legend]

List of all members.

Public Types

enum  AdhocCommandStatus { AdhocCommandExecuting, AdhocCommandCompleted, AdhocCommandCanceled, AdhocCommandStatusUnknown }
enum  AdhocExecuteActions {
  ActionDefault = 0, ActionPrevious = 1, ActionNext = 2, ActionComplete = 4,
  ActionCancel = 8
}
enum  AdhocNoteType { AdhocNoteInfo, AdhocNoteWarn, AdhocNoteError }

Public Member Functions

 Adhoc (ClientBase *parent)
virtual ~Adhoc ()
virtual StringList handleDiscoNodeFeatures (const std::string &node)
virtual StringMap handleDiscoNodeIdentities (const std::string &node, std::string &name)
virtual DiscoNodeItemList handleDiscoNodeItems (const std::string &node)
virtual bool handleIq (Stanza *stanza)
virtual bool handleIqID (Stanza *stanza, int context)
virtual void handleDiscoInfoResult (Stanza *stanza, int context)
virtual void handleDiscoItemsResult (Stanza *stanza, int context)
virtual void handleDiscoError (Stanza *stanza, int context)
void registerAdhocCommandProvider (AdhocCommandProvider *acp, const std::string &command, const std::string &name)
void checkSupport (const JID &remote, AdhocHandler *ah)
void getCommands (const JID &remote, AdhocHandler *ah)
void execute (const JID &remote, const std::string &command, AdhocHandler *ah, const std::string &sessionid="", DataForm *form=0, AdhocExecuteActions action=ActionDefault)
void removeAdhocCommandProvider (const std::string &command)


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@camaya.net>

Definition at line 78 of file adhoc.h.


Member Enumeration Documentation

The current status of a command.

Enumerator:
AdhocCommandExecuting  The command is being executed.
AdhocCommandCompleted  The command has completed. The command session has ended.
AdhocCommandCanceled  The command has been canceled. The command session has ended.
AdhocCommandStatusUnknown  None or unknown status.

Definition at line 84 of file adhoc.h.

Describes actions to jump between execution stages and dataform pages.

Enumerator:
ActionDefault  The default action is being executed.
ActionPrevious  Request previous page.
ActionNext  Request next page.
ActionComplete  Complete or finish the execution.
ActionCancel  Cancel command execution.

Definition at line 95 of file adhoc.h.

Describes the type of a note attached to a execution stage.

Enumerator:
AdhocNoteInfo  The note is informational only. This is not really an exceptional condition.
AdhocNoteWarn  The note indicates a warning. Possibly due to illogical (yet valid) data.
AdhocNoteError  The note indicates an error. The text should indicate the reason for the error.

Definition at line 107 of file adhoc.h.


Constructor & Destructor Documentation

Adhoc ( ClientBase parent  ) 

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

Parameters:
parent The ClientBase used for XMPP communication.

Definition at line 26 of file adhoc.cpp.

~Adhoc (  )  [virtual]

Virtual destructor.

Definition at line 38 of file adhoc.cpp.


Member Function Documentation

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.

Parameters:
node The node this handler is supposed to handle.
Returns:
A list of features supported by this node.

Implements DiscoNodeHandler.

Definition at line 50 of file adhoc.cpp.

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.

Parameters:
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.
Returns:
A map of identities for the given node. The first string is the category specifier, the second string is the type specifier.

Implements DiscoNodeHandler.

Definition at line 83 of file adhoc.cpp.

DiscoNodeItemList 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.

Parameters:
node The node this handler is supposed to handle.
Returns:
A list of items supported by this node.

Implements DiscoNodeHandler.

Definition at line 57 of file adhoc.cpp.

bool handleIq ( Stanza stanza  )  [virtual]

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

Parameters:
stanza The complete 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.

Implements IqHandler.

Definition at line 99 of file adhoc.cpp.

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.

Parameters:
stanza The complete Stanza.
context A value to restore context, stored with ClientBase::trackID().
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.

Implements IqHandler.

Definition at line 119 of file adhoc.cpp.

void handleDiscoInfoResult ( Stanza stanza,
int  context 
) [virtual]

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

Parameters:
stanza The full Stanza.
context A context identifier.
Todo:
Replace the stanza with decoded values.

Implements DiscoHandler.

Definition at line 197 of file adhoc.cpp.

void handleDiscoItemsResult ( Stanza stanza,
int  context 
) [virtual]

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

Parameters:
stanza The full Stanza.
context A context identifier.
Todo:
Replace the stanza with decoded values.

Implements DiscoHandler.

Definition at line 217 of file adhoc.cpp.

void handleDiscoError ( Stanza stanza,
int  context 
) [virtual]

Reimplement this function to receive disco error notifications.

Parameters:
stanza The full Stanza.
context A context identifier.
Todo:
Replace the stanza with decoded values.

Implements DiscoHandler.

Definition at line 251 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:
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.

Definition at line 189 of file adhoc.cpp.

void checkSupport ( const JID remote,
AdhocHandler ah 
)

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

Parameters:
remote The remote entity's JID.
ah The object handling the result of this request.

Definition at line 265 of file adhoc.cpp.

void getCommands ( const JID remote,
AdhocHandler ah 
)

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:
remote The remote entity's JID.
ah The object handling the result of this request.

Definition at line 278 of file adhoc.cpp.

void execute ( const JID remote,
const std::string &  command,
AdhocHandler ah,
const std::string &  sessionid = "",
DataForm form = 0,
AdhocExecuteActions  action = ActionDefault 
)

Executes the given command on the given remote entity. For initial execution requests, only the first three parameters are required. For subsequent requests (of a multiple stages request) at least sessionid and form should be provided (depending on the command being executed, of course).

Parameters:
remote The remote entity's JID.
command The command to execute.
ah The object handling the result of this request.
sessionid The sessionid identifying the command currenly being executed. Must be empty on first request.
form A DataForm containing the result of a previous response. Must be left empty on first request.
action The action to take, e.g. navigatte o the previous 'screen'.

Definition at line 291 of file adhoc.cpp.

void removeAdhocCommandProvider ( const std::string &  command  ) 

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

Parameters:
command The command to unregister.

Definition at line 342 of file adhoc.cpp.


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

Generated on Sun Apr 27 11:08:17 2008 for gloox by  doxygen 1.5.5