QXmpp  Version:1.3.0
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
[legend]
Collaboration diagram for QXmppRegistrationManager:
Collaboration graph
[legend]

Signals

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 ()
 
 ~QXmppClientExtension () override
 
virtual QList< QXmppDiscoveryIq::IdentitydiscoveryIdentities () const
 
virtual bool handleStanza (const QDomElement &stanza)=0
 You need to implement this method to process incoming XMPP stanzas. More...
 
- 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 ()
 
- 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)
 

Properties

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;
client->addExtension(registrationManager);

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>();
discoManager->requestInfo(client->configuration().server());
});

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.

Example:

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");

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();
});
registrationManager->deleteAccount();

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>();
registrationManager->setRegisterOnConnectEnabled(true);

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.

config.setDomain("example.org");

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

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.

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

registrationManager->setRegistrationFormToSend(completedForm);
registrationManager->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 ...
registrationManager->setRegistrationFormToSend(completedForm);
// As before, you only need to provide a domain to connectToServer()
// the registration manager sends the form automatically

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.

Since
QXmpp 1.2

Constructor & Destructor Documentation

◆ QXmppRegistrationManager()

QXmppRegistrationManager::QXmppRegistrationManager ( )

Default constructor.

Member Function Documentation

◆ accountDeleted

void QXmppRegistrationManager::accountDeleted ( )
signal

Emitted, when the account was deleted successfully.

◆ accountDeletionFailed

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

Emitted, when the account could not be deleted.

◆ changePassword()

void QXmppRegistrationManager::changePassword ( const QString &  newPassword)

Changes the password of the user's account.

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

◆ deleteAccount()

void QXmppRegistrationManager::deleteAccount ( )

Cancels an existing registration on the server.

See also
accountDeleted()
accountDeletionFailed()

◆ discoveryFeatures()

QStringList QXmppRegistrationManager::discoveryFeatures ( ) const
overridevirtual

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

Reimplemented from QXmppClientExtension.

◆ passwordChanged

void QXmppRegistrationManager::passwordChanged ( const QString &  newPassword)
signal

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

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

Parameters
newPasswordThe new password that was set on the server.

◆ passwordChangeFailed

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

Emitted, when changing the password did not succeed.

Parameters
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)
signal

Emitted, when the registration failed.

Parameters
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)
signal

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.

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

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.

Parameters
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)
overrideprotectedvirtual

Sets the client which loaded this extension.

Parameters
client

Reimplemented from QXmppClientExtension.

◆ setRegisterOnConnectEnabled()

void QXmppRegistrationManager::setRegisterOnConnectEnabled ( bool  enabled)

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

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

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

Parameters
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
QXmppRegistrationManager::supportedByServerChanged()

◆ supportedByServerChanged

void QXmppRegistrationManager::supportedByServerChanged ( )
signal

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:
QXmppRegistrationManager::registrationFormReceived
void registrationFormReceived(const QXmppRegisterIq &iq)
QXmppRegistrationManager::registrationFailed
void registrationFailed(const QXmppStanza::Error &error)
QXmppDiscoveryManager::requestInfo
QString requestInfo(const QString &jid, const QString &node=QString())
Definition: QXmppDiscoveryManager.cpp:73
QXmppClientExtension::client
QXmppClient * client()
Definition: QXmppClientExtension.cpp:70
QXmppStanza::Error
The Error class represents a stanza error.
Definition: QXmppStanza.h:105
QXmppClient::connectToServer
void connectToServer(const QXmppConfiguration &, const QXmppPresence &initialPresence=QXmppPresence())
Definition: QXmppClient.cpp:245
QXmppRegistrationManager::accountDeletionFailed
void accountDeletionFailed(QXmppStanza::Error error)
QXmppRegistrationManager::deleteAccount
void deleteAccount()
Definition: QXmppRegistrationManager.cpp:105
QXmppConfiguration::setDomain
void setDomain(const QString &)
Definition: QXmppConfiguration.cpp:133
QXmppDiscoveryManager
The QXmppDiscoveryManager class makes it possible to discover information about other entities as def...
Definition: QXmppDiscoveryManager.h:38
QXmppClient::disconnectFromServer
void disconnectFromServer()
Definition: QXmppClient.cpp:298
QXmppClient::addExtension
bool addExtension(QXmppClientExtension *extension)
Definition: QXmppClient.cpp:181
QXmppRegistrationManager::passwordChangeFailed
void passwordChangeFailed(QXmppStanza::Error error)
QXmppClient::findExtension
T * findExtension()
Returns the extension which can be cast into type T*, or 0 if there is no such extension.
Definition: QXmppClient.h:144
QXmppRegistrationManager::QXmppRegistrationManager
QXmppRegistrationManager()
Definition: QXmppRegistrationManager.cpp:65
QXmppClient::connected
void connected()
QXmppRegistrationManager::passwordChanged
void passwordChanged(const QString &newPassword)
QXmppRegistrationManager::setRegisterOnConnectEnabled
void setRegisterOnConnectEnabled(bool enabled)
Definition: QXmppRegistrationManager.cpp:188
QXmppConfiguration
The QXmppConfiguration class holds configuration options.
Definition: QXmppConfiguration.h:47
QXmppConfiguration::user
QString user() const
Definition: QXmppConfiguration.cpp:237
QXmppRegistrationManager::accountDeleted
void accountDeleted()
QXmppClient::configuration
QXmppConfiguration & configuration()
Definition: QXmppClient.cpp:232
QXmppRegistrationManager
The QXmppRegistrationManager class manages in-band registration and account management tasks like cha...
Definition: QXmppRegistrationManager.h:242
QXmppStanza::Error::text
QString text() const
Definition: QXmppStanza.cpp:228
QXmppRegisterIq
The QXmppRegisterIq class represents a registration IQ as defined by XEP-0077: In-Band Registration.
Definition: QXmppRegisterIq.h:41
QXmppRegistrationManager::changePassword
void changePassword(const QString &newPassword)
Definition: QXmppRegistrationManager.cpp:89
QXmppRegisterIq::instructions
QString instructions() const
Returns the instructions for this registration IQ.
Definition: QXmppRegisterIq.cpp:136