RosterManager Class Reference

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

#include <rostermanager.h>

Inherits IqHandler, PresenceHandler, SubscriptionHandler, and PrivateXMLHandler.

Inheritance diagram for RosterManager:

Inheritance graph
[legend]
Collaboration diagram for RosterManager:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 RosterManager (ClientBase *parent, bool self=false)
virtual ~RosterManager ()
void fill ()
RosterListener::Rosterroster ()
void subscribe (const std::string &jid, const std::string &name, StringList &groups, const std::string &msg)
void synchronize ()
void add (const std::string &jid, const std::string &name, StringList &groups)
void unsubscribe (const std::string &jid, const std::string &msg, bool remove)
void ackSubscriptionRequest (const JID &to, bool ack)
const std::string & delimiter () const
void setDelimiter (const std::string &delimiter)
void registerRosterListener (RosterListener *rl, bool syncSubscribeReq=true)
void removeRosterListener ()
virtual bool handleIq (Stanza *stanza)
virtual bool handleIqID (Stanza *, int)
virtual void handlePresence (Stanza *stanza)
virtual void handleSubscription (Stanza *stanza)
virtual void handlePrivateXML (const std::string &tag, Tag *xml)
virtual void handlePrivateXMLResult (const std::string uid, PrivateXMLResult result)

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, JEP-0083 (Nested Roster Groups) is implemented herein.

Author:
Jakob Schroeter <js@camaya.net>

Definition at line 44 of file rostermanager.h.


Constructor & Destructor Documentation

RosterManager ClientBase parent,
bool  self = false
 

Creates a new RosterManager.

Parameters:
parent The Client which is used for communication.
self Whether to automatically include a self-contact in the roster. Default: false.

Definition at line 25 of file rostermanager.cpp.

References JID::bare(), ClientBase::jid(), ClientBase::registerIqHandler(), ClientBase::registerPresenceHandler(), and ClientBase::registerSubscriptionHandler().

~RosterManager  )  [virtual]
 

Virtual destructor.

Definition at line 45 of file rostermanager.cpp.

References ClientBase::removeIqHandler(), ClientBase::removePresenceHandler(), and ClientBase::removeSubscriptionHandler().


Member Function Documentation

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

References Tag::addAttrib(), JID::bare(), ClientBase::jid(), and ClientBase::send().

Referenced by RosterManager::handleSubscription().

void add const std::string &  jid,
const std::string &  name,
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 163 of file rostermanager.cpp.

References Tag::addAttrib(), Tag::addChild(), and ClientBase::getID().

Referenced by RosterManager::subscribe().

const std::string& delimiter  )  const [inline]
 

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

Returns:
The group delimiter.
Since:
0.7

Definition at line 118 of file rostermanager.h.

void fill  ) 
 

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

Definition at line 68 of file rostermanager.cpp.

References Tag::addAttrib(), Tag::addChild(), ClientBase::getID(), PrivateXML::requestXML(), and ClientBase::send().

Referenced by RosterManager::handlePrivateXML(), and RosterManager::handlePrivateXMLResult().

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

References RosterListener::roster(), gloox::STANZA_IQ_RESULT, and Stanza::subtype().

virtual bool handleIqID Stanza ,
int 
[inline, 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 148 of file rostermanager.h.

void handlePresence Stanza stanza  )  [virtual]
 

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

Parameters:
stanza The complete stanza.

Implements PresenceHandler.

Definition at line 110 of file rostermanager.cpp.

References JID::bare(), Stanza::from(), RosterListener::itemAvailable(), RosterListener::itemChanged(), RosterListener::itemUnavailable(), gloox::PRESENCE_AVAILABLE, gloox::PRESENCE_UNAVAILABLE, Stanza::show(), and Stanza::status().

void handlePrivateXML const std::string &  tag,
Tag xml
[virtual]
 

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

Parameters:
tag The tag of the storage packet.
xml The private xml, i.e. the first child of the <query> tag.

Implements PrivateXMLHandler.

Definition at line 425 of file rostermanager.cpp.

References Tag::cdata(), and RosterManager::fill().

void handleSubscription Stanza stanza  )  [virtual]
 

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

Parameters:
stanza The complete Stanza.

Implements SubscriptionHandler.

Definition at line 272 of file rostermanager.cpp.

References RosterManager::ackSubscriptionRequest(), JID::bare(), Stanza::from(), gloox::STANZA_S10N_SUBSCRIBE, Stanza::status(), RosterListener::subscriptionRequest(), and Stanza::subtype().

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 an request right away, make it synchronous.

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

Definition at line 331 of file rostermanager.cpp.

void removeRosterListener  ) 
 

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

Definition at line 337 of file rostermanager.cpp.

RosterListener::Roster * roster  ) 
 

This function returns the roster.

Returns:
Returns a map of JIDs with their current presence.

Definition at line 63 of file rostermanager.cpp.

void setDelimiter const std::string &  delimiter  ) 
 

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

Parameters:
delimiter The group delimiter.
Since:
0.7

Definition at line 417 of file rostermanager.cpp.

References Tag::addAttrib(), and PrivateXML::storeXML().

void subscribe const std::string &  jid,
const std::string &  name,
StringList groups,
const std::string &  msg
 

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

References RosterManager::add(), Tag::addAttrib(), JID::full(), ClientBase::jid(), and ClientBase::send().

void synchronize  ) 
 

Synchronizes locally modified RosterItems back to the server.

Definition at line 224 of file rostermanager.cpp.

References Tag::addAttrib(), Tag::addChild(), and ClientBase::getID().

void unsubscribe const std::string &  jid,
const std::string &  msg,
bool  remove
 

Use this function to unsubscribe from a JID in the roster.

Parameters:
jid The address to unsubscribe from.
msg A message to send along with the request.
remove Whether the contact should also be removed from the roster.

Definition at line 194 of file rostermanager.cpp.

References Tag::addAttrib(), Tag::addChild(), JID::bare(), ClientBase::getID(), ClientBase::jid(), and ClientBase::send().


The documentation for this class was generated from the following files:
Generated on Mon Jan 16 16:20:01 2006 for gloox by  doxygen 1.4.6