RosterListener Class Reference

A virtual interface which can be reimplemented to receive roster updates. More...

#include <rosterlistener.h>

List of all members.

Public Types

typedef std::map< const std::string,
RosterItem * > 
Roster

Public Member Functions

virtual ~RosterListener ()
virtual void itemAdded (const std::string &jid)=0
virtual void itemSubscribed (const std::string &jid)=0
virtual void itemRemoved (const std::string &jid)=0
virtual void itemUpdated (const std::string &jid)=0
virtual void itemUnsubscribed (const std::string &jid)=0
virtual void roster (const Roster &roster)=0
virtual void presenceUpdated (const RosterItem &item, int status, const std::string &msg)=0
virtual void itemAvailable (const RosterItem &item, const std::string &msg, const JID &from)=0
virtual void itemUnavailable (const RosterItem &item, const std::string &msg, const JID &from)=0
virtual bool subscriptionRequest (const std::string &jid, const std::string &msg)=0
virtual bool unsubscriptionRequest (const std::string &jid, const std::string &msg)=0
virtual void nonrosterPresenceReceived (const JID &jid)=0


Detailed Description

A virtual interface which can be reimplemented to receive roster updates.

A class implementing this interface and being registered as RosterListener with the Roster object receives notifications about all the changes in the server-side roster. Only one RosterListener per Roster at a time is possible.

Author:
Jakob Schroeter <js@camaya.net>
Since:
0.3

Definition at line 35 of file rosterlistener.h.


Member Typedef Documentation

typedef std::map<const std::string, RosterItem*> Roster

A map of JID/RosterItem pairs.

Definition at line 41 of file rosterlistener.h.


Constructor & Destructor Documentation

virtual ~RosterListener (  )  [inline, virtual]

Virtual Destructor.

Definition at line 46 of file rosterlistener.h.


Member Function Documentation

virtual void itemAdded ( const std::string &  jid  )  [pure virtual]

Reimplement this function if you want to be notified about new items on the server-side roster (items subject to a so-called Roster Push). This function will be called regardless who added the item, either this resource or another. However, it will not be called for JIDs for which presence is received without them being on the roster.

Parameters:
jid The new item's full address.

virtual void itemSubscribed ( const std::string &  jid  )  [pure virtual]

Reimplement this function if you want to be notified about items which authorised subscription.

Parameters:
jid The authorising item's full address.

Referenced by RosterManager::handleSubscription().

virtual void itemRemoved ( const std::string &  jid  )  [pure virtual]

Reimplement this function if you want to be notified about items that were removed from the server-side roster (items subject to a so-called Roster Push). This function will be called regardless who deleted the item, either this resource or another.

Parameters:
jid The removed item's full address.

virtual void itemUpdated ( const std::string &  jid  )  [pure virtual]

Reimplement this function if you want to be notified about items that were modified on the server-side roster (items subject to a so-called Roster Push). A roster push is initiated if a second resource of this JID modifies an item stored on the server-side contact list. This can include modifying the item's name, its groups, or the subscription status. These changes are pushed by the server to all connected resources. This is why this function will be called if you modify a roster item locally and synchronize it with teh server.

Parameters:
jid The modified item's full address.

virtual void itemUnsubscribed ( const std::string &  jid  )  [pure virtual]

Reimplement this function if you want to be notified about items which removed subscription authorization.

Parameters:
jid The item's full address.

Referenced by RosterManager::handleSubscription().

virtual void roster ( const Roster roster  )  [pure virtual]

Reimplement this function if you want to receive the whole server-side roster on the initial roster push. After successful authentication, RosterManager asks the server for the full server-side roster. Invocation of this method announces its arrival. Roster item status is set to 'unavailable' until incoming presence info updates it. A full roster push only happens once per connection.

Parameters:
roster The full roster.

Referenced by RosterManager::handleIq().

virtual void presenceUpdated ( const RosterItem item,
int  status,
const std::string &  msg 
) [pure virtual]

This function is called on every status change of an item in the roster.

Note:
This function is not called for status changes from or to Unavailable. In these cases, itemAvailable() and itemUnavailable() are called, respectively.
Parameters:
item The roster item.
status The item's new status.
msg The status change message.

Referenced by RosterManager::handlePresence().

virtual void itemAvailable ( const RosterItem item,
const std::string &  msg,
const JID from 
) [pure virtual]

This function is called whenever a roster item comes online (is available). However, it will not be called for status changes from Away (or any other status which is not Unavailable) to Available.

Parameters:
item A reference to the changed roster item.
msg The status change message.
from The full JID that became available.

Referenced by RosterManager::handlePresence().

virtual void itemUnavailable ( const RosterItem item,
const std::string &  msg,
const JID from 
) [pure virtual]

This function is called whenever a roster item goes offline (is unavailable).

Parameters:
item A reference to the changed roster item.
msg The status change message.
from The full JID that became unavailable.

Referenced by RosterManager::handlePresence().

virtual bool subscriptionRequest ( const std::string &  jid,
const std::string &  msg 
) [pure virtual]

This function is called when an entity wishes to subscribe to this entity's presence. If the handler is registered as a asynchronous handler for subscription requests, the return value of this function is ignored. In this case you should use RosterManager::ackSubscriptionRequest() to answer the request.

Parameters:
jid The requesting item's address.
msg A message sent along with the request.
Returns:
Return true to allow subscription and subscribe to the remote entity's presence, false to ignore the request.

Referenced by RosterManager::handleSubscription().

virtual bool unsubscriptionRequest ( const std::string &  jid,
const std::string &  msg 
) [pure virtual]

This function is called when an entity unsubscribes from this entity's presence. If the handler is registered as a asynchronous handler for subscription requests, the return value of this function is ignored. In this case you should use RosterManager::unsubscribe() if you want to unsubscribe yourself from the contct's presence and to remove the contact from the roster.

Parameters:
jid The item's address.
msg A message sent along with the request.
Returns:
Return true to unsubscribe from the remote entity, false to ignore.

Referenced by RosterManager::handleSubscription().

virtual void nonrosterPresenceReceived ( const JID jid  )  [pure virtual]

This function is called whenever presence from an entity is received which is not in the roster.

Parameters:
jid The entity's full JID.

Referenced by RosterManager::handlePresence().


The documentation for this class was generated from the following file:
Generated on Tue May 1 14:20:26 2007 for gloox by  doxygen 1.5.1