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:
[legend]
Collaboration diagram for QXmppRegistrationManager:
[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::Identity > | discoveryIdentities () 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
QXmppClient * | client ()
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);
QXmppClientExtension::client
QXmppClient * client()
Definition: QXmppClientExtension.cpp:70
QXmppClient::addExtension
bool addExtension(QXmppClientExtension *extension)
Definition: QXmppClient.cpp:179
QXmppRegistrationManager::QXmppRegistrationManager
QXmppRegistrationManager()
Definition: QXmppRegistrationManager.cpp:65

### 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());
});
QXmppClient::configuration
QXmppConfiguration & configuration()
Definition: QXmppClient.cpp:230
QXmppClient::connected
void connected()
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:154
QXmppDiscoveryManager
The QXmppDiscoveryManager class makes it possible to discover information about other entities as def...
Definition: QXmppDiscoveryManager.h:39
QXmppDiscoveryManager::requestInfo
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.

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");
QXmppConfiguration::user
QString user() const
Definition: QXmppConfiguration.cpp:237
QXmppRegistrationManager
The QXmppRegistrationManager class manages in-band registration and account management tasks like cha...
Definition: QXmppRegistrationManager.h:243
QXmppRegistrationManager::passwordChangeFailed
void passwordChangeFailed(QXmppStanza::Error error)
QXmppRegistrationManager::passwordChanged
void passwordChanged(const QString &newPassword)
QXmppRegistrationManager::changePassword
void changePassword(const QString &newPassword)
Definition: QXmppRegistrationManager.cpp:89
QXmppStanza::Error
The Error class represents a stanza error.
Definition: QXmppStanza.h:106
QXmppStanza::Error::text
QString text() const
Definition: QXmppStanza.cpp:226

### 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();
QXmppRegistrationManager::accountDeleted
void accountDeleted()
QXmppRegistrationManager::deleteAccount
void deleteAccount()
Definition: QXmppRegistrationManager.cpp:105
QXmppRegistrationManager::accountDeletionFailed
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>();
registrationManager->setRegisterOnConnectEnabled(true);
QXmppRegistrationManager::setRegisterOnConnectEnabled
void setRegisterOnConnectEnabled(bool enabled)
Definition: QXmppRegistrationManager.cpp:188

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);
QXmppClient::connectToServer
void connectToServer(const QXmppConfiguration &, const QXmppPresence &initialPresence=QXmppPresence())
Definition: QXmppClient.cpp:245
QXmppConfiguration
The QXmppConfiguration class holds configuration options.
Definition: QXmppConfiguration.h:48
QXmppConfiguration::setDomain
void setDomain(const QString &)
Definition: QXmppConfiguration.cpp:133

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

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.

client->disconnectFromServer();
// user fills out form ...
registrationManager->setRegistrationFormToSend(completedForm);
// As before, you only need to provide a domain to connectToServer()
client->connectToServer(...);
// the registration manager sends the form automatically
QXmppClient::disconnectFromServer
void disconnectFromServer()
Definition: QXmppClient.cpp:302

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

  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

override virtual

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

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

  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

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

signal

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

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

  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

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

  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.

## setClient()

void QXmppRegistrationManager::setClient | ( | QXmppClient * | client | ) |

override protected virtual

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

  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

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.h
- QXmppRegistrationManager.cpp