Manager Class Reference

`#include <pubsubmanager.h>`

Inheritance diagram for Manager:
[legend]

## 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 | subscribe (const JID &service, const std::string &node, ResultHandler *handler, const JID &jid, DataForm *options)
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 &subid=EmptyString)
const std::string | setSubscriptionOptions (const JID &service, const JID &jid, const std::string &node, DataForm *df, ResultHandler *handler, const std::string &subid=EmptyString)
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)
Public Member Functions inherited from IqHandler
virtual | ~IqHandler ()

## 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() );
  gloox::PubSub::Event
  This is an implementation of a PubSub Notification as a StanzaExtension.
  Definition pubsubevent.h:35
- 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
  }
  gloox::ExtPubSubEvent
  @ ExtPubSubEvent
  Definition stanzaextension.h:86

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 Schröter js@ca.nosp@m.maya.nosp@m..net
  Vincent Thomasset vthom.nosp@m.asse.nosp@m.t@gma.nosp@m.il.c.nosp@m.om

Since
  1.0

Definition at line 78 of file pubsubmanager.h.

## Constructor & Destructor Documentation

## Manager()

Manager | ( | ClientBase * | parent | ) |

Initialize the manager.

Parameters

  parent | Client to which this manager belongs.

Definition at line 582 of file pubsubmanager.cpp.

## ~Manager()

virtual ~Manager | ( |  | ) |

inline virtual

Default virtual destructor.

Definition at line 91 of file pubsubmanager.h.

## Member Function Documentation

## createNode()

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 829 of file pubsubmanager.cpp.

## deleteItem()

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 805 of file pubsubmanager.cpp.

## deleteNode()

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 853 of file pubsubmanager.cpp.

## getAffiliates()

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

## getAffiliations() [1/2]

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

## getAffiliations() [2/2]

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

## getDefaultNodeConfig()

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 874 of file pubsubmanager.cpp.

## getNodeConfig()

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

## getSubscribers()

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

## getSubscriptionOptions()

const std::string getSubscriptionOptions | ( | const JID & | service,
|  | const JID & | jid,
|  | const std::string & | node,
|  | ResultHandler * | handler,
|  | const std::string & | subid = EmptyString )

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.
  subid | An optional subscription ID.

Returns
  The IQ ID used in the request.

See also
  ResultHandler::handleSubscriptionOptions

Definition at line 199 of file pubsubmanager.h.

## getSubscriptions()

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

## handleIq()

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, an 'error' will be sent back.

Since
  1.0

Implements IqHandler.

Definition at line 490 of file pubsubmanager.h.

## handleIqID()

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 empty 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 1007 of file pubsubmanager.cpp.

## publishItem()

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 778 of file pubsubmanager.cpp.

## purgeNode()

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 972 of file pubsubmanager.cpp.

## removeID()

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 993 of file pubsubmanager.cpp.

## requestItems() [1/2]

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 754 of file pubsubmanager.cpp.

## requestItems() [2/2]

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 730 of file pubsubmanager.cpp.

## setAffiliates()

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

## setNodeConfig()

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

## setSubscribers()

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

## setSubscriptionOptions()

const std::string setSubscriptionOptions | ( | const JID & | service,
|  | const JID & | jid,
|  | const std::string & | node,
|  | DataForm * | df,
|  | ResultHandler * | handler,
|  | const std::string & | subid = EmptyString )

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.
  subid | An optional subscription ID.

Returns
  The IQ ID used in the request.

See also
  ResultHandler::handleSubscriptionOptionsResult

Definition at line 219 of file pubsubmanager.h.

## subscribe() [1/2]

const std::string subscribe | ( | const JID & | service,
|  | const std::string & | node,
|  | ResultHandler * | handler,
|  | const JID & | jid,
|  | DataForm * | options )

Subscribe to a node and configure options.

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).
  options | The options to configure while subscribing. Should be a TypeSubmit form, with a field named FORM_TYPE having the value http://jabber.org/protocol/pubsub#subscribe_options See XEP-0060, "Subscribe and Configure". Will be owned and deleted by the PubSub object.

Returns
  The IQ ID used in the request.

See also
  ResultHandler::handleSubscriptionResult

Definition at line 651 of file pubsubmanager.cpp.

## subscribe() [2/2]

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 611 of file pubsubmanager.cpp.

## unsubscribe()

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 678 of file pubsubmanager.cpp.

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

- pubsubmanager.h
- pubsubmanager.cpp