QXmpp: QXmppRegistrationManager Class Reference

QXmpp Version: 1.14.2

Loading...
Searching...
No Matches
QXmppRegistrationManager Class Reference
Managers

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:

## Public Member Functions
| QXmppRegistrationManager ()
| Default constructor.
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)
Q_SIGNAL void | supportedByServerChanged ()
Q_SIGNAL void | passwordChanged (const QString &newPassword)
Q_SIGNAL void | passwordChangeFailed (QXmppStanza::Error error)
Q_SIGNAL void | registrationFormReceived (const QXmppRegisterIq &iq)
Q_SIGNAL void | accountDeleted ()
Q_SIGNAL void | accountDeletionFailed (QXmppStanza::Error error)
Q_SIGNAL void | registrationSucceeded ()
Q_SIGNAL void | registrationFailed (const QXmppStanza::Error &error)
Public Member Functions inherited from QXmppClientExtension
| QXmppClientExtension ()
virtual QList< QXmppDiscoIdentity > | discoveryIdentities () 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)
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.

## Protected Member Functions
void | onRegistered (QXmppClient *client) override
void | onUnregistered (QXmppClient *client) override
Protected Member Functions inherited from QXmppClientExtension
QXmppClient * | client () const
virtual void | setClient (QXmppClient *client)
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)
| 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.

## 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);
QXmppClientExtension::client
QXmppClient * client() const
Definition QXmppClientExtension.cpp:57
QXmppRegistrationManager::QXmppRegistrationManager
QXmppRegistrationManager()
Default constructor.
Definition QXmppRegistrationManager.cpp:51

### Setting up service discovery correctly for this manager

This manager automatically recognizes whether the local server supports XEP-0077. 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");
QXmppRegistrationManager::passwordChangeFailed
Q_SIGNAL void passwordChangeFailed(QXmppStanza::Error error)
QXmppRegistrationManager::passwordChanged
Q_SIGNAL void passwordChanged(const QString &newPassword)
QXmppStanza::Error
The Error class represents a stanza error.
Definition QXmppStanza.h:112
QXmppStanza::Error::text
QString text() const
Definition QXmppStanza.cpp:233

### 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. If the server takes too much time to confirm the account deletion, you may disconnect manually after a reasonable timeout.

QXmpp periodically sends pings to the server. If the server does not respond to it within QXmppConfiguration::keepAliveInterval(), QXmpp disconnects from the server. Make sure to handle that case if it happens during account deletion. E.g., you could try to connect to the server again with the same account and check whether QXmpp::AuthenticationError::NotAuthorized occurs. In that case, the account can be considered as deleted.

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

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

QXmppConfiguration config;
config.setDomain("example.org");
client->connectToServer(config);
QXmppConfiguration
The QXmppConfiguration class holds configuration options.
Definition QXmppConfiguration.h:37
QXmppConfiguration::setDomain
void setDomain(const QString &)
Definition QXmppConfiguration.cpp:156

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 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();
});
QXmppRegisterIq
The QXmppRegisterIq class represents a registration IQ as defined by XEP-0077: In-Band Registration.
Definition QXmppRegisterIq.h:23
QXmppRegisterIq::instructions
QString instructions() const
Returns the instructions for this registration IQ.
Definition QXmppRegisterIq.cpp:120
QXmppRegistrationManager::registrationFailed
Q_SIGNAL void registrationFailed(const QXmppStanza::Error &error)
QXmppRegistrationManager::registrationFormReceived
Q_SIGNAL void registrationFormReceived(const QXmppRegisterIq &iq)

#### Filling out the registration form

Now you need to fill out the registration form. The server can close the connection during that time. It is due to some servers kicking unauthorized clients after some time when the clients are inactive. That is often the case when user interaction is required before the completed form is submitted to the server. In order to support account creation for both servers closing the connection and servers keeping it open, you need to handle those cases appropriately.

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 the connection is still open once the form is filled out, set the form using setRegistrationFormToSend() and then trigger the form to be directly sent using sendCachedRegistrationForm().

registrationManager->setRegistrationFormToSend(completedForm);
registrationManager->sendCachedRegistrationForm();

Option B: If the connection is closed before the form is filled out, set the form using setRegistrationFormToSend() and connect to the server again. The registration manager will automatically send the set form once connected.

registrationManager->setRegistrationFormToSend(completedForm);
// As before, you only need to provide a domain to connectToServer()
client->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 usual.

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

## Member Function Documentation

## ◆ accountDeleted()

Q_SIGNAL void QXmppRegistrationManager::accountDeleted | ( |  | ) |

Emitted, when the account was deleted successfully.

## ◆ accountDeletionFailed()

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

Note
  Be sure to only call this when any previous requests have finished.

Parameters

  newPassword | The 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.

## ◆ onRegistered()

void QXmppRegistrationManager::onRegistered | ( | QXmppClient * | client | ) |
| overrideprotectedvirtual

Called after the extension has been added to a QXmppClient.

Parameters

  client |

Reimplemented from QXmppClientExtension.

## ◆ onUnregistered()

void QXmppRegistrationManager::onUnregistered | ( | QXmppClient * | client | ) |
| overrideprotectedvirtual

Called after the extension has been removed from a QXmppClient.

Parameters

  client |

Reimplemented from QXmppClientExtension.

## ◆ passwordChanged()

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

Parameters

  newPassword | The new password that was set on the server.

## ◆ passwordChangeFailed()

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

Emitted, when changing the password did not succeed.

Parameters

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

Q_SIGNAL void QXmppRegistrationManager::registrationFailed | ( | const QXmppStanza::Error & | error | ) |

Emitted, when the registration failed.

Parameters

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

Q_SIGNAL void QXmppRegistrationManager::registrationFormReceived | ( | const QXmppRegisterIq & | iq | ) |

Emitted, when a registration form has been received.

Parameters

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

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

Parameters

  service | The 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.

## ◆ setRegisterOnConnectEnabled()

void QXmppRegistrationManager::setRegisterOnConnectEnabled | ( | bool | enabled | ) |

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

Parameters

  enabled | true 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

  dataForm | The 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

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

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

- QXmppRegistrationManager.h
- QXmppRegistrationManager.cpp