QXmppClient Class

Member Function Documentation

QXmppClient::QXmppClient(QObject *parent = nullptr)

Creates a QXmppClient object. parent is passed to the QObject's constructor.

[since QXmpp 1.6] QXmppClient::QXmppClient(QXmppClient::InitialExtensions initialExtensions, QObject *parent = nullptr)

Creates a QXmppClient object.

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

This function was introduced in QXmpp 1.6.

bool QXmppClient::addExtension(QXmppClientExtension *extension)

Registers a new extension with the client. Returns true on success.

[since QXmpp 1.5] template <typename T, typename... Args> T *QXmppClient::addNewExtension(Args... args)

Creates a new extension (forwarding args to its constructor) and adds it to the client.

Returns the newly created extension.

This function was introduced in QXmpp 1.5.

QXmppPresence QXmppClient::clientPresence() const

Returns the client's current presence.

See also setClientPresence().

QXmppConfiguration &QXmppClient::configuration()

Returns a modifiable reference to the current configuration of QXmppClient.

[slot] void QXmppClient::connectToServer(const QString &jid, const QString &password)

Overloaded function to simply connect to an XMPP server with a jid and password for the account.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        xmppClient, qOverload(&QXmppClient::connectToServer));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        xmppClient, [receiver = xmppClient](const QString &jid, const QString &password) { receiver->connectToServer(jid, password); });

[slot] 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.

config specifies the configuration object for connecting the XMPP server. This contains the host name, user, password etc. See QXmppConfiguration for details. initialPresence is the initial presence which will be set for this user after establishing the session. The default value is QXmppPresence::Available.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        xmppClient, qOverload(&QXmppClient::connectToServer));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        xmppClient, [receiver = xmppClient](const QXmppConfiguration &config, const QXmppPresence &initialPresence) { receiver->connectToServer(config, initialPresence); });

[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.

[signal, since QXmpp 1.8] 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.

This function was introduced in QXmpp 1.8.

[slot] void QXmppClient::disconnectFromServer()

Disconnects the client and the current presence of client changes to QXmppPresence::Unavailable and status text changes to "Logged out".

[signal] void QXmppClient::disconnected()

This signal is emitted when the XMPP connection disconnects.

[since QXmpp 1.5] QXmppE2eeExtension *QXmppClient::encryptionExtension() const

Returns the currently used encryption extension.

This function was introduced in QXmpp 1.5.

See also setEncryptionExtension().

[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.

[signal, since QXmpp 1.7] void QXmppClient::errorOccurred(const QXmppError &error)

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

error is a detailed error object with a description. It may contain

• QAbstractSocket::SocketError
• QXmpp::TimeoutError
• QXmpp::StreamError
• QXmpp::AuthenticationError
• QXmpp::BindError

This function was introduced in QXmpp 1.7.

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

Returns a list containing all the client's extensions.

template <typename T> T *QXmppClient::findExtension() const

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...
}

[since QXmpp 1.2] template <typename T> int QXmppClient::indexOfExtension() const

Returns the index of an extension

Usage example:

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

This function was introduced in QXmpp 1.2.

bool QXmppClient::insertExtension(int index, QXmppClientExtension *extension)

Registers a new extension with the client at the given index. Returns true on success.

[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.

iq is the received IQ stanza.

[since QXmpp 1.0] 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.

This function was introduced in QXmpp 1.0.

bool QXmppClient::isAuthenticated() const

Returns true if the client has authenticated with the XMPP server.

bool QXmppClient::isConnected() const

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

QXmppLogger *QXmppClient::logger() const

Returns the QXmppLogger associated with the current QXmppClient.

See also setLogger().

[signal] void QXmppClient::loggerChanged(QXmppLogger *logger)

This signal is emitted when the logger changes.

[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.

message is the received message stanza.

[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.

presence is the received presence stanza.

bool QXmppClient::removeExtension(QXmppClientExtension *extension)

Returns whether the extension was unregistered. Unregisters the given extension from the client. If the extension is found, it will be destroyed.

extension.

[since QXmpp 1.5] 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.

params and stanza.

This function was introduced in QXmpp 1.5.

[since QXmpp 1.5] 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.

This function was introduced in QXmpp 1.5.

[since QXmpp 1.5] QXmppTask<QXmppClient::EmptyResult> QXmppClient::sendGenericIq(QXmppIq &&iq, const std::optional<QXmppSendStanzaParams> & = {})

Sends an IQ 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 QXmpp::Success (on response type 'result') or the contained QXmppStanza::Error (on response type 'error').

This function was introduced in QXmpp 1.5.

[since QXmpp 1.5] 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.

iq.

This function was introduced in QXmpp 1.5.

See also sendSensitiveIq().

[since QXmpp 1.5] 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.

params and stanza.

This function was introduced in QXmpp 1.5.

[since QXmpp 1.5] 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.

params and iq.

This function was introduced in QXmpp 1.5.

[since QXmpp 1.0] 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.

active.

This function was introduced in QXmpp 1.0.

See also isActive().

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.

presence is a QXmppPresence object.

See also clientPresence().

[since QXmpp 1.5] void QXmppClient::setEncryptionExtension(QXmppE2eeExtension *extension)

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

extension.

This function was introduced in QXmpp 1.5.

See also encryptionExtension().

void QXmppClient::setLogger(QXmppLogger *logger)

Sets the QXmppLogger associated with the current QXmppClient.

logger.

See also logger().

QAbstractSocket::SocketError QXmppClient::socketError()

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

QString QXmppClient::socketErrorString() const

Returns the human-readable description of the last socket error if error() is QXmppClient::SocketError.

[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.

errors.

QXmppClient::State QXmppClient::state() const

Returns the client's current state.

[signal] void QXmppClient::stateChanged(QXmppClient::State state)

This signal is emitted when the client state changes.

[since QXmpp 1.4] 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.

This function was introduced in QXmpp 1.4.

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

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