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 ()
const std::string	subscribe (const JID &service, const std::string &node, ResultHandler *handler, const JID &jid=JID(), SubscriptionObject type=SubscriptionNodes, int depth=1, const std::string &expire=EmptyString)
const std::string	unsubscribe (const JID &service, const std::string &node, const std::string &subid, ResultHandler *handler, const JID &jid=JID())
const std::string	getSubscriptions (const JID &service, ResultHandler *handler)
const std::string	getAffiliations (const JID &service, ResultHandler *handler)
const std::string	getSubscriptionOptions (const JID &service, const JID &jid, const std::string &node, ResultHandler *handler)
const std::string	setSubscriptionOptions (const JID &service, const JID &jid, const std::string &node, DataForm df, ResultHandler handler)
void	getAffiliations (const JID &service, const std::string &node, ResultHandler *handler)
const std::string	requestItems (const JID &service, const std::string &node, const std::string &subid, int maxItems, ResultHandler *handler)
const std::string	requestItems (const JID &service, const std::string &node, const std::string &subid, const ItemList &items, ResultHandler *handler)
const std::string	publishItem (const JID &service, const std::string &node, ItemList &items, DataForm options, ResultHandler handler)
const std::string	deleteItem (const JID &service, const std::string &node, const ItemList &items, bool notify, ResultHandler *handler)
const std::string	createNode (const JID &service, const std::string &node, DataForm config, ResultHandler handler)
const std::string	deleteNode (const JID &service, const std::string &node, ResultHandler *handler)
const std::string	getDefaultNodeConfig (const JID &service, NodeType type, ResultHandler *handler)
const std::string	purgeNode (const JID &service, const std::string &node, ResultHandler *handler)
const std::string	getSubscribers (const JID &service, const std::string &node, ResultHandler *handler)
const std::string	setSubscribers (const JID &service, const std::string &node, const SubscriberList &list, ResultHandler *handler)
const std::string	getAffiliates (const JID &service, const std::string &node, ResultHandler *handler)
const std::string	setAffiliates (const JID &service, const std::string &node, const AffiliateList &list, ResultHandler *handler)
const std::string	getNodeConfig (const JID &service, const std::string &node, ResultHandler *handler)
const std::string	setNodeConfig (const JID &service, const std::string &node, DataForm config, ResultHandler handler)
bool	removeID (const std::string &id)
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.

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

To receive PubSub events:

Tell ClientBase that you are interested in PubSub events by registering an empty PubSub::Event StanzaExtension
```
 m_client->registerStanzaExtension( new PubSub::Event() );
```
Implement a MessageHandler and register it with ClientBase, or use the MessageSession interface, at your choice,

When receiving a Message, check it for a PubSub::Event

 const PubSub::Event* pse = msg.findExtension<PubSub::Event>( ExtPubSubEvent );
 if( pse )
 {
   // use the Event
 }
 else
 {
   // no Event
 }

To interact with PubSub services, you will need to instantiate a PubSub::Manager and implement the ResultHandler virtual interfaces to be notified of the result of requests.

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

XEP Version: 1.12

Author:: Jakob Schroeter <js@camaya.net>
Vincent Thomasset <vthomasset@gmail.com>

Since:: 1.0

Definition at line 78 of file pubsubmanager.h.

Constructor & Destructor Documentation

Manager ( ClientBase * parent )

Initialize the manager.
Parameters:

parent Client to which this manager belongs.

Definition at line 556 of file pubsubmanager.cpp.

virtual ~Manager ( ) [inline, virtual]

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

Member Function Documentation

const std::string createNode ( const JID & service,

const std::string & node,

DataForm * config,

ResultHandler * handler

)

Creates a new node.

Parameters:

service Service where to create the new node.

node The ID of the new node.

config An optional DataForm that holds the node configuration. The DataForm will be owned and deleted by the Manager.

handler The handler to handle the result.

Returns:
The ID used in the request.

See also:
ResultHandler::handleNodeCreation

Definition at line 785 of file pubsubmanager.cpp.

const std::string deleteItem ( const JID & service,

const std::string & node,

const ItemList & items,

bool notify,

ResultHandler * handler

)

Delete an item from a node.

Parameters:

service Service hosting the node.

node ID of the node to delete the item from.

items A list of items to delete (only ID filled in).

notify Whether or not to notify subscribers about the deletion.

handler The handler to handle the result.

Returns:
The ID used in the request.

See also:
ResultHandler::handleItemDeletation

Definition at line 761 of file pubsubmanager.cpp.

const std::string 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.

handler The handler to handle the result.

Returns:
The ID used in the request.

See also:
ResultHandler::handleNodeDeletion

Definition at line 808 of file pubsubmanager.cpp.

const std::string 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.

Returns:
The ID used in the request.

See also:
ResultHandler::handleAffiliates

Definition at line 388 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

const std::string getAffiliations ( const JID & service,

ResultHandler * handler

) [inline]

Requests the affiliation list from a service.

Parameters:

service Service to query.

handler The ResultHandler to handle the result.

Returns:
The IQ ID used in the request.

See also:
ResultHandler::handleAffiliations

Definition at line 158 of file pubsubmanager.h.

const std::string 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.

Returns:
The ID used in the request.

See also:
ResultHandler::handleDefaultNodeConfig

Definition at line 829 of file pubsubmanager.cpp.

const std::string 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.

Returns:
The ID used in the request.

See also:
ResultHandler::handleNodeConfig

Definition at line 423 of file pubsubmanager.h.

const std::string 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.

Returns:
The ID used in the request.

See also:
ResultHandler::handleSubscribers

Definition at line 352 of file pubsubmanager.h.

const std::string 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 The SubscriptionListHandler to handle the result.

Returns:
The IQ ID used in the request.

See also:
ResultHandler::handleSubscriptionOptions

Definition at line 177 of file pubsubmanager.h.

const std::string getSubscriptions ( const JID & service,

ResultHandler * handler

) [inline]

Requests the subscription list from a service.

Parameters:

service Service to query.

handler The ResultHandler to handle the result.

Returns:
The IQ ID used in the request.

See also:
ResultHandler::handleSubscriptions

Definition at line 141 of file pubsubmanager.h.

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 465 of file pubsubmanager.h.

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:

iq The complete IQ stanza.

context A 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 961 of file pubsubmanager.cpp.

const std::string publishItem ( const JID & service,

const std::string & node,

ItemList & items,

DataForm * options,

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.

items One or more items to publish. The items will be owned and deleted by the Manager, even in the error case (empty string returned).

options An optional DataForm containing publish options. The DataForm will be owned and deleted by the Manager.

handler The handler to handle the result.

Returns:
The ID used in the request.

See also:
ResultHandler::handleItemPublication

Definition at line 734 of file pubsubmanager.cpp.

const std::string 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.

Returns:
The ID used in the request.

See also:
ResultHandler::handleNodePurge

Definition at line 926 of file pubsubmanager.cpp.

bool removeID ( const std::string & id )

Removes an ID from our tracking lists.
Parameters:

id The ID to remove.

Returns:
True if the ID was found and removed, false otherwise.

Definition at line 947 of file pubsubmanager.cpp.

const std::string requestItems ( const JID & service,

const std::string & node,

const std::string & subid,

const ItemList & items,

ResultHandler * handler

)

Requests specific items from a node.
Parameters:

service Service to query.

node Node ID of the node.

subid An optional subscription ID.

items The list of item IDs to request.

handler The handler to handle the result.

Returns:
The ID used in the request.

Definition at line 710 of file pubsubmanager.cpp.

const std::string requestItems ( const JID & service,

const std::string & node,

const std::string & subid,

int maxItems,

ResultHandler * handler

)

Requests items from a node.
Parameters:

service Service to query.

node Node ID of the node.

subid An optional subscription ID.

maxItems The optional maximum number of items to return.

handler The handler to handle the result.

Returns:
The ID used in the request.

Definition at line 686 of file pubsubmanager.cpp.

const std::string 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.

handler ResultHandler.

Returns:
The ID used in the request.

See also:
ResultHandler::handleAffiliatesResult

Definition at line 406 of file pubsubmanager.h.

const std::string setNodeConfig ( const JID & service,

const std::string & node,

DataForm * config,

ResultHandler * handler

) [inline]

Changes a node's configuration (options).

Parameters:

service Service to query.

node Node ID of the node.

config The node's configuration DataForm.

handler ResultHandler responsible to handle the request result.

Returns:
The ID used in the request.

See also:
ResultHandler::handleNodeConfigResult

Definition at line 439 of file pubsubmanager.h.

const std::string 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 The subscriber list.

handler The ResultHandler.

Returns:
The ID used in the request.

See also:
ResultHandler::handleSubscribers

Definition at line 371 of file pubsubmanager.h.

const std::string setSubscriptionOptions ( const JID & service,

const JID & jid,

const std::string & node,

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. The DataForm will be owned and deleted by the Manager.

handler The handler to handle the result.

Returns:
The IQ ID used in the request.

See also:
ResultHandler::handleSubscriptionOptionsResult

Definition at line 195 of file pubsubmanager.h.

const std::string subscribe ( const JID & service,

const std::string & node,

ResultHandler * handler,

const JID & jid = JID(),

SubscriptionObject type = SubscriptionNodes,

int depth = 1,

const std::string & expire = EmptyString

)

Subscribe to a node.

Parameters:

service Service hosting the node.

node ID of the node to subscribe to.

handler The ResultHandler.

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

expire Subscription expiry. Defaults to the empty string.

Returns:
The IQ ID used in the request.

See also:
ResultHandler::handleSubscriptionResult

Definition at line 585 of file pubsubmanager.cpp.

const std::string unsubscribe ( const JID & service,

const std::string & node,

const std::string & subid,

ResultHandler * handler,

const JID & jid = JID()

)

Unsubscribe from a node.

Parameters:

service Service hosting the node.

node ID of the node to unsubscribe from.

subid An optional, additional subscription ID.

handler ResultHandler receiving the result notification.

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

Returns:
The IQ ID used in the request.

See also:
ResultHandler::handleUnsubscriptionResult

Definition at line 637 of file pubsubmanager.cpp.

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

Generated on Sat Oct 31 19:54:43 2009 for gloox by

1.4.1

Manager Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation