RosterListener Class Referenceabstract

`#include <rosterlistener.h>`

## Public Member Functions

virtual | ~RosterListener ()
virtual void | handleItemAdded (const JID &jid)=0
virtual void | handleItemSubscribed (const JID &jid)=0
virtual void | handleItemRemoved (const JID &jid)=0
virtual void | handleItemUpdated (const JID &jid)=0
virtual void | handleItemUnsubscribed (const JID &jid)=0
virtual void | handleRoster (const Roster &roster)=0
virtual void | handleRosterPresence (const RosterItem &item, const std::string &resource, Presence::PresenceType presence, const std::string &msg)=0
virtual void | handleSelfPresence (const RosterItem &item, const std::string &resource, Presence::PresenceType presence, const std::string &msg)=0
virtual bool | handleSubscriptionRequest (const JID &jid, const std::string &msg)=0
virtual bool | handleUnsubscriptionRequest (const JID &jid, const std::string &msg)=0
virtual void | handleNonrosterPresence (const Presence &presence)=0
virtual void | handleRosterError (const IQ &iq)=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 RosterManager object receives notifications about all the changes in the server-side roster. Only one RosterListener per Roster at a time is possible.

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

Since
  0.3

Definition at line 43 of file rosterlistener.h.

## Constructor & Destructor Documentation

## ~RosterListener()

virtual ~RosterListener | ( |  | ) |

inline virtual

Virtual Destructor.

Definition at line 49 of file rosterlistener.h.

## Member Function Documentation

## handleItemAdded()

virtual void handleItemAdded | ( | const JID & | 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.

## handleItemRemoved()

virtual void handleItemRemoved | ( | const JID & | 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.

## handleItemSubscribed()

virtual void handleItemSubscribed | ( | const JID & | 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.

## handleItemUnsubscribed()

virtual void handleItemUnsubscribed | ( | const JID & | 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.

## handleItemUpdated()

virtual void handleItemUpdated | ( | const JID & | 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 the server.

Parameters

  jid | The modified item's full address.

## handleNonrosterPresence()

virtual void handleNonrosterPresence | ( | const Presence & | presence | ) |

pure virtual

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

Parameters

  presence | The full presence stanza.

## handleRoster()

virtual void handleRoster | ( | 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.

## handleRosterError()

virtual void handleRosterError | ( | const IQ & | iq | ) |

pure virtual

This function is called if the server returned an error.

Parameters

  iq | The error stanza.

## handleRosterPresence()

virtual void handleRosterPresence | ( | const RosterItem & | item,
|  | const std::string & | resource,
|  | Presence::PresenceType | presence,
|  | const std::string & | msg )

pure virtual

This function is called on every status change of an item in the roster. If the presence is of type Unavailable, then the resource has already been removed from the RosterItem.

Parameters

  item | The roster item.
  resource | The resource that changed presence.
  presence | The item's new presence.
  msg | The status change message.

Since
  0.9

## handleSelfPresence()

virtual void handleSelfPresence | ( | const RosterItem & | item,
|  | const std::string & | resource,
|  | Presence::PresenceType | presence,
|  | const std::string & | msg )

pure virtual

This function is called on every status change of a JID that matches the Client's own JID. If the presence is of type Unavailable, then the resource has already been removed from the RosterItem.

Parameters

  item | The self item.
  resource | The resource that changed presence.
  presence | The item's new presence.
  msg | The status change message.

Since
  0.9

## handleSubscriptionRequest()

virtual bool handleSubscriptionRequest | ( | const JID & | 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.

## handleUnsubscriptionRequest()

virtual bool handleUnsubscriptionRequest | ( | const JID & | 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.

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

- rosterlistener.h