gloox::PubSub::Manager

Manager Class Reference

This manager is used to interact with PubSub services (XEP-0060). More...

#include <pubsubmanager.h>

Inherits IqHandler.

Inheritance diagram for Manager:

[legend]List of all members.


Public Member Functions
	Manager (ClientBase *parent)
virtual	~Manager ()
void	subscribe (const JID &service, const std::string &node, ResultHandler *handler, const JID &jid=JID(), SubscriptionObject type=SubscriptionNodes, int depth=1)
void	unsubscribe (const JID &service, const std::string &node, ResultHandler *handler, const JID &jid=JID())
void	getSubscriptions (const JID &service, ResultHandler *handler)
void	getAffiliations (const JID &service, ResultHandler *handler)
void	getSubscriptionOptions (const JID &service, const JID &jid, const std::string &node, ResultHandler *handler)
void	setSubscriptionOptions (const JID &service, const JID &jid, const std::string &node, const DataForm &df, ResultHandler *handler)
void	getAffiliations (const JID &service, const std::string &node, ResultHandler *handler)
void	publishItem (const JID &service, const std::string &node, Tag item, ResultHandler handler)
void	deleteItem (const JID &service, const std::string &node, const std::string &item, ResultHandler *handler)
void	getItems (const JID &service, const std::string &node, ResultHandler *handler)
void	createNode (NodeType type, const JID &service, const std::string &node, ResultHandler handler, const std::string &name=EmptyString, const std::string &parent=EmptyString, AccessModel access=AccessDefault, const StringMap config=0)
void	createLeafNode (const JID &service, const std::string &node, ResultHandler handler, const std::string &name, const std::string &parent=EmptyString, AccessModel access=AccessDefault, const StringMap config=0)
void	createCollectionNode (const JID &service, const std::string &node, ResultHandler handler, const std::string &name, const std::string &parent=EmptyString, AccessModel access=AccessDefault, const StringMap config=0)
void	deleteNode (const JID &service, const std::string &node, ResultHandler *handler)
void	getDefaultNodeConfig (const JID &service, NodeType type, ResultHandler *handler)
void	purgeNode (const JID &service, const std::string &node, ResultHandler *handler)
void	getSubscribers (const JID &service, const std::string &node, ResultHandler *handler)
void	setSubscribers (const JID &service, const std::string &node, const SubscriberList &list, ResultHandler *handler)
void	getAffiliates (const JID &service, const std::string &node, ResultHandler *handler)
void	setAffiliates (const JID &service, const std::string &node, const AffiliateList &list, ResultHandler *handler)
void	getNodeConfig (const JID &service, const std::string &node, ResultHandler *handler)
void	setNodeConfig (const JID &service, const std::string &node, const DataForm &config, ResultHandler *handler)
void	registerEventHandler (EventHandler *handler)
void	removeEventHandler (EventHandler *handler)
virtual bool	handleIq (const IQ &iq)
virtual void	handleIqID (const IQ &iq, int context)

Detailed Description

This manager is used to interact with PubSub services (XEP-0060).

Note:: PubSub support in gloox is still relatively young and you are most welcome to ask questions, criticize the API and so on. For contact informations, see below.

This manager acts in concert with 2 different handlers:

EventHandler is responsible for receiving the PubSub event notifications. Register as much as you need with the Manager.

ResultHandler is used to receive a request's result. Depending on the context, this can be a notification that an item has been succesfully deleted (or not), or the default node configuration for a service.

Note that many PubSub queries will both trigger a notification from registered EventHandler's and from the ResultHandler specific to the query.

To get started with PubSub in gloox, create a Manager, implement the PubSub::EventHandler virtuals and register an instance with a Manager. This will get you notified of PubSub events sent to you.

Next, to be able to interact with PubSub services, you will need to implement the ResultHandler virtuals interfaces to be notified of the result of requests and pass these along to these requests (null handlers are not allowed).

Note:: A null ResultHandler to a query is not allowed and is a no-op.

Here's an example.

EventHandler::handleItemPublication() can be called with or without the actual tag, depending on if the notification actually includes the payload. From there you could only record the event and be done with it, or decide to retrieve the full payload. Eg:

 class MyEventHandler : public gloox::EventHandler
 {
   // ...
 };

 void MyEventHandler::handleItemPublication( const JID& service,
                                             const std::string& node,
                                             const std::string& item,
                                             const Tag* entry )
 {
   // we want to retrieve the payload everytime
   if( !entry )
   {
     m_manager->requestItem( service, node, item, this );
   }
   else
   {
     do_something_useful( entry );
   }
 }

In response to this request, MyResultHandler::handleItem() will be called.

XEP Version: 1.9

Author:: Vincent Thomasset <vthomasset@gmail.com>

Since:: 1.0

Todo:

Implement Subscription request management.
Update to XEP version 1.10.
Write tests and examples.
Check for possible ways to have generic handleResult method(s) in ResultHandler.
Implement unsubscription result notification (aka sub id tracking)

Definition at line 112 of file pubsubmanager.h.

Constructor & Destructor Documentation

Manager ( ClientBase * parent )

Initialize the manager.
Parameters:

parent Client to which this manager belongs to.

Definition at line 108 of file pubsubmanager.cpp.

virtual ~Manager ( ) [inline, virtual]

Default virtual destructor.
Definition at line 125 of file pubsubmanager.h.

Member Function Documentation

void createCollectionNode ( const JID & service,

const std::string & node,

ResultHandler * handler,

const std::string & name,

const std::string & parent = EmptyString,

AccessModel access = AccessDefault,

const StringMap * config = 0

) [inline]

Creates a new collection node.

Parameters:

service Service where to create the new node.

node The ID of the new node.

name The name of the new node.

parent ID of the parent node. If empty, the node will be located at the root of the service.

access The node's access model.

config A map of further node configuration options. The keys of the map must be in the form of 'pubsub#name', where 'name' is a valid pubsub option. It is not necessary to include an access model config option. Use the access parameter instead. See XEP-0068 Sect. 8 for valid options.

See also:
ResultHandler::handleNodeCreation

Definition at line 349 of file pubsubmanager.h.

void createLeafNode ( const JID & service,

const std::string & node,

ResultHandler * handler,

const std::string & name,

const std::string & parent = EmptyString,

AccessModel access = AccessDefault,

const StringMap * config = 0

) [inline]

Creates a new leaf node.

Parameters:

service Service where to create the new node.

node The ID of the new node.

name The name of the new node.

parent ID of the parent node. If empty, the node will be located at the root of the service.

access The node's access model.

config A map of further node configuration options. The keys of the map must be in the form of 'pubsub#name', where 'name' is a valid pubsub option. Do not use this map to include an access model config option, use the access parameter instead. See XEP-0068 Sect. 8 for valid options.

See also:
ResultHandler::handleNodeCreation

Definition at line 322 of file pubsubmanager.h.

void createNode ( NodeType type,

const JID & service,

const std::string & node,

ResultHandler * handler,

const std::string & name = EmptyString,

const std::string & parent = EmptyString,

AccessModel access = AccessDefault,

const StringMap * config = 0

)

Creates a new node.

Parameters:

type The type of the new node.

service Service where to create the new node.

node The ID of the new node.

name The name of the new node.

parent ID of the parent node. If empty, the node will be located at the root of the service.

access The node's access model.

config A map of further node configuration options. The keys of the map should be in the form of 'pubsub#name', where 'name' is a valid pubsub option. Do not use this map to include an access model config option, use the access parameter instead. See XEP-0068 Sect. 8 for valid options.

See also:
ResultHandler::handleNodeCreation

Definition at line 365 of file pubsubmanager.cpp.

void deleteItem ( const JID & service,

const std::string & node,

const std::string & item,

ResultHandler * handler

)

Delete an item from a node.

Parameters:

service Service hosting the node.

node ID of the node to delete the item from.

item ID of the item in the node.

See also:
ResultHandler::handleItemDeletation

Definition at line 347 of file pubsubmanager.cpp.

void deleteNode ( const JID & service,

const std::string & node,

ResultHandler * handler

)

Deletes a node.

Parameters:

service Service where to create the new node.

node Node ID of the new node.

See also:
ResultHandler::handleNodeDeletation

Definition at line 423 of file pubsubmanager.cpp.

void getAffiliates ( const JID & service,

const std::string & node,

ResultHandler * handler

) [inline]

Requests the affiliate list for a node.

Parameters:

service Service to query.

node Node ID of the node.

handler ResultHandler.

See also:
ResultHandler::handleAffiliates

Definition at line 444 of file pubsubmanager.h.

void getAffiliations ( const JID & service,

const std::string & node,

ResultHandler * handler

)

Requests the affiliation list for a node.

Parameters:

service Service to query.

node Node ID of the node.

handler The AffiliationListHandler to handle the result.

See also:
ResultHandler::handleAffiliations

void getAffiliations ( const JID & service,

ResultHandler * handler

)

Requests the affiliation list from a service.

Parameters:

service Service to query.

handler The ResultHandler to handle the result.

See also:
ResultHandler::handleAffiliations

Definition at line 253 of file pubsubmanager.cpp.

void getDefaultNodeConfig ( const JID & service,

NodeType type,

ResultHandler * handler

)

Retrieves the default configuration for a specific NodeType.

Parameters:

service The queried service.

type NodeType to get default configuration for.

handler ResultHandler.

See also:
ResultHandler::handleDefaultNodeConfig

Definition at line 439 of file pubsubmanager.cpp.

void getItems ( const JID & service,

const std::string & node,

ResultHandler * handler

)

Ask for the item list of a specific node.

Parameters:

service Service hosting the node.

node ID of the node.

handler ResultHandler to send the result to.

See also:
ResultHandler::handleItems

Definition at line 537 of file pubsubmanager.cpp.

void getNodeConfig ( const JID & service,

const std::string & node,

ResultHandler * handler

) [inline]

Retrieve the configuration (options) of a node.

Parameters:

service Service hosting the node.

node ID of the node.

handler ResultHandler responsible to handle the request result.

See also:
ResultHandler::handleNodeConfig

Definition at line 473 of file pubsubmanager.h.

void getSubscribers ( const JID & service,

const std::string & node,

ResultHandler * handler

) [inline]

Requests the subscriber list for a node.

Parameters:

service Service to query.

node Node ID of the node.

handler ResultHandler.

See also:
ResultHandler::handleSubscribers

Definition at line 414 of file pubsubmanager.h.

void getSubscriptionOptions ( const JID & service,

const JID & jid,

const std::string & node,

ResultHandler * handler

) [inline]

Requests subscription options.

Parameters:

service Service to query.

jid Subscribed entity.

node Node ID of the node.

handler Node ID of the node.

slh The SubscriptionListHandler to handle the result.

See also:
ResultHandler::handleSubscriptionOptions

Definition at line 199 of file pubsubmanager.h.

void getSubscriptions ( const JID & service,

ResultHandler * handler

)

Requests the subscription list from a service.

Parameters:

service Service to query.

handler The ResultHandler to handle the result.

See also:
ResultHandler::handleSubscriptions

Definition at line 240 of file pubsubmanager.cpp.

virtual bool handleIq ( const IQ & iq ) [inline, virtual]

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

iq The 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 515 of file pubsubmanager.h.

void handleIqID ( const IQ & iq,

int context

) [virtual]

Todo:
Track context info for Unsubscription result.

Todo:

Implements IqHandler.
Definition at line 572 of file pubsubmanager.cpp.

void publishItem ( const JID & service,

const std::string & node,

Tag * item,

ResultHandler * handler

)

Publish an item to a node. The Tag to publish is destroyed by the function before returning.

Parameters:

service Service hosting the node.

node ID of the node to delete the item from.

item The item to publish.

See also:
ResultHandler::handleItemPublication

Definition at line 326 of file pubsubmanager.cpp.

void purgeNode ( const JID & service,

const std::string & node,

ResultHandler * handler

)

Removes all the items from a node.

Parameters:

service Service to query.

node Node ID of the node.

handler ResultHandler.

See also:
ResultHandler::handleNodePurge

Definition at line 552 of file pubsubmanager.cpp.

void registerEventHandler ( EventHandler * handler ) [inline]

Registers an handler to receive notification of events.

Parameters:

handler EventHandler to register.

Definition at line 498 of file pubsubmanager.h.

void removeEventHandler ( EventHandler * handler ) [inline]

Removes an handler from the list of event handlers.
Parameters:

handler EventHandler to remove.

Definition at line 505 of file pubsubmanager.h.

void setAffiliates ( const JID & service,

const std::string & node,

const AffiliateList & list,

ResultHandler * handler

) [inline]

Modifies the affiliate list for a node.

Parameters:

service Service to query.

node Node ID of the node.

list ResultHandler.

See also:
ResultHandler::handleAffiliatesResult

Definition at line 458 of file pubsubmanager.h.

void setNodeConfig ( const JID & service,

const std::string & node,

const DataForm & config,

ResultHandler * handler

) [inline]

Changes a node's configuration (options).

Parameters:

service Service to query.

node Node ID of the node.

handler ResultHandler responsible to handle the request result.

See also:
ResultHandler::handleNodeConfigResult

Definition at line 487 of file pubsubmanager.h.

void setSubscribers ( const JID & service,

const std::string & node,

const SubscriberList & list,

ResultHandler * handler

) [inline]

Modifies the subscriber list for a node. This function SHOULD only set the subscriber list to those which needs modification.

Parameters:

service Service to query.

node Node ID of the node.

list ResultHandler.

See also:
ResultHandler::handleSubscribers

Definition at line 429 of file pubsubmanager.h.

void setSubscriptionOptions ( const JID & service,

const JID & jid,

const std::string & node,

const DataForm & df,

ResultHandler * handler

) [inline]

Modifies subscription options.

Parameters:

service Service to query.

jid Subscribed entity.

node Node ID of the node.

df New configuration.

See also:
ResultHandler::handleSubscriptionOptionsResult

Definition at line 215 of file pubsubmanager.h.

void subscribe ( const JID & service,

const std::string & node,

ResultHandler * handler,

const JID & jid = JID(),

SubscriptionObject type = SubscriptionNodes,

int depth = 1

)

Subscribe to a node.

Parameters:

service Service hosting the node.

node ID of the node to subscribe to.

jid JID to subscribe. If empty, the client's JID will be used (ie self subscription).

type SubscriptionType of the subscription (Collections only).

depth Subscription depth. For 'all', use 0 (Collections only!).

See also:
ResultHandler::handleSubscriptionResult

Definition at line 266 of file pubsubmanager.cpp.

void unsubscribe ( const JID & service,

const std::string & node,

ResultHandler * handler,

const JID & jid = JID()

)

Unsubscribe from a node.

Parameters:

service Service hosting the node.

node ID of the node to unsubscribe from.

handler ResultHandler receiving the result notification.

jid JID to unsubscribe. If empty, the client's JID will be used (ie self unsubscription).

See also:
ResultHandler::handleUnsubscriptionResult

Definition at line 307 of file pubsubmanager.cpp.

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

Generated on Tue Apr 22 15:10:16 2008 for gloox by

1.4.1

Manager Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation