QXmpp: QXmppClient Class Reference

QXmpp Version: 1.14.3

Loading...
Searching...
No Matches
QXmppClient Class Reference
Core classes

Main class for starting and managing connections to XMPP servers. More...

Inheritance diagram for QXmppClient:

## Public Types
enum | Error { NoError , SocketError , KeepAliveError , XmppStreamError }
enum | State { DisconnectedState , ConnectingState , ConnectedState }
| This enumeration describes a client state. More...
enum | StreamManagementState { NoStreamManagement , NewStream , ResumedStream }
| Describes the use of XEP-0198: Stream Management. More...
enum | InitialExtensions { NoExtensions , BasicExtensions }
using | IqResult = std::variant<QDomElement, QXmppError>
using | EmptyResult = std::variant<QXmpp::Success, QXmppError>

## Public Member Functions
| QXmppClient (InitialExtensions, QObject *parent=nullptr)
| QXmppClient (QObject *parent=nullptr)
bool | addExtension (QXmppClientExtension *extension)
| Registers a new extension with the client.
template<typename T, typename... Args>
T * | addNewExtension (Args... args)
bool | insertExtension (int index, QXmppClientExtension *extension)
| Registers a new extension with the client at the given index.
bool | removeExtension (QXmppClientExtension *extension)
QXmppE2eeExtension * | encryptionExtension () const
void | setEncryptionExtension (QXmppE2eeExtension *)
QList< QXmppClientExtension * > | extensions () const
| Returns a list containing all the client's extensions.
template<typename T>
T * | findExtension () const
| Returns the extension which can be cast into type T*, or 0 if there is no such extension.
template<typename T>
int | indexOfExtension () const
| Returns the index of an extension.
bool | isAuthenticated () const
| Returns true if the client has authenticated with the XMPP server.
bool | isConnected () const
| Returns true if the client is connected to the XMPP server.
bool | isActive () const
void | setActive (bool active)
StreamManagementState | streamManagementState () const
QXmppPresence | clientPresence () const
| Returns the client's current presence.
void | setClientPresence (const QXmppPresence &presence)
QXmppConfiguration & | configuration ()
| Returns a modifiable reference to the current configuration of QXmppClient.
QXmppLogger * | logger () const
| Returns the QXmppLogger associated with the current QXmppClient.
void | setLogger (QXmppLogger *logger)
| Sets the QXmppLogger associated with the current QXmppClient.
QAbstractSocket::SocketError | socketError ()
| Returns the socket error if error() is QXmppClient::SocketError.
QString | socketErrorString () const
| Returns the human-readable description of the last socket error if error() is QXmppClient::SocketError.
State | state () const
| Returns the client's current state.
QXmppStanza::Error::Condition | xmppStreamError ()
| Returns the XMPP stream error if QXmppClient::Error is QXmppClient::XmppStreamError.
QXmppTask< QXmpp::SendResult > | sendSensitive (QXmppStanza &&, const std::optional< QXmppSendStanzaParams > &={})
QXmppTask< QXmpp::SendResult > | send (QXmppStanza &&, const std::optional< QXmppSendStanzaParams > &={})
QXmppTask< QXmpp::SendResult > | reply (QXmppStanza &&stanza, const std::optional< QXmppE2eeMetadata > &e2eeMetadata, const std::optional< QXmppSendStanzaParams > &={})
QXmppTask< IqResult > | sendIq (QXmppIq &&, const std::optional< QXmppSendStanzaParams > &={})
QXmppTask< IqResult > | sendSensitiveIq (QXmppIq &&, const std::optional< QXmppSendStanzaParams > &={})
QXmppTask< EmptyResult > | sendGenericIq (QXmppIq &&, const std::optional< QXmppSendStanzaParams > &={})
Q_SIGNAL void | connected ()
Q_SIGNAL void | disconnected ()
| This signal is emitted when the XMPP connection disconnects.
Q_SIGNAL void | error (QXmppClient::Error)
Q_SIGNAL void | errorOccurred (const QXmppError &error)
Q_SIGNAL void | loggerChanged (QXmppLogger *logger)
| This signal is emitted when the logger changes.
Q_SIGNAL void | messageReceived (const QXmppMessage &message)
Q_SIGNAL void | presenceReceived (const QXmppPresence &presence)
Q_SIGNAL void | iqReceived (const QXmppIq &iq)
Q_SIGNAL void | sslErrors (const QList< QSslError > &errors)
Q_SIGNAL void | stateChanged (QXmppClient::State state)
| This signal is emitted when the client state changes.
Q_SIGNAL void | credentialsChanged ()
Q_SLOT void | connectToServer (const QXmppConfiguration &, const QXmppPresence &initialPresence={})
Q_SLOT void | connectToServer (const QString &jid, const QString &password)
Q_SLOT void | disconnectFromServer ()
QXmppRosterManager & | rosterManager ()
QXmppVCardManager & | vCardManager ()
QXmppVersionManager & | versionManager ()
Q_SLOT bool | sendPacket (const QXmppNonza &)
Q_SLOT void | sendMessage (const QString &bareJid, const QString &message)
Public Member Functions inherited from QXmppLoggable
| QXmppLoggable (QObject *parent=nullptr)
Q_SIGNAL void | setGauge (const QString &gauge, double value)
| Sets the given gauge to value.
Q_SIGNAL void | logMessage (QXmppLogger::MessageType type, const QString &msg)
| This signal is emitted to send logging messages.
Q_SIGNAL void | updateCounter (const QString &counter, qint64 amount=1)
| Updates the given counter by amount.

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

## Friends
class | QXmppClientExtension
class | QXmppCarbonManagerV2
class | QXmppRegistrationManager
class | TestClient

## Additional Inherited Members
Protected Member Functions inherited from QXmppLoggable
void | debug (const QString &message)
| Logs a debugging message.
void | info (const QString &message)
| Logs an informational message.
void | warning (const QString &message)
| Logs a warning message.
void | logReceived (const QString &message)
| Logs a received packet.
void | logSent (const QString &message)
| Logs a sent packet.

## Detailed Description

Main class for starting and managing connections to XMPP servers.

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 that behaviour using QXmppConfiguration::setAutoReconnectionEnabled().

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

List of managers enabled by default:

- QXmppRosterManager
- QXmppVCardManager
- QXmppVersionManager
- QXmppDiscoveryManager
- QXmppEntityTimeManager

## Connection details

If no explicit host and port are configured, the client will look up the SRV records of the domain of the configured JID. Since QXmpp 1.8 both TCP and direct TLS records are looked up and connection via direct TLS is preferred as it saves the extra round trip from STARTTLS. See also XEP-0368: SRV records for XMPP over TLS.

On connection errors the other SRV records are tested too (if multiple are available).

For servers without SRV records or if looking up the records did not succeed, domain and the default port of 5223 (TLS) and 5222 (TCP/STARTTLS) are tried.

## Usage of FAST token-based authentication

QXmpp uses XEP-0484: Fast Authentication Streamlining Tokens if enabled and supported by the server. FAST tokens can be requested after a first time authentication using a password or another strong authentication mechanism. The tokens can then be used to log in, without a password. The tokens are linked to a specific device ID (set via the SASL 2 user agent) and only this device can use the token. Tokens also expire and are rotated by the server.

The advantage of this mechanism is that a client does not necessarily need to store the password of an account and in the future clients that are logged in could be listed and logged out manually. FAST also allows for performance improvements as it only requires one round trip for authentication (and may be included in TLS 0-RTT data although that is not implemented in QXmpp) while other mechanisms like SCRAM need multiple round trips.

FAST itself is enabled by default (see QXmppConfiguration::useFastTokenAuthentication()), but you also need to set a SASL user agent with a stable device ID, so FAST can be used. After that you can login and use QXmppCredentials to serialize the token data and store it permanently. Note that the token may change over time, though.

## Member Typedef Documentation

## ◆ EmptyResult

using QXmppClient::EmptyResult = std::variant<QXmpp::Success, QXmppError>

Result of a generic request without a return value. Contains Success in case everything went well. If the returned IQ contained an error a QXmppStanza::Error is reported.

Since
  QXmpp 1.5

## ◆ IqResult

using QXmppClient::IqResult = std::variant<QDomElement, QXmppError>

Result of an IQ request, either contains the QDomElement of the IQ reponse (in case of an 'result' IQ type) or it contains an QXmppError with a QXmppStanza::Error (on type 'error') or a QXmpp::SendError.

Since
  QXmpp 1.5

## Member Enumeration Documentation

## ◆ Error

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.

## ◆ InitialExtensions

enum QXmppClient::InitialExtensions

Used to decide which extensions should be added by default.

Since
  QXmpp 1.6

Enumerator
NoExtensions | Creates a client without any extensions.
BasicExtensions | Creates a client with the default set of extensions.

## ◆ State

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.

## ◆ StreamManagementState

enum QXmppClient::StreamManagementState

Describes the use of XEP-0198: Stream Management.

Enumerator
NoStreamManagement | Stream Management is not used.
NewStream | Stream Management is used and the previous stream has not been resumed.
ResumedStream | Stream Management is used and the previous stream has been resumed.

## Constructor & Destructor Documentation

## ◆ QXmppClient() [1/2]

QXmppClient::QXmppClient | ( | InitialExtensions | initialExtensions,
|  | QObject * | parent = nullptr )

Creates a QXmppClient object.

Parameters

  initialExtensions | can be used to set the initial set of extensions.
  parent | is passed to the QObject's constructor. The default value is 0.

Since
  QXmpp 1.6

## ◆ QXmppClient() [2/2]

QXmppClient::QXmppClient | ( | QObject * | parent = nullptr | ) |

Creates a QXmppClient object.

Parameters

  parent | is passed to the QObject's constructor.

## Member Function Documentation

## ◆ addNewExtension()

template<typename T, typename... Args>

T * QXmppClient::addNewExtension | ( | Args... | args | ) |
| inline

Creates a new extension and adds it to the client.

Returns
  the newly created extension

Since
  QXmpp 1.5

## ◆ connected()

Q_SIGNAL void QXmppClient::connected | ( |  | ) |

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 `findExtension<QXmppRosterManager>()` to get the handle of QXmppRosterManager object.

## ◆ connectToServer() [1/2]

void QXmppClient::connectToServer | ( | const QString & | jid,
|  | const QString & | password )

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.

## ◆ connectToServer() [2/2]

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

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

## ◆ credentialsChanged()

Q_SIGNAL void QXmppClient::credentialsChanged | ( |  | ) |

Emitted when the credentials, e.g. tokens have changed.

This means that the QXmppCredentials in the QXmppConfiguration of this client has changed.

Since
  QXmpp 1.8

## ◆ disconnectFromServer()

void QXmppClient::disconnectFromServer | ( |  | ) |

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.

## ◆ encryptionExtension()

QXmppE2eeExtension * QXmppClient::encryptionExtension | ( |  | ) | const

Returns the currently used encryption extension.

Since
  QXmpp 1.5

## ◆ error()

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

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.

## ◆ errorOccurred()

Q_SIGNAL void QXmppClient::errorOccurred | ( | const QXmppError & | error | ) |

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

Parameters

  error | Detailed error object with a description. It may contain QAbstractSocket::SocketError QXmpp::TimeoutError QXmpp::StreamError QXmpp::AuthenticationError QXmpp::BindError

Since
  QXmpp 1.7

## ◆ findExtension()

template<typename T>

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

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

Usage example:

QXmppDiscoveryManager* ext = client->findExtension<QXmppDiscoveryManager>();
if(ext)
{
//extension found, do stuff...
}
QXmppDiscoveryManager
The QXmppDiscoveryManager class makes it possible to discover information about other entities as def...
Definition QXmppDiscoveryManager.h:23

## ◆ indexOfExtension()

template<typename T>

int QXmppClient::indexOfExtension | ( |  | ) | const
| inline

Returns the index of an extension.

Usage example:

int index = client->indexOfExtension<QXmppDiscoveryManager>();
if (index > 0) {
// extension found, do stuff...
} else {
// extension not found
}

Since
  QXmpp 1.2

## ◆ iqReceived()

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

This signal is emitted when IQs of type result or error are received by the client and no registered QXmppClientExtension could handle it.

This is useful when it is only important to check whether the response of an IQ was successful. However, the recommended way is still to use an additional QXmppClientExtension for this kind of tasks.

## ◆ isActive()

bool QXmppClient::isActive | ( |  | ) | const

Returns true if the current client state is "active", false if it is "inactive". See XEP-0352: Client State Indication for details.

Since
  QXmpp 1.0

## ◆ messageReceived()

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

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.

## ◆ presenceReceived()

Q_SIGNAL void QXmppClient::presenceReceived | ( | const QXmppPresence & | presence | ) |

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.

## ◆ removeExtension()

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

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

## ◆ reply()

QXmppTask< QXmpp::SendResult > QXmppClient::reply | ( | QXmppStanza && | stanza,
|  | const std::optional< QXmppE2eeMetadata > & | e2eeMetadata,
|  | const std::optional< QXmppSendStanzaParams > & | params = {} )

Sends the stanza with the same encryption as `e2eeMetadata`.

When there is no e2eeMetadata given this always sends the stanza without end-to-end encryption. Intended to be used for replies to IQs and messages.

Since
  QXmpp 1.5

## ◆ rosterManager()

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.

Deprecated
  This method is deprecated since QXmpp 1.1. Use `QXmppClient::findExtension<QXmppRosterManager>()` instead.

## ◆ send()

QXmppTask< QXmpp::SendResult > QXmppClient::send | ( | QXmppStanza && | stanza,
|  | const std::optional< QXmppSendStanzaParams > & | = {} )

Sends a packet always without end-to-end-encryption.

This does the same as send(), but does not do any end-to-end encryption on the stanza.

Returns
  A QXmppTask that makes it possible to track the state of the packet.

Since
  QXmpp 1.5

## ◆ sendGenericIq()

QXmppTask< QXmppClient::EmptyResult > QXmppClient::sendGenericIq | ( | QXmppIq && | iq,
|  | const std::optional< QXmppSendStanzaParams > & | = {} )

Sends an IQ and returns possible stanza errors.

If you want to parse a special IQ response in the result case, you can use sendIq() and parse the returned QDomElement.

Returns
  Returns QXmpp::Success (on response type 'result') or the contained QXmppStanza::Error (on response type 'error')

Since
  QXmpp 1.5

## ◆ sendIq()

QXmppTask< QXmppClient::IqResult > QXmppClient::sendIq | ( | QXmppIq && | iq,
|  | const std::optional< QXmppSendStanzaParams > & | = {} )

Sends an IQ packet and returns the response asynchronously.

This is useful for further processing and parsing of the returned QDomElement. If you don't expect a special response, you may want use sendGenericIq().

IQs of type 'error' are parsed automatically and returned as QXmppError with a contained QXmppStanza::Error.

This does not do any end-to-encryption on the IQ.

See also
  sendSensitiveIq()

Since
  QXmpp 1.5

## ◆ sendMessage()

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

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.

Note
  Usage of this method is discouraged because most modern clients use carbon messages (XEP-0280: Message Carbons) and MAM (XEP-0313: Message Archive Management) and so could possibly receive messages multiple times or not receive them at all. `QXmppClient::sendPacket()` should be used instead with a `QXmppMessage`.

Parameters

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

Deprecated

## ◆ sendPacket()

bool QXmppClient::sendPacket | ( | const QXmppNonza & | packet | ) |

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.

This function does not end-to-end encrypt the packets.

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);
QXmppMessage
The QXmppMessage class represents an XMPP message.
Definition QXmppMessage.h:64

Parameters

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

Deprecated

## ◆ sendSensitive()

QXmppTask< QXmpp::SendResult > QXmppClient::sendSensitive | ( | QXmppStanza && | stanza,
|  | const std::optional< QXmppSendStanzaParams > & | params = {} )

Sends a packet and reports the result via QXmppTask.

If stream management is enabled, the task continues to be active until the server acknowledges the packet. On success, QXmpp::SendSuccess with acknowledged == true is reported and the task finishes.

If connection errors occur, the packet is resent if possible. If reconnecting is not possible, an error is reported.

Returns
  A QXmppTask that makes it possible to track the state of the packet.

Since
  QXmpp 1.5

## ◆ sendSensitiveIq()

QXmppTask< QXmppClient::IqResult > QXmppClient::sendSensitiveIq | ( | QXmppIq && | iq,
|  | const std::optional< QXmppSendStanzaParams > & | params = {} )

Tries to encrypt and send an IQ packet and returns the response asynchronously.

This can be used for sensitive IQ requests performed from client to client. Most IQ requests like service discovery requests cannot be end-to-end encrypted or it only makes little sense to do so. This is why the default sendIq() does not do any additional end-to-end encryption.

IQs of type 'error' are parsed automatically and returned as QXmppError with a contained QXmppStanza::Error.

Since
  QXmpp 1.5

## ◆ setActive()

void QXmppClient::setActive | ( | bool | active | ) |

Sets the client state as described in XEP-0352: Client State Indication.

Since QXmpp 1.8, the state is restored across reconnects. QXmpp will re-send the state of 'inactive' on connection if that was set before. Stream resumptions are also handled.

Since
  QXmpp 1.0

## ◆ setClientPresence()

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

## ◆ setEncryptionExtension()

void QXmppClient::setEncryptionExtension | ( | QXmppE2eeExtension * | extension | ) |

Sets the extension to be used for end-to-end-encryption.

Since
  QXmpp 1.5

## ◆ sslErrors()

Q_SIGNAL void QXmppClient::sslErrors | ( | const QList< QSslError > & | errors | ) |

This signal is emitted to indicate that one or more SSL errors were encountered while establishing the identity of the server.

## ◆ streamManagementState()

QXmppClient::StreamManagementState QXmppClient::streamManagementState | ( |  | ) | const

Returns the current XEP-0198: Stream Management state of the connection.

Upon connection of the client this can be used to check whether the previous stream has been resumed.

Since
  QXmpp 1.4

## ◆ vCardManager()

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

Returns the reference to QXmppVCardManager, implementation of XEP-0054.

Deprecated
  This method is deprecated since QXmpp 1.1. Use `QXmppClient::findExtension<QXmppVCardManager>()` instead.

## ◆ versionManager()

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

Returns the reference to QXmppVersionManager, implementation of XEP-0092.

Deprecated
  This method is deprecated since QXmpp 1.1. Use `QXmppClient::findExtension<QXmppVersionManager>()` instead.

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

- QXmppClient.h
- client/compat/removed_api.cpp
- QXmppClient.cpp