documentation and rosterReceived() SIGNAL implementation

1 files changed, 46 insertions, 5 deletions

diff --git a/source/QXmppRoster.h b/source/QXmppRoster.h
index ef1b40d4..1d585ec7 100644
--- a/source/QXmppRoster.h
+++ b/source/QXmppRoster.h
@@ -22,6 +22,30 @@
  */
 
 
+/// \class QXmppRoster
+/// \brief Class for handling the roster of the connected client.
+///
+/// \note It's object should not be created using it's constructor. Instead
+/// QXmppClient::getRoster() should be used to get the reference of instantiated
+/// object this class.
+///
+/// It stores all the Roster and Presence details of all the roster entries (that
+/// is all the bareJids) in the client's friend's list. It provides the
+/// functionality to get all the bareJids in the client's roster and Roster and
+/// Presence details of the same.
+///
+/// After the sucessfull xmpp connection that after the signal QXmppClient::connected()
+/// is emitted QXmpp requests for getting the roster. Once QXmpp receives the roster
+/// the signal QXmppRoster::rosterReceived() is emitted and after that user can
+/// use the functions of this class to get roster entries.
+///
+/// Function QXmppRoster::isRosterReceived() tells whether the roster has been
+/// received or not.
+///
+/// Signals presenceChanged() or rosterChanged() are emitted whenever presence
+/// or roster changes respectively.
+///
+
 #ifndef QXMPPROSTER_H
 #define QXMPPROSTER_H
 
@@ -43,13 +67,19 @@ public:
     class QXmppRosterEntry
     {
     public:
+        /// An enumeration for type of subscription with the bareJid in the roster.
         enum SubscriptionType
         {
-            None = 0,
-            Both,
-            From,
-            To,
-            Remove
+            None = 0,   ///< the user does not have a subscription to the
+                        ///< contact's presence information, and the contact does
+                        ///< not have a subscription to the user's presence information
+            Both,   ///< both the user and the contact have subscriptions to each
+                    ///< other's presence information
+            From,   ///< the contact has a subscription to the user's presence information,
+                    ///< but the user does not have a subscription to the contact's presence information
+            To,     ///< the user has a subscription to the contact's presence information,
+                    ///< but the contact does not have a subscription to the user's presence information
+            Remove  ///< to delete a roster item
         };
 
         QString getBareJid() const;
@@ -77,6 +107,7 @@ public:
     QXmppRoster(QXmppStream* stream);
     ~QXmppRoster();
     
+    bool isRosterReceived();
     QStringList getRosterBareJids() const;
     QXmppRoster::QXmppRosterEntry getRosterEntry(const QString& bareJid) const;
     QMap<QString, QXmppRoster::QXmppRosterEntry> getRosterEntries() const;
@@ -89,7 +120,14 @@ public:
                               const QString& resource) const;
 
 signals:
+    /// This signal is emitted when the Roster IQ is received after a successful
+    /// connection.
+    void rosterReceived();
+
+    /// This signal is emitted when the presence of a particular bareJid and resource changes.
     void presenceChanged(const QString& bareJid, const QString& resource);
+
+    /// This signal is emitted when the roster entry of a particular bareJid changes.
     void rosterChanged(const QString& bareJid);
 
 private:
@@ -99,10 +137,13 @@ private:
     QMap<QString, QXmppRoster::QXmppRosterEntry> m_entries;
     // map of resources of the jid and map of resouces and presences
     QMap<QString, QMap<QString, QXmppPresence> > m_presences;
+    // flag to store that QXmppRoster has been populated
+    bool m_isRosterReceived ;
 
 private slots:
     void presenceReceived(const QXmppPresence&);
     void rosterIqReceived(const QXmppRosterIq&);
+    void rosterRequestIqReceived(const QXmppRosterIq&);
 };
 
 #endif // QXMPPROSTER_H