documentation

2 files changed, 184 insertions, 19 deletions

diff --git a/source/QXmppClient.cpp b/source/QXmppClient.cpp
index 9ae4899f..5940860a 100644
--- a/source/QXmppClient.cpp
+++ b/source/QXmppClient.cpp
@@ -28,6 +28,10 @@
 #include "QXmppMessage.h"

 #include "QXmppReconnectionManager.h"

 

+/// Creates a QXmppClient object.

+/// \param parent is passed to the QObject's contructor.

+/// The default value is 0.

+

 QXmppClient::QXmppClient(QObject *parent)

     : QObject(parent), m_stream(0), m_clientPrecence(QXmppPresence::Available),

     m_reconnectionManager(0)

@@ -61,15 +65,62 @@ QXmppClient::QXmppClient(QObject *parent)
     Q_ASSERT(check);

 }

 

+/// Destroys the QXmppClient object.

+///

+

 QXmppClient::~QXmppClient()

 {

 }

 

+/// Returns a modifiable reference to the current configuration of QXmppClient.

+/// \return Reference to the QXmppClient's configuration for the connection.

+

 QXmppConfiguration& QXmppClient::getConfiguration()

 {

     return m_config;

 }

 

+/// Overloaded function. It returns a const reference to the current configuration

+/// of QXmppClient.

+/// \return Constant reference to the QXmppClient's configuration for the connection.

+

+const QXmppConfiguration& QXmppClient::getConfiguration() const

+{

+    return m_config;

+}

+

+/// Attempts to connect to the XMPP server. Server deatils and other configurations

+/// are specified using the config parameter. Use signals connected(), error(QXmppClient::Error)

+/// and disconnected() to know the status of the connection.

+/// \param config Specifies the configuration object for connecting the XMPP server.

+/// This contains the host name, user, passwd etc. See QXmppConfiguration for details.

+/// \param initialPresence The initial presence which will be set for this user

+/// after establishing the session. The default value is QXmppPresence::Available

+

+void QXmppClient::connectToServer(const QXmppConfiguration& config,

+                                  const QXmppPresence& initialPresence)

+{

+    m_config = config;

+

+    m_clientPrecence = initialPresence;

+

+    m_stream->connect();

+}

+

+/// Overloaded function.

+/// \param host host name of the XMPP server where connection has to be made

+/// (e.g. "jabber.org" and "talk.google.com"). It can also be an IP address in

+/// the form of a string (e.g. "192.168.1.25").

+/// \param user Username of the account at the specified XMPP server. It should

+/// be the name without the domain name. E.g. "qxmpp.test1" and not

+/// "qxmpp.test1@gmail.com"

+/// \param passwd Password for the specified username

+/// \param domain Domain name e.g. "gmail.com" and "jabber.org".

+/// \param port Port number at which the XMPP server is listening. The default

+/// value is 5222.

+/// \param initialPresence The initial presence which will be set for this user

+/// after establishing the session. The default value is QXmppPresence::Available

+

 void QXmppClient::connectToServer(const QString& host, const QString& user,

                                   const QString& passwd, const QString& domain,

                                   int port,

@@ -86,15 +137,20 @@ void QXmppClient::connectToServer(const QString& host, const QString& user,
     m_stream->connect();

 }

 

-void QXmppClient::connectToServer(const QXmppConfiguration& config,

-                                  const QXmppPresence& initialPresence)

-{

-    m_config = config;

-

-    m_clientPrecence = initialPresence;

-

-    m_stream->connect();

-}

+/// After successfully connecting to the server use this function to send

+/// stanzas to the server. This function can solely be used to send various kind

+/// of stanzas to the server. QXmppPacket is a parent class of all the stanzas

+/// QXmppMessage, QXmppPresence, QXmppIq, QXmppBind, QXmppRosterIq, QXmppSession

+/// and QXmppVCard.

+///

+/// Following code snippet illustrates how to send a message using this function:

+/// \code

+/// QXmppMessage message(from, to, message);

+/// client.sendPacket(message);

+/// \endcode

+///

+/// \param packet A valid XMPP stanza. It can an iq, a message or a presence stanza.

+///

 

 void QXmppClient::sendPacket(const QXmppPacket& packet)

 {

@@ -104,6 +160,14 @@ void QXmppClient::sendPacket(const QXmppPacket& packet)
     }

 }

 

+/// Disconnects the client and the current presence of client changes to

+/// QXmppPresence::Unavailable and statatus text changes to "Logged out".

+///

+/// \note Make sure that the clientPresence is changed to

+/// QXmppPresence::Available, if you are again calling connectToServer() after

+/// calling the disconnect() function.

+///

+

 void QXmppClient::disconnect()

 {

     m_clientPrecence.setType(QXmppPresence::Unavailable);

@@ -114,12 +178,23 @@ void QXmppClient::disconnect()
         m_stream->disconnect();

 }

 

+/// Returns the reference to QXmppRoster object of the client.

+/// \return Reference to the roster object of the connected client. Use this to

+/// get the list of friends in the roster and there presence information.

+///

+

 QXmppRoster& QXmppClient::getRoster()

 {

     if(m_stream)

         return m_stream->getRoster();

 }

 

+/// Utility function to send message to all the resources associated with the

+/// specified bareJid.

+///

+/// \param bareJid bareJid of the receiving entity

+/// \param message Message string to be sent.

+

 void QXmppClient::sendMessage(const QString& bareJid, const QString& message)

 {

     QStringList resources = getRoster().getResources(bareJid);

@@ -129,21 +204,37 @@ void QXmppClient::sendMessage(const QString& bareJid, const QString& message)
     }

 }

 

-// sets the new presence of the connected client

+/// Changes the presence of the connected client.

+///

+/// \param presence QXmppPresence object

+///

+

 void QXmppClient::setClientPresence(const QXmppPresence& presence)

 {

     m_clientPrecence = presence;

     sendPacket(m_clientPrecence);

 }

 

-// overloaded function, changes the status text

+/// Overloaded function.

+///

+/// It only changes the status text.

+///

+/// \param statusText New status message string

+///

+

 void QXmppClient::setClientPresence(const QString& statusText)

 {

     m_clientPrecence.getStatus().setStatusText(statusText);

     sendPacket(m_clientPrecence);

 }

 

-// overloaded function, changes the presence type

+/// Overloaded function.

+///

+/// It only changes the QXmppPresence::Type.

+///

+/// \param presenceType New QXmppPresence::Type

+///

+

 void QXmppClient::setClientPresence(QXmppPresence::Type presenceType)

 {

     if(presenceType == QXmppPresence::Unavailable)

@@ -157,24 +248,46 @@ void QXmppClient::setClientPresence(QXmppPresence::Type presenceType)
     }

 }

 

-// overloaded function, changes the status type

+/// Overloaded function.

+///

+/// It only changes the QXmppPresence::Status::Type.

+///

+/// \param statusType New QXmppPresence::Status::Type

+///

+

 void QXmppClient::setClientPresence(QXmppPresence::Status::Type statusType)

 {

     m_clientPrecence.getStatus().setType(statusType);

     sendPacket(m_clientPrecence);

 }

 

-// returnsn the referece to client presence object

+/// Function to get the client's current presence.

+///

+/// \return Constant reference to the client's presence object

+///

+

 const QXmppPresence& QXmppClient::getClientPresence() const

 {

     return m_clientPrecence;

 }

 

+/// Function to get reconnection manager. By default there exists a reconnection

+/// manager. See QXmppReconnectionManager for more details of the reconnection

+/// mechanism.

+///

+/// \return Pointer to QXmppReconnectionManager

+///

+

 QXmppReconnectionManager* QXmppClient::getReconnectionManager()

 {

     return m_reconnectionManager;

 }

 

+/// Sets the user defined reconnection manager.

+///

+/// \return true if all the signal-slot connections are done correctly.

+///

+

 bool QXmppClient::setReconnectionManager(QXmppReconnectionManager*

                                          reconnectionManager)

 {

@@ -194,11 +307,20 @@ bool QXmppClient::setReconnectionManager(QXmppReconnectionManager*
     return true;

 }

 

+/// Returns the socket error if QXmppClient::Error is QXmppClient::SocketError.

+///

+/// \return QAbstractSocket::SocketError

+///

+

 QAbstractSocket::SocketError QXmppClient::getSocketError()

 {

     return m_stream->getSocketError();

 }

 

+/// Returns the reference to QXmppVCardManager, implimentation of XEP-0054.

+/// http://xmpp.org/extensions/xep-0054.html

+///

+

 QXmppVCardManager& QXmppClient::getVCardManager()

 {

     return m_stream->getVCardManager();

diff --git a/source/QXmppClient.h b/source/QXmppClient.h
index 79e28d6e..2f3934bb 100644
--- a/source/QXmppClient.h
+++ b/source/QXmppClient.h
@@ -44,11 +44,13 @@ class QXmppClient : public QObject
     Q_OBJECT

 

 public:

+    /// An enumeration for type of error.

+    /// Error could come due a TCP socket or XML stream or due to various stanzas.

     enum Error

     {

-        SocketError,

-        XmppStreamError,

-        XmppStanzaError

+        SocketError,        ///< Error due to TCP socket

+        XmppStreamError,    ///< Error due to XML stream

+        XmppStanzaError     ///< Error due to stanza

     };

 

     QXmppClient(QObject *parent = 0);

@@ -66,17 +68,57 @@ public:
     void disconnect();

     QXmppRoster& getRoster();

     QXmppConfiguration& getConfiguration();

+    const QXmppConfiguration& getConfiguration() const;

     QXmppReconnectionManager* getReconnectionManager();

     bool setReconnectionManager(QXmppReconnectionManager*);

     const QXmppPresence& getClientPresence() const;

     QXmppVCardManager& getVCardManager();

 

 signals:

+

+    /// This signal is emitted when the client connects sucessfully to the XMPP

+    /// server i.e. when a successful XMPP connection is established.

+    /// XMPP Connection involves following sequential steps:

+    ///     - TCP socket connection

+    ///     - Client sends start stream

+    ///     - Server sends start stream

+    ///     - TLS negotiation (encryption)

+    ///     - Authentication

+    ///     - Resource binding

+    ///     - Session establishment

+    ///

+    /// After all these steps a successful XMPP connection is established and

+    /// connected() signal is emitted.

+    ///

     void connected();

+

+    /// This signal is emitted when the XMPP connection disconnects.

+    ///

     void disconnected();

+

+    /// This signal is emitted when the XMPP connection encounters any error.

+    /// The QXmppClient::Error parameter specifies the type of error occured.

+    /// It could be due to TCP socket or the xml stream or the stanza.

+    /// Depending upon the type of error occured use the respective get function to

+    /// know the error.

     void error(QXmppClient::Error);

+

+    /// Notifies that an XMPP message stanza is received. The QXmppMessage

+    /// parameter contains the details of the message sent to this client.

+    /// In other words whenever someone sends you a message this signal is

+    /// emitted.

     void messageReceived(const QXmppMessage&);

+

+    /// Notifies that an XMPP presence stanza is received. The QXmppPresence

+    /// parameter contains the details of the presence sent to this client.

+    /// This signal is emitted when someone login/logout or when someone's status

+    /// changes Busy, Idle, Invisible etc.

     void presenceReceived(const QXmppPresence&);

+

+    /// Notifies that an XMPP iq stanza is received. The QXmppIq

+    /// parameter contains the details of the iq sent to this client.

+    /// IQ stanzas provide a structured request-response mechanism. Roster

+    /// management, setting-getting vCards etc is done using iq stanzas.

     void iqReceived(const QXmppIq&);

 

 public:

@@ -93,8 +135,9 @@ public slots:
     void setClientPresence(QXmppPresence::Status::Type statusType);

 

 private:

-    QXmppStream* m_stream;

-    QXmppConfiguration m_config;

+    QXmppStream* m_stream;  ///< Pointer to QXmppStream object a wrapper over

+                            ///< TCP socket and XMPP protocol

+    QXmppConfiguration m_config;    ///<

     QXmppPresence m_clientPrecence;

     QXmppReconnectionManager* m_reconnectionManager;

 };