RosterManager Class Reference

`#include <rostermanager.h>`

Inheritance diagram for RosterManager:
[legend]

## Public Member Functions

| RosterManager (ClientBase *parent)
virtual | ~RosterManager ()
void | fill ()
Roster * | roster ()
void | subscribe (const JID &jid, const std::string &name=EmptyString, const StringList &groups=StringList(), const std::string &msg=EmptyString)
void | synchronize ()
void | add (const JID &jid, const std::string &name, const StringList &groups)
void | unsubscribe (const JID &jid, const std::string &msg=EmptyString)
void | cancel (const JID &jid, const std::string &msg=EmptyString)
void | remove (const JID &jid)
void | ackSubscriptionRequest (const JID &to, bool ack)
const std::string & | delimiter () const
void | setDelimiter (const std::string &delimiter)
RosterItem * | getRosterItem (const JID &jid)
void | registerRosterListener (RosterListener *rl, bool syncSubscribeReq=true)
void | removeRosterListener ()
virtual bool | handleIq (const IQ &iq)
virtual void | handleIqID (const IQ &iq, int context)
virtual void | handlePresence (const Presence &presence)
virtual void | handleSubscription (const Subscription &subscription)
virtual void | handlePrivateXML (const Tag *xml)
virtual void | handlePrivateXMLResult (const std::string &uid, PrivateXMLResult pxResult)
Public Member Functions inherited from IqHandler
virtual | ~IqHandler ()
Public Member Functions inherited from PresenceHandler
virtual | ~PresenceHandler ()
Public Member Functions inherited from SubscriptionHandler
virtual | ~SubscriptionHandler ()
Public Member Functions inherited from PrivateXMLHandler
virtual | ~PrivateXMLHandler ()

## Additional Inherited Members

Public Types inherited from PrivateXMLHandler
enum | PrivateXMLResult { PxmlStoreOk , PxmlStoreError , PxmlRequestError }

## Detailed Description

This class implements Jabber/XMPP roster handling in the jabber:iq:roster namespace.

It takes care of changing presence, subscriptions, etc. You can modify any number of RosterItems within the Roster at any time. These changes must be synchronized with the server by calling synchronize(). Note that incoming Roster pushes initiated by other resources may overwrite changed values. Additionally, XEP-0083 (Nested Roster Groups) is implemented herein.

Author
  Jakob Schröter js@ca.nosp@m.maya.nosp@m..net

Since
  0.3

Definition at line 47 of file rostermanager.h.

## Constructor & Destructor Documentation

## RosterManager()

RosterManager | ( | ClientBase * | parent | ) |

Creates a new RosterManager.

Parameters

  parent | The ClientBase which is used for communication.

Definition at line 108 of file rostermanager.cpp.

## ~RosterManager()

~RosterManager | ( |  | ) |

virtual

Virtual destructor.

Definition at line 124 of file rostermanager.cpp.

## Member Function Documentation

## ackSubscriptionRequest()

void ackSubscriptionRequest | ( | const JID & | to,
|  | bool | ack )

Use this function to acknowledge a subscription request if you requested asynchronous subscription request handling.

Parameters

  to | The JID to authorize/decline.
  ack | Whether to authorize or decline the contact's request.

Definition at line 296 of file rostermanager.cpp.

## add()

void add | ( | const JID & | jid,
|  | const std::string & | name,
|  | const StringList & | groups )

Use this function to add a contact to the roster. No subscription request is sent.

Note
  Use unsubscribe() to remove an item from the roster.

Parameters

  jid | The JID to add.
  name | The displayed name of the contact.
  groups | A list of groups the contact belongs to.

Definition at line 248 of file rostermanager.cpp.

## cancel()

void cancel | ( | const JID & | jid,
|  | const std::string & | msg = EmptyString )

Use this function to cancel the contact's subscription to your presence. The contact will no longer receive presence from you.

Parameters

  jid | The contact's JID.
  msg | A message to send along with the request.

Since
  0.9

Note
  Use remove() to remove a contact from the roster and to cancel its subscriptions.

Definition at line 265 of file rostermanager.cpp.

## delimiter()

const std::string & delimiter | ( |  | ) | const

inline

Use this function to retrieve the delimiter of Nested Roster Groups (XEP-0083).

Returns
  The group delimiter.

Since
  0.7

Definition at line 141 of file rostermanager.h.

## fill()

void fill | ( |  | ) |

This function does the initial filling of the roster with the current server-side roster.

Definition at line 145 of file rostermanager.cpp.

## getRosterItem()

RosterItem * getRosterItem | ( | const JID & | jid | ) |

Lets you retrieve the RosterItem that belongs to the given JID.

Parameters

  jid | The JID to return the RosterItem for.

Definition at line 377 of file rostermanager.cpp.

## handleIq()

bool handleIq | ( | const IQ & | iq | ) |

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 157 of file rostermanager.cpp.

## 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 172 of file rostermanager.cpp.

## handlePresence()

void handlePresence | ( | const Presence & | presence | ) |

virtual

Reimplement this function if you want to be updated on incoming presence notifications.

Parameters

  presence | The complete stanza.

Since
  1.0

Implements PresenceHandler.

Definition at line 199 of file rostermanager.cpp.

## handlePrivateXML()

void handlePrivateXML | ( | const Tag * | xml | ) |

virtual

Reimplement this function to receive the private XML that was requested earlier using `PrivateXML::requestXML()`.

Parameters

  xml | The private xml, i.e. the first child of the <query> tag. May be 0. You should not delete the object.

Implements PrivateXMLHandler.

Definition at line 367 of file rostermanager.cpp.

## handlePrivateXMLResult()

void handlePrivateXMLResult | ( | const std::string & | uid,
|  | PrivateXMLResult | pxResult )

virtual

This function is called to notify about the result of a 'store' or 'request' operation (successful requests are announced by means of handlePrivateXML()).

Parameters

  uid | The ID of the query.
  pxResult | The result of the operation.

Since
  0.7

Implements PrivateXMLHandler.

Definition at line 373 of file rostermanager.cpp.

## handleSubscription()

void handleSubscription | ( | const Subscription & | subscription | ) |

virtual

Reimplement this function if you want to be notified about incoming subscriptions/subscription requests.

Parameters

  subscription | The complete Subscription stanza.

Since
  1.0

Implements SubscriptionHandler.

Definition at line 303 of file rostermanager.cpp.

## registerRosterListener()

void registerRosterListener | ( | RosterListener * | rl,
|  | bool | syncSubscribeReq = true )

Register `rl` as object that receives updates on roster operations. For GUI applications it may be necessary to display a dialog or whatever to the user without blocking. If you want that, use asynchronous subscription requests. If you want to answer a request right away, make it synchronous.

Parameters

  rl | The object that receives roster updates.
  syncSubscribeReq | Indicates whether (Un)SubscriptionRequests shall be handled synchronous (true) or asynchronous (false). Default: synchronous.

Definition at line 347 of file rostermanager.cpp.

## remove()

void remove | ( | const JID & | jid | ) |

Use this function to remove a contact from the roster. Subscription is implicitely cancelled.

Parameters

  jid | The contact's JID.

Since
  0.9

Definition at line 271 of file rostermanager.cpp.

## removeRosterListener()

void removeRosterListener | ( |  | ) |

Complementary function to registerRosterListener. Removes the current RosterListener. Roster events will not be delivered anywhere.

Definition at line 353 of file rostermanager.cpp.

## roster()

Roster * roster | ( |  | ) |

This function returns the roster.

Returns
  Returns a map of JIDs with their current presence.

Definition at line 140 of file rostermanager.cpp.

## setDelimiter()

void setDelimiter | ( | const std::string & | delimiter | ) |

Use this function to set the group delimiter (XEP-0083).

Parameters

  delimiter | The group delimiter.

Since
  0.7

Definition at line 359 of file rostermanager.cpp.

## subscribe()

void subscribe | ( | const JID & | jid,
|  | const std::string & | name = EmptyString,
|  | const StringList & | groups = StringList(),
|  | const std::string & | msg = EmptyString )

Use this function to subscribe to a new JID. The contact is added to the roster automatically (by compliant servers, as required by RFC 3921).

Parameters

  jid | The address to subscribe to.
  name | The displayed name of the contact.
  groups | A list of groups the contact belongs to.
  msg | A message sent along with the request.

Definition at line 235 of file rostermanager.cpp.

## synchronize()

void synchronize | ( |  | ) |

Synchronizes locally modified RosterItems back to the server.

Definition at line 282 of file rostermanager.cpp.

## unsubscribe()

void unsubscribe | ( | const JID & | jid,
|  | const std::string & | msg = EmptyString )

Use this function to unsubscribe from a contact's presence. You will no longer receive presence from this contact.

Parameters

  jid | The address to unsubscribe from.
  msg | A message to send along with the request.

Since
  0.9

Note
  Use remove() to remove a contact from the roster and to cancel its subscriptions.

Definition at line 259 of file rostermanager.cpp.

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

- rostermanager.h
- rostermanager.cpp