documentation and rosterReceived() SIGNAL implementation

4 files changed, 220 insertions, 15 deletions

diff --git a/source/QXmppRoster.cpp b/source/QXmppRoster.cpp
index 13f5c8cd..98e9ec85 100644
--- a/source/QXmppRoster.cpp
+++ b/source/QXmppRoster.cpp
@@ -28,7 +28,8 @@
 #include "QXmppPresence.h"
 #include "QXmppStream.h"
 
-QXmppRoster::QXmppRoster(QXmppStream* stream) : m_stream(stream)
+QXmppRoster::QXmppRoster(QXmppStream* stream) : m_stream(stream),
+                                m_isRosterReceived(false)
 {
 }
 
@@ -82,68 +83,175 @@ void QXmppRoster::rosterIqReceived(const QXmppRosterIq& rosterIq)
     }
 }
 
+void QXmppRoster::rosterRequestIqReceived(const QXmppRosterIq& rosterIq)
+{
+    switch(rosterIq.getType())
+    {
+    case QXmppIq::Set:
+    case QXmppIq::Result:
+        {
+            QList<QXmppRosterIq::Item> items = rosterIq.getItems();
+            for(int i = 0; i < items.count(); ++i)
+            {
+                QString bareJid = items.at(i).getBareJid();
+                m_entries[bareJid].setBareJid(bareJid);
+                m_entries[bareJid].setName(items.at(i).getName());
+                m_entries[bareJid].setSubscriptionType(
+                    static_cast<QXmppRosterEntry::SubscriptionType>(
+                            items.at(i).getSubscriptionType()));
+                m_entries[bareJid].setSubscriptionStatus(
+                        items.at(i).getSubscriptionStatus());
+                m_entries[bareJid].setGroups(items.at(i).getGroups());
+            }
+            if(rosterIq.getType() == QXmppIq::Set) // send result iq
+            {
+                QXmppIq returnIq(QXmppIq::Result);
+                returnIq.setId(rosterIq.getId());
+                m_stream->sendPacket(returnIq);
+            }
+            m_isRosterReceived = true;
+            emit rosterReceived();
+            break;
+        }
+    default:
+        break;
+    }
+}
+
+/// Returns the bareJid of the roster entry.
+///
+/// \return bareJid as a QString
+///
+
 QString QXmppRoster::QXmppRosterEntry::getBareJid() const
 {
     return m_bareJid;
 }
 
+/// Returns the name of the roster entry.
+///
+/// \return name as a QString
+///
+
 QString QXmppRoster::QXmppRosterEntry::getName() const
 {
     return m_name;
 }
 
+/// Returns the subscription type of the roster entry.
+///
+/// \return QXmppRosterEntry::SubscriptionType
+///
+
 QXmppRoster::QXmppRosterEntry::SubscriptionType
         QXmppRoster::QXmppRosterEntry::getSubscriptionType() const
 {
     return m_type;
 }
 
+/// Sets the subscription status of the roster entry. It is the "ask"
+/// attribute in the Roster IQ stanza. Its value can be "subscribe" or "unsubscribe"
+/// or empty.
+///
+/// \return subscription status as a QString
+///
+///
+
 QString QXmppRoster::QXmppRosterEntry::getSubscriptionStatus() const
 {
     return m_subscriptionStatus;
 }
 
+/// Returns the groups of the roster entry.
+///
+/// \return QSet<QString> list of all the groups
+///
+
 QSet<QString> QXmppRoster::QXmppRosterEntry::getGroups() const
 {
     return m_groups;
 }
 
-void QXmppRoster::QXmppRosterEntry::setBareJid(const QString& str)
+/// Sets the bareJid of the roster entry.
+///
+/// \param bareJid as a QString
+///
+
+void QXmppRoster::QXmppRosterEntry::setBareJid(const QString& bareJid )
 {
-    m_bareJid = str;
+    m_bareJid = bareJid ;
 }
 
-void QXmppRoster::QXmppRosterEntry::setName(const QString& str)
+/// Sets the name of the roster entry.
+///
+/// \param name as a QString
+///
+
+void QXmppRoster::QXmppRosterEntry::setName(const QString& name)
 {
-    m_name = str;
+    m_name = name;
 }
 
+/// Sets the subscription type of the roster entry.
+///
+/// \param type as a QXmppRosterEntry::SubscriptionType
+///
+
 void QXmppRoster::QXmppRosterEntry::setSubscriptionType(
         QXmppRosterEntry::SubscriptionType type)
 {
     m_type = type;
 }
 
-void QXmppRoster::QXmppRosterEntry::setSubscriptionStatus(const QString& str)
+/// Sets the subscription status of the roster entry. It is the "ask"
+/// attribute in the Roster IQ stanza. Its value can be "subscribe" or "unsubscribe"
+/// or empty.
+///
+/// \param status as a QString
+///
+
+void QXmppRoster::QXmppRosterEntry::setSubscriptionStatus(const QString& status)
 {
-    m_subscriptionStatus = str;
+    m_subscriptionStatus = status;
 }
 
-void QXmppRoster::QXmppRosterEntry::addGroupEntry(const QString& str)
+/// Adds the group entry of the roster entry.
+///
+/// \param group name as a QString
+///
+
+void QXmppRoster::QXmppRosterEntry::addGroupEntry(const QString& group)
 {
-    m_groups << str;
+    m_groups << group;
 }
 
+/// Sets the groups of the roster entry.
+///
+/// \param groups list of all the groups as a QSet<QString>
+///
+
 void QXmppRoster::QXmppRosterEntry::setGroups(const QSet<QString>& groups)
 {
     m_groups = groups;
 }
 
+/// Function to get all the bareJids present in the roster.
+///
+/// \return QStringList list of all the bareJids
+///
+
 QStringList QXmppRoster::getRosterBareJids() const
 {
     return m_entries.keys();
 }
 
+/// Returns the roster entry of the given bareJid. If the bareJid is not in the
+/// database and empty QXmppRoster::QXmppRosterEntry will be returned.
+///
+/// \param bareJid as a QString
+/// \return QXmppRoster::QXmppRosterEntry
+///
+
 QXmppRoster::QXmppRosterEntry QXmppRoster::getRosterEntry(
         const QString& bareJid) const
 {
@@ -157,12 +265,26 @@ QXmppRoster::QXmppRosterEntry QXmppRoster::getRosterEntry(
     }
 }
 
+/// [OBSOLETE] Returns all the roster entries in the database.
+///
+/// \return Map of bareJid and its respective QXmppRoster::QXmppRosterEntry
+///
+/// \note This function is obsolete, use getRosterBareJids() and
+/// getRosterEntry() to get all the roster entries.
+///
+
 QMap<QString, QXmppRoster::QXmppRosterEntry>
         QXmppRoster::getRosterEntries() const
 {
     return m_entries;
 }
 
+/// Get all the associated resources with the given bareJid.
+///
+/// \param bareJid as a QString
+/// \return list of associated resources as a QStringList
+///
+
 QStringList QXmppRoster::getResources(const QString& bareJid) const
 {
     if(m_presences.contains(bareJid))
@@ -173,6 +295,14 @@ QStringList QXmppRoster::getResources(const QString& bareJid) const
         return QStringList();
 }
 
+/// Get all the presences of all the resources of the given bareJid. A bareJid
+/// can have multiple resources and each resource will have a presence
+/// associated with it.
+///
+/// \param bareJid as a QString
+/// \return Map of resource and its respective presence QMap<QString, QXmppPresence>
+///
+
 QMap<QString, QXmppPresence> QXmppRoster::getAllPresencesForBareJid(
         const QString& bareJid) const
 {
@@ -185,6 +315,13 @@ QMap<QString, QXmppPresence> QXmppRoster::getAllPresencesForBareJid(
     }
 }
 
+/// Get the presence of the given resource of the given bareJid.
+///
+/// \param bareJid as a QString
+/// \param resource as a QString
+/// \return QXmppPresence
+///
+
 QXmppPresence QXmppRoster::getPresence(const QString& bareJid,
                                        const QString& resource) const
 {
@@ -197,7 +334,25 @@ QXmppPresence QXmppRoster::getPresence(const QString& bareJid,
     }
 }
 
+/// [OBSOLETE] Returns all the presence entries in the database.
+///
+/// \return Map of bareJid and map of resource and its presence that is
+/// QMap<QString, QMap<QString, QXmppPresence> >
+///
+/// \note This function is obsolete, use getRosterBareJids(), getResources()
+/// and getPresence() or getAllPresencesForBareJid()
+/// to get all the presence entries.
+
 QMap<QString, QMap<QString, QXmppPresence> > QXmppRoster::getAllPresences() const
 {
     return m_presences;
 }
+
+/// Function to check whether the roster has been received or not.
+///
+/// \return true if roster received else false
+
+bool QXmppRoster::isRosterReceived()
+{
+    return m_isRosterReceived;
+}
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
diff --git a/source/QXmppStream.cpp b/source/QXmppStream.cpp
index 4405e3b4..0971b83d 100644
--- a/source/QXmppStream.cpp
+++ b/source/QXmppStream.cpp
@@ -90,6 +90,10 @@ QXmppStream::QXmppStream(QXmppClient* client)
         &m_roster, SLOT(rosterIqReceived(const QXmppRosterIq&)));
     Q_ASSERT(check);
 
+    check = QObject::connect(this, SIGNAL(rosterRequestIqReceived(const QXmppRosterIq&)),
+        &m_roster, SLOT(rosterRequestIqReceived(const QXmppRosterIq&)));
+    Q_ASSERT(check);
+
     check = QObject::connect(this, SIGNAL(vCardIqReceived(const QXmppVCard&)),
         &m_vCardManager, SLOT(vCardIqReceived(const QXmppVCard&)));
     Q_ASSERT(check);
@@ -918,7 +922,11 @@ void QXmppStream::processBindIq(const QXmppBind& bind)
 
 void QXmppStream::processRosterIq(const QXmppRosterIq& rosterIq)
 {
-    emit rosterIqReceived(rosterIq);
+    if(m_rosterReqId == rosterIq.getId())
+        emit rosterRequestIqReceived(rosterIq);
+    else
+        emit rosterIqReceived(rosterIq);
+
     switch(rosterIq.getType())
     {
     case QXmppIq::Set:
diff --git a/source/QXmppStream.h b/source/QXmppStream.h
index 05d18f80..86a6bf62 100644
--- a/source/QXmppStream.h
+++ b/source/QXmppStream.h
@@ -80,6 +80,7 @@ signals:
     void messageReceived(const QXmppMessage&);
     void iqReceived(const QXmppIq&);
     void rosterIqReceived(const QXmppRosterIq&);
+    void rosterRequestIqReceived(const QXmppRosterIq&);
     void vCardIqReceived(const QXmppVCard&);
 
 private slots: