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

#include <QXmppClient.h>

Inheritance diagram for QXmppClient:

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

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

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

Public Slots
void	connectToServer (const QXmppConfiguration &, const QXmppPresence &initialPresence=QXmppPresence())

void	connectToServer (const QString &jid, const QString &password)

void	disconnectFromServer ()

bool	sendPacket (const QXmppNonza &)

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

Signals
void	connected ()

void	disconnected ()
	This signal is emitted when the XMPP connection disconnects.

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	sslErrors (const QList< QSslError > &errors)

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=nullptr)

bool	addExtension (QXmppClientExtension *extension)

template<typename T , typename... Args>
T *	addNewExtension (Args... args)

bool	insertExtension (int index, QXmppClientExtension *extension)

bool	removeExtension (QXmppClientExtension *extension)

QXmppE2eeExtension *	encryptionExtension () const

void	setEncryptionExtension (QXmppE2eeExtension *)

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.

template<typename T >
int	indexOfExtension ()
	Returns the index of an extension.

bool	isAuthenticated () const
	Returns true if the client has authenticated with the XMPP server.

bool	isConnected () const

bool	isActive () const

void	setActive (bool active)

StreamManagementState	streamManagementState () const

QXmppPresence	clientPresence () const

void	setClientPresence (const QXmppPresence &presence)

QXmppConfiguration &	configuration ()

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 ()

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 > &={})

QXmppRosterManager &	rosterManager ()

QXmppVCardManager &	vCardManager ()

QXmppVersionManager &	versionManager ()

Public Member Functions inherited from QXmppLoggable
	QXmppLoggable (QObject *parent=nullptr)

Properties
QXmppLogger *	logger
	The QXmppLogger associated with the current QXmppClient.

State	state
	The client's current state.

Friends
class	QXmppClientExtension

class	QXmppInternalClientExtension

class	TestClient

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 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:

Member Typedef Documentation

◆ EmptyResult

QXmppClient::EmptyResult

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

QXmppClient::IqResult

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.

◆ 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()

QXmppClient::QXmppClient ( QObject * parent = nullptr )

Creates a QXmppClient object.

Parameters

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

Member Function Documentation

◆ addExtension()

bool QXmppClient::addExtension ( QXmppClientExtension * extension )

Registers a new extension with the client.

Parameters

extension

◆ addNewExtension()

template<typename T , typename... Args>

QXmppClient::addNewExtension ( Args... args )

inline

Creates a new extension and adds it to the client.

Returns: the newly created extension

Since: QXmpp 1.5

◆ clientPresence()

QXmppPresence QXmppClient::clientPresence ( ) const

Returns the client's current presence.

◆ configuration()

QXmppConfiguration & QXmppClient::configuration ( )

Returns a modifiable reference to the current configuration of QXmppClient.

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

◆ connected

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

◆ connectToServer [1/2]

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.

◆ connectToServer [2/2]

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

slot

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

◆ disconnectFromServer

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.

◆ encryptionExtension()

QXmppE2eeExtension * QXmppClient::encryptionExtension ( ) const

Returns the currently used encryption extension.

Since: QXmpp 1.5

◆ error

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.

◆ extensions()

QList< QXmppClientExtension * > QXmppClient::extensions ( )

Returns a list containing all the client's extensions.

◆ findExtension()

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:

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

◆ indexOfExtension()

template<typename T >

int QXmppClient::indexOfExtension ( )

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

◆ insertExtension()

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

Registers a new extension with the client at the given index.

Parameters

index
extension

◆ iqReceived

void QXmppClient::iqReceived ( const QXmppIq & iq )

signal

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.

On connect this is always reset to true.

Since: QXmpp 1.0

◆ isConnected()

bool QXmppClient::isConnected ( ) const

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

◆ messageReceived

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.

◆ presenceReceived

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.

◆ removeExtension()

bool QXmppClient::removeExtension ( QXmppClientExtension * extension )

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

Parameters

extension

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

Warning: THIS API IS NOT FINALIZED YET!

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')

Warning: THIS API IS NOT FINALIZED YET!

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()

Warning: THIS API IS NOT FINALIZED YET!

Since: QXmpp 1.5

◆ sendMessage

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.

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.

◆ sendPacket

bool QXmppClient::sendPacket ( const QXmppNonza & 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.

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:35

Parameters

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

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

Warning: THIS API IS NOT FINALIZED YET!

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.

Warning: THIS API IS NOT FINALIZED YET!

Since: QXmpp 1.5

◆ setActive()

void QXmppClient::setActive ( bool active )

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

On connect this is always reset to true.

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

◆ socketError()

QAbstractSocket::SocketError QXmppClient::socketError ( )

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

◆ sslErrors

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

signal

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. http://xmpp.org/extensions/xep-0054.html

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. http://xmpp.org/extensions/xep-0092.html

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
QXmppClient.cpp

Public Types

Public Slots

Signals

Public Member Functions

Properties

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ EmptyResult

◆ IqResult

Member Enumeration Documentation

◆ Error

◆ State

◆ StreamManagementState

Constructor & Destructor Documentation

◆ QXmppClient()

Member Function Documentation

◆ addExtension()

◆ addNewExtension()

◆ clientPresence()

◆ configuration()

◆ connected

◆ connectToServer [1/2]

◆ connectToServer [2/2]

◆ disconnectFromServer

◆ encryptionExtension()

◆ error

◆ extensions()

◆ findExtension()

◆ indexOfExtension()

◆ insertExtension()

◆ iqReceived

◆ isActive()

◆ isConnected()

◆ messageReceived

◆ presenceReceived

◆ removeExtension()

◆ reply()

◆ rosterManager()

◆ send()

◆ sendGenericIq()

◆ sendIq()

◆ sendMessage

◆ sendPacket

◆ sendSensitive()

◆ sendSensitiveIq()

◆ setActive()

◆ setClientPresence()

◆ setEncryptionExtension()

◆ socketError()

◆ sslErrors

◆ streamManagementState()

◆ vCardManager()

◆ versionManager()