QXmpp Version: 1.5.6
No Matches
Signals | Public Member Functions | Protected Member Functions | Properties | List of all members
QXmppRegistrationManager Class Reference

The QXmppRegistrationManager class manages in-band registration and account management tasks like changing the password as defined in XEP-0077: In-Band Registration. More...

#include <QXmppRegistrationManager.h>

Inheritance diagram for QXmppRegistrationManager:
Inheritance graph
Collaboration diagram for QXmppRegistrationManager:
Collaboration graph


void supportedByServerChanged ()
void passwordChanged (const QString &newPassword)
void passwordChangeFailed (QXmppStanza::Error error)
void registrationFormReceived (const QXmppRegisterIq &iq)
void accountDeleted ()
void accountDeletionFailed (QXmppStanza::Error error)
void registrationSucceeded ()
void registrationFailed (const QXmppStanza::Error &error)
- 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

 QXmppRegistrationManager ()
QStringList discoveryFeatures () const override
void changePassword (const QString &newPassword)
void deleteAccount ()
bool supportedByServer () const
void requestRegistrationForm (const QString &service={})
void setRegistrationFormToSend (const QXmppRegisterIq &iq)
void setRegistrationFormToSend (const QXmppDataForm &dataForm)
void sendCachedRegistrationForm ()
bool registerOnConnectEnabled () const
void setRegisterOnConnectEnabled (bool enabled)
- Public Member Functions inherited from QXmppClientExtension
 QXmppClientExtension ()
virtual QList< QXmppDiscoveryIq::IdentitydiscoveryIdentities () const
virtual bool handleStanza (const QDomElement &stanza)
 You need to implement this method to process incoming XMPP stanzas.
virtual bool handleStanza (const QDomElement &stanza, const std::optional< QXmppE2eeMetadata > &e2eeMetadata)
 You need to implement this method to process incoming XMPP stanzas.
- Public Member Functions inherited from QXmppLoggable
 QXmppLoggable (QObject *parent=nullptr)

Protected Member Functions

void setClient (QXmppClient *client) override
- Protected Member Functions inherited from QXmppClientExtension
QXmppClientclient ()
void injectIq (const QDomElement &element, const std::optional< QXmppE2eeMetadata > &e2eeMetadata)
bool injectMessage (QXmppMessage &&message)
- 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)


bool supportedByServer
 Whether support of XEP-0077: In-band Registration has been discovered on the server.

Detailed Description

The QXmppRegistrationManager class manages in-band registration and account management tasks like changing the password as defined in XEP-0077: In-Band Registration.

Activating the manager

To make use of this manager, you need to instantiate it and load it into the QXmppClient instance as follows:

auto *registrationManager = new QXmppRegistrationManager;
QXmppClient * client()
Definition QXmppClientExtension.cpp:78
bool addExtension(QXmppClientExtension *extension)
Definition QXmppClient.cpp:263
Definition QXmppRegistrationManager.cpp:46

Setting up service discovery correctly for this manager

This manager automatically recognizes whether the local server supports XEP-0077 (see supportedByServer()). You just need to request the service discovery information from the server on connect as below:

connect(client, &QXmppClient::connected, [=]() {
// The service discovery manager is added to the client by default.
auto *discoManager = client->findExtension<QXmppDiscoveryManager>();
QXmppConfiguration & configuration()
Definition QXmppClient.cpp:334
void connected()
T * findExtension()
Returns the extension which can be cast into type T*, or 0 if there is no such extension.
Definition QXmppClient.h:157
The QXmppDiscoveryManager class makes it possible to discover information about other entities as def...
Definition QXmppDiscoveryManager.h:26
QString requestInfo(const QString &jid, const QString &node=QString())
Definition QXmppDiscoveryManager.cpp:73

As soon as the result is retrieved, the supportedByServer() property should be correct and could be used to display the user whether account management tasks can be performed on this server.

However, this is not relevant if you only want to register a new account on a server.

Changing the account's password

To change the password of the current account changePassword() can be used. Upon that either passwordChanged() or passwordChangeFailed() is emitted.

If changing the password was successful, the new password is automatically set in the QXmppClient::configuration(), so reconnecting works properly.


auto *registrationManager = client->findExtension<QXmppRegistrationManager>();
connect(registrationManager, &QXmppRegistrationManager::passwordChanged, [=](const QString &newPassword) {
qDebug() << "Password changed to:" << newPassword;
connect(registrationManager, &QXmppRegistrationManager::passwordChangeFailed, [=](QXmppStanza::Error error) {
qDebug() << "Couldn't change the password:" << error.text();
registrationManager->changePassword(client->configuration().user(), "m1cr0$0ft");
QString user() const
Definition QXmppConfiguration.cpp:219
The QXmppRegistrationManager class manages in-band registration and account management tasks like cha...
Definition QXmppRegistrationManager.h:222
void passwordChangeFailed(QXmppStanza::Error error)
void passwordChanged(const QString &newPassword)
void changePassword(const QString &newPassword)
Definition QXmppRegistrationManager.cpp:70
The Error class represents a stanza error.
Definition QXmppStanza.h:94
QString text() const
Definition QXmppStanza.cpp:370

Unregistration with the server

If you want to delete your account on the server, you can do that using deleteAccount(). When the result is received either accountDeleted() or accountDeletionFailed() is emitted. In case it was successful the manager automatically disconnects from the client.

auto *registrationManager = client->findExtension<QXmppRegistrationManager>();
connect(registrationManager, &QXmppRegistrationManager::accountDeleted, [=]() {
qDebug() << "Account deleted successfull, the client is disconnecting now";
connect(registrationManager, &QXmppRegistrationManager::accountDeletionFailed, [=](QXmppStanza::Error error) {
qDebug() << "Couldn't delete account:" << error.text();
void deleteAccount()
Definition QXmppRegistrationManager.cpp:86
void accountDeletionFailed(QXmppStanza::Error error)

Registering with a server

Registering with a server consists of multiple steps:

  1. Requesting the registration form from the server
  2. Filling out the registration form
  3. Sending the completed form to the server
    • On failure (e.g. because of a username conflict), the process continues at step 1 again.
  4. Connecting with the newly created account

Requesting the registration form from the server

First of all, you need to enable the registration process in the registration manager, which of course needs to be activated in the client.

auto *registrationManager = client->findExtension<QXmppRegistrationManager>();
void setRegisterOnConnectEnabled(bool enabled)
Definition QXmppRegistrationManager.cpp:171

After that you can start to connect to the server you want to register with. No JID is set in the QXmppConfiguration for the client and instead only the server is set.

void connectToServer(const QXmppConfiguration &, const QXmppPresence &initialPresence=QXmppPresence())
Definition QXmppClient.cpp:349
The QXmppConfiguration class holds configuration options.
Definition QXmppConfiguration.h:29
void setDomain(const QString &)
Definition QXmppConfiguration.cpp:114

Alternatively, you can also provide a domain-only JID and no password to connectToServer():

client->connectToServer("example.org", QString());

Now as soon as (START)TLS was handled, the registration manager interrupts the normal connection process. The manager checks whether the server supports in-band registration and whether the server advertises this as a stream feature.

If the server does not support in-band registration, the manager will abort the connection at this point and emit the registrationFailed() signal with a fixed QXmppStanza::Error of type QXmppStanza::Error::Cancel and with a condition of QXmppStanza::Error::FeatureNotImplemented.

The manager will now request the registration form. This will either result in an error (reported by registrationFailed()) or, if everything went well, the registration form is reported by registrationFormReceived().

To handle everything correctly, you need to connect to both Q_SIGNALS:

connect(registrationManager, &QXmppRegistrationManager::registrationFormReceived, [=](const QXmppRegisterIq &iq) {
qDebug() << "Form received:" << iq.instructions().
// you now need to complete the form
connect(registrationManager, &QXmppRegistrationManager::registrationFailed, [=](const QXmppStanza::Error &error) {
qDebug() << "Requesting the registration form failed:" << error.text();
The QXmppRegisterIq class represents a registration IQ as defined by XEP-0077: In-Band Registration.
Definition QXmppRegisterIq.h:23
QString instructions() const
Returns the instructions for this registration IQ.
Definition QXmppRegisterIq.cpp:122
void registrationFormReceived(const QXmppRegisterIq &iq)
void registrationFailed(const QXmppStanza::Error &error)

Filling out the registration form

Now you need to fill out the registration form. If this requires user interaction, it is recommended that you disconnect from the server at this point now. This is required, because some servers will kick inactive, not authorized clients after a few seconds.

If the returned IQ contains a data form, that can be displayed to a user or can be filled out in another way.

If the server does not support data forms, you can check the standard fields of the QXmppRegisterIq. You need to search the fields for empty (non-null) strings. All fields that contain an empty string are required and can be filled out. You can just set values for those fields and send the form as described in the next step.

QXmpp currently has only implemented the most important default fields in the QXmppRegisterIq. The other fields are not very widespread, because data forms are usually used for such purposes.

Sending the completed form to the server

Option A: If filling out the form goes very quick, you can set the filled out form directly using setRegistrationFormToSend() and then directly trigger the form to be sent using sendCachedRegistrationForm().


Option B: If filling out the form takes longer, i.e. because user interaction is required, you should disconnect now. As soon as you have completed the form, you can set it using setRegistrationFormToSend(). After that you can reconnect to the server and the registration manager will automatically send the set form.

// user fills out form ...
// As before, you only need to provide a domain to connectToServer()
// the registration manager sends the form automatically
void disconnectFromServer()
Definition QXmppClient.cpp:620

The form is now sent to the server. As soon as the result is received, either registrationSucceeded() or registrationFailed() is emitted.

In case there was a conflict or another error, you should request a new form and restart the process. This is especially important, if the form can only be used once as with most CAPTCHA implementations.

Connecting with the newly created account

You need to disconnect now. The user can then enter their credentials and connect as usually.

It is also possible to extract username and password from the sent form, but that does not work always. There might also be forms that have no clear username or password fields.

QXmpp 1.2

Constructor & Destructor Documentation

◆ QXmppRegistrationManager()

QXmppRegistrationManager::QXmppRegistrationManager ( )

Default constructor.

Member Function Documentation

◆ accountDeleted

void QXmppRegistrationManager::accountDeleted ( )

Emitted, when the account was deleted successfully.

◆ accountDeletionFailed

void QXmppRegistrationManager::accountDeletionFailed ( QXmppStanza::Error  error)

Emitted, when the account could not be deleted.

◆ changePassword()

void QXmppRegistrationManager::changePassword ( const QString &  newPassword)

Changes the password of the user's account.

Be sure to only call this when any previous requests have finished.
newPasswordThe new password to be set. This must not be empty.

◆ deleteAccount()

void QXmppRegistrationManager::deleteAccount ( )

Cancels an existing registration on the server.

See also

◆ discoveryFeatures()

QStringList QXmppRegistrationManager::discoveryFeatures ( ) const

This adds the jabber:iq:register namespace to the features.

Reimplemented from QXmppClientExtension.

◆ passwordChanged

void QXmppRegistrationManager::passwordChanged ( const QString &  newPassword)

Emitted, when the password of the account was changed successfully.

The new password is automatically set in QXmppClient::configuration().

newPasswordThe new password that was set on the server.

◆ passwordChangeFailed

void QXmppRegistrationManager::passwordChangeFailed ( QXmppStanza::Error  error)

Emitted, when changing the password did not succeed.

errorError returned from the service.

◆ registerOnConnectEnabled()

bool QXmppRegistrationManager::registerOnConnectEnabled ( ) const

Returns whether to only request the registration form and not to connect with username/password.

◆ registrationFailed

void QXmppRegistrationManager::registrationFailed ( const QXmppStanza::Error error)

Emitted, when the registration failed.

errorThe returned error from the service. The reported errors might be different from server to server, but the common ones are the following:
  • type=Cancel and condition=Conflict: The username already exists.
  • type=Cancel and condition=NotAllowed: The CAPTCHA verification failed.
  • type=Modify and condition=NotAcceptable: Some required information was missing or the selected password was too weak.
  • type=Modify and condition=JidMalformed: No username was provided or the username has an illegal format.

◆ registrationFormReceived

void QXmppRegistrationManager::registrationFormReceived ( const QXmppRegisterIq iq)

Emitted, when a registration form has been received.

When registering an account on the server and user interaction is required now to complete the form, it is recommended to disconnect and sending the completed registration form on reconnect using QXmppRegistrationManager::setRegistrationFormToSend(). Some servers (i.e. ejabberd) kick their clients after a timeout when they are not active. This can be avoided this way.

iqThe received form. If it does not contain a valid data form (see QXmppRegisterIq::form()), the required fields should be marked by empty (but not null) strings in the QXmppRegisterIq (i.e. QXmppRegisterIq::password().isNull() => false).

◆ registrationSucceeded

void QXmppRegistrationManager::registrationSucceeded ( )

Emitted, when the registration with a service completed successfully.

To connect with the account you still need to set the correct credentials in QXmppClient::configuration() and reconnect.

◆ requestRegistrationForm()

void QXmppRegistrationManager::requestRegistrationForm ( const QString &  service = {})

Requests the registration form for registering.

serviceThe service which the registration form should be requested from. If left empty, this will default to the local server.

◆ sendCachedRegistrationForm()

void QXmppRegistrationManager::sendCachedRegistrationForm ( )

Sends a completed registration form that was previously set using setRegistrationFormToSend().

You usually only need to set the form and the manager will automatically send it when connected. More details can be found in the documentation of the QXmppRegistrationManager.

◆ setClient()

void QXmppRegistrationManager::setClient ( QXmppClient client)

Sets the client which loaded this extension.


Reimplemented from QXmppClientExtension.

◆ setRegisterOnConnectEnabled()

void QXmppRegistrationManager::setRegisterOnConnectEnabled ( bool  enabled)

Sets whether to only request the registration form and not to connect with username/password.

enabledtrue to register, false to connect normally.

◆ setRegistrationFormToSend() [1/2]

void QXmppRegistrationManager::setRegistrationFormToSend ( const QXmppDataForm dataForm)

Sets a registration form to be sent on the next connect with the server.

dataFormThe completed data form for registration.

◆ setRegistrationFormToSend() [2/2]

void QXmppRegistrationManager::setRegistrationFormToSend ( const QXmppRegisterIq iq)

Sets a registration form to be sent on the next connect with the server.

iqThe completed registration form.

◆ supportedByServer()

bool QXmppRegistrationManager::supportedByServer ( ) const

Returns whether the server supports registration.

By default this is set to false and only changes, if you request the service discovery info of the connected server using QXmppDiscoveryManager::requestInfo().

This is only relevant to actions that happen after authentication.

See also

◆ supportedByServerChanged

void QXmppRegistrationManager::supportedByServerChanged ( )

Emitted, when registrationSupported() changed.

This can happen after the service discovery info of the server was retrieved using QXmppDiscoveryManager::requestInfo() or on disconnect.

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