QXmpp: QXmppClient Class Reference

QXmpp Version:0.7.5

- Main Page
- Modules
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

All Classes Functions Variables Enumerations Enumerator Properties Groups
Public Types | Public Slots | Signals | Public Member Functions | Properties | List of all members
QXmppClient Class Reference
Core

The QXmppClient class is the main class for using QXmpp. More...

`#include <QXmppClient.h>`

Inheritance diagram for QXmppClient:

## Public Types
enum | Error { NoError, SocketError, KeepAliveError, XmppStreamError }
enum | State { DisconnectedState, ConnectingState, ConnectedState }
| This enumeration describes a client state. More...

## Public Slots
void | connectToServer (const QString &jid, const QString &password)
void | disconnectFromServer ()
bool | sendPacket (const QXmppStanza &)
void | sendMessage (const QString &bareJid, const QString &message)

## Signals
void | connected ()
void | disconnected ()
void | error (QXmppClient::Error)
void | loggerChanged (QXmppLogger *logger)
| This signal is emitted when the logger changes.
void | messageReceived (const QXmppMessage &message)
void | presenceReceived (const QXmppPresence &presence)
void | iqReceived (const QXmppIq &iq)
void | stateChanged (QXmppClient::State state)
| This signal is emitted when the client state changes.
Signals inherited from QXmppLoggable
void | setGauge (const QString &gauge, double value)
| Sets the given gauge to value.
void | logMessage (QXmppLogger::MessageType type, const QString &msg)
| This signal is emitted to send logging messages.
void | updateCounter (const QString &counter, qint64 amount=1)
| Updates the given counter by amount.

## Public Member Functions
| QXmppClient (QObject *parent=0)
| ~QXmppClient ()
bool | addExtension (QXmppClientExtension *extension)
bool | removeExtension (QXmppClientExtension *extension)
QList< QXmppClientExtension * > | extensions ()
template<typename T >
T * | findExtension ()
| Returns the extension which can be cast into type T*, or 0 if there is no such extension.
void | connectToServer (const QXmppConfiguration &, const QXmppPresence &initialPresence=QXmppPresence())
bool | isAuthenticated () const
| Returns true if the client has authenticated with the XMPP server.
bool | isConnected () const
QXmppPresence | clientPresence () const
void | setClientPresence (const QXmppPresence &presence)
QXmppConfiguration & | configuration ()
QXmppLogger * | logger () const
void | setLogger (QXmppLogger *logger)
| Sets the QXmppLogger associated with the current QXmppClient.
QAbstractSocket::SocketError | socketError ()
State | state () const
QXmppStanza::Error::Condition | xmppStreamError ()
QXmppRosterManager & | rosterManager ()
QXmppVCardManager & | vCardManager ()
QXmppVersionManager & | versionManager ()
Public Member Functions inherited from QXmppLoggable
| QXmppLoggable (QObject *parent=0)

## Properties
QXmppLogger | logger
| Returns the QXmppLogger associated with the current QXmppClient.
State | state
| Returns the client's current state.

## Additional Inherited Members
Protected Member Functions inherited from QXmppLoggable
void | debug (const QString &message)
void | info (const QString &message)
void | warning (const QString &message)
void | logReceived (const QString &message)
void | logSent (const QString &message)

## Detailed Description

The QXmppClient class is the main class for using QXmpp.

It provides the user all the required functionality to connect to the server and perform operations afterwards.

This class will provide the handle/reference to QXmppRosterManager (roster management), QXmppVCardManager (vCard manager), and QXmppVersionManager (software version information).

By default, the client will automatically try reconnecting to the server. You can change this a behaviour using QXmppConfiguration::setAutoReconnectionEnabled().

Not all the managers or extensions have been enabled by default. One can enable/disable the managers using the funtions addExtension() and removeExtension(). findExtension() can be used to find reference/pointer to particular instansiated and enabled manager.

List of managers enabled by default:

- QXmppRosterManager
- QXmppVCardManager
- QXmppVersionManager
- QXmppDiscoveryManager
- QXmppEntityTimeManager

## Member Enumeration Documentation

enum QXmppClient::Error

An enumeration for type of error. Error could come due a TCP socket or XML stream or due to various stanzas.

Enumerator:

  NoError | No error.
  SocketError | Error due to TCP socket.
  KeepAliveError | Error due to no response to a keep alive.
  XmppStreamError | Error due to XML stream.

enum QXmppClient::State

This enumeration describes a client state.

Enumerator:

  DisconnectedState | Disconnected from the server.
  ConnectingState | Trying to connect to the server.
  ConnectedState | Connected to the server.

## Constructor & Destructor Documentation

QXmppClient::QXmppClient | ( | QObject * | parent = `0` | ) |

Creates a QXmppClient object.

Parameters

  parent | is passed to the QObject's constructor. The default value is 0.

QXmppClient::~QXmppClient | ( |  | ) |

Destructor, destroys the QXmppClient object.

## Member Function Documentation

bool QXmppClient::addExtension | ( | QXmppClientExtension * | extension | ) |

Registers a new extension with the client.

Parameters

  extension |

QXmppPresence QXmppClient::clientPresence | ( |  | ) | const

Returns the client's current presence.

QXmppConfiguration & QXmppClient::configuration | ( |  | ) |

Returns a modifiable reference to the current configuration of QXmppClient.

Returns
  Reference to the QXmppClient's configuration for the connection.

void QXmppClient::connected | ( |  | ) |
| signal

This signal is emitted when the client connects successfully 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.

After the connected() signal is emitted QXmpp will send the roster request to the server. On receiving the roster, QXmpp will emit QXmppRosterManager::rosterReceived(). After this signal, QXmppRosterManager object gets populated and you can use rosterManager() to get the handle of QXmppRosterManager object.

void QXmppClient::connectToServer | ( | const QXmppConfiguration & | config,
|  | const QXmppPresence & | initialPresence = `QXmppPresence()`
| ) |  |

Attempts to connect to the XMPP server. Server details and other configurations are specified using the config parameter. Use signals connected(), error(QXmppClient::Error) and disconnected() to know the status of the connection.

Parameters

  config | Specifies the configuration object for connecting the XMPP server. This contains the host name, user, password etc. See QXmppConfiguration for details.
  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 & | jid,
|  | const QString & | password
| ) |  |
| slot

Overloaded function to simply connect to an XMPP server with a JID and password.

Parameters

  jid | JID for the account.
  password | Password for the account.

void QXmppClient::disconnected | ( |  | ) |
| signal

This signal is emitted when the XMPP connection disconnects.

void QXmppClient::disconnectFromServer | ( |  | ) |
| slot

Disconnects the client and the current presence of client changes to QXmppPresence::Unavailable and status 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 disconnectFromServer() function.

void QXmppClient::error | ( | QXmppClient::Error |  | ) |
| signal

This signal is emitted when the XMPP connection encounters any error. The QXmppClient::Error parameter specifies the type of error occurred. It could be due to TCP socket or the xml stream or the stanza. Depending upon the type of error occurred use the respective get function to know the error.

QList< QXmppClientExtension * > QXmppClient::extensions | ( |  | ) |

Returns a list containing all the client's extensions.

template<typename T >

T* QXmppClient::findExtension | ( |  | ) |
| inline

Returns the extension which can be cast into type T*, or 0 if there is no such extension.

       Usage example:
       @code

QXmppDiscoveryManager* ext = client->findExtension<QXmppDiscoveryManager>(); if(ext) { //extension found, do stuff... }

void QXmppClient::iqReceived | ( | const QXmppIq & | iq | ) |
| signal

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.

bool QXmppClient::isConnected | ( |  | ) | const

Returns true if the client is connected to the XMPP server.

void QXmppClient::messageReceived | ( | const QXmppMessage & | message | ) |
| signal

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 QXmppClient::presenceReceived | ( | const QXmppPresence & | presence | ) |
| signal

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.

bool QXmppClient::removeExtension | ( | QXmppClientExtension * | extension | ) |

Unregisters the given extension from the client. If the extension is found, it will be destroyed.

Parameters

  extension |

QXmppRosterManager & QXmppClient::rosterManager | ( |  | ) |

Returns the reference to QXmppRosterManager object of the client.

Returns
  Reference to the roster object of the connected client. Use this to get the list of friends in the roster and their presence information.

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

Utility function to send message to all the resources associated with the specified bareJid. If there are no resources available, that is the contact is offline or not present in the roster, it will still send a message to the bareJid.

Parameters

  bareJid | bareJid of the receiving entity
  message | Message string to be sent.

bool QXmppClient::sendPacket | ( | const QXmppStanza & | packet | ) |
| slot

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. QXmppStanza is a parent class of all the stanzas QXmppMessage, QXmppPresence, QXmppIq, QXmppBind, QXmppRosterIq, QXmppSession and QXmppVCard.

Returns
  Returns true if the packet was sent, false otherwise.

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

QXmppMessage message(from, to, message);
client.sendPacket(message);

Parameters

  packet | A valid XMPP stanza. It can be an iq, a message or a presence stanza.

void QXmppClient::setClientPresence | ( | const QXmppPresence & | presence | ) |

Changes the presence of the connected client.

The connection to the server will be updated accordingly:

- If the presence type is QXmppPresence::Unavailable, the connection to the server will be closed.

- Otherwise, the connection to the server will be established as needed.

Parameters

  presence | QXmppPresence object

QAbstractSocket::SocketError QXmppClient::socketError | ( |  | ) |

Returns the socket error if error() is QXmppClient::SocketError.

QXmppVCardManager & QXmppClient::vCardManager | ( |  | ) |

Returns the reference to QXmppVCardManager, implementation of XEP-0054. http://xmpp.org/extensions/xep-0054.html

QXmppVersionManager & QXmppClient::versionManager | ( |  | ) |

Returns the reference to QXmppVersionManager, implementation of XEP-0092. http://xmpp.org/extensions/xep-0092.html

QXmppStanza::Error::Condition QXmppClient::xmppStreamError | ( |  | ) |

Returns the XMPP stream error if QXmppClient::Error is QXmppClient::XmppStreamError.

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

- QXmppClient.h
- QXmppClient.cpp