From 93f275fa9abd0a95f4a915417bec9ac25bc1cd23 Mon Sep 17 00:00:00 2001 From: Manjeet Dahiya Date: Thu, 17 Sep 2009 22:04:01 +0000 Subject: documentation --- source/QXmppClient.cpp | 150 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 136 insertions(+), 14 deletions(-) (limited to 'source/QXmppClient.cpp') 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(); -- cgit v1.2.3