QXmppOmemoManager Class

 QXmppPubSubManager *pubSubManager = new QXmppPubSubManager;
 client->addExtension(pubSubManager);

 QXmppOmemoStorage *omemoStorage = new QXmppOmemoMemoryStorage;
 QXmppTrustStorage *trustStorage = new QXmppTrustMemoryStorage;

 client->addNewExtension<QXmppAtmManager>(trustStorage);

 auto *manager = client->addNewExtension<QXmppOmemoManager>(omemoStorage);
 client->setEncryptionExtension(manager);

 manager->setSecurityPolicy(QXmpp::Toakafa);

 client->addNewExtension<QXmppCarbonManagerV2>();

 manager->load();
 });

 connect(client, &QXmppClient::connected, this, [=]() {
 auto future = manager->start();
 });

 QXmpp::TrustLevel::AutomaticallyTrusted | QXmpp::TrustLevel::ManuallyTrusted
 | QXmpp::TrustLevel::Authenticated

 QXmppSendStanzaParams params;
 params.setAcceptedTrustLevels(QXmpp::TrustLevel::Authenticated)
 client->send(stanza, params);

 QXmppSendStanzaParams params;
 params.setEncryptionJids({ "alice@example.org", "bob@example.com" })
 client->send(stanza, params);

Member Function Documentation

[explicit] QXmppOmemoManager::QXmppOmemoManager(QXmppOmemoStorage *omemoStorage)

Constructs an OMEMO manager using omemoStorage to store all OMEMO data.

QXmpp::TrustLevels QXmppOmemoManager::acceptedSessionBuildingTrustLevels()

Returns the trust levels keys must have in order to build sessions for their devices.

See also setAcceptedSessionBuildingTrustLevels().

[signal] void QXmppOmemoManager::allDevicesRemoved()

Emitted when all devices are removed.

QXmppTask<void> QXmppOmemoManager::buildMissingSessions(QList<QString> jids)

Builds sessions manually with devices for whom no sessions are available.

Usually, sessions are built during sending a first message to a device or after a first message is received from a device. This can be called in order to speed up the sending of a message. If this method is called before sending the first message, all sessions can be built and when the first message is being sent, the message only needs to be encrypted. Especially for chats with multiple devices, that can decrease the noticeable time a user has to wait for sending a message. Additionally, the keys are automatically retrieved from the server which is helpful in order to get them when calling QXmppOmemoManager::devices().

The user must be logged in while calling this. jids contains the JIDs of the device owners for whom the sessions are built.

QXmppTask<bool> QXmppOmemoManager::changeDeviceLabel(const QString &deviceLabel = {})

Changes the label of the own (this client instance's current user's) device to deviceLabel.

The label is a human-readable string used to identify the device by users.

Returns whether the action was successful.

[signal] void QXmppOmemoManager::deviceAdded(const QString &jid, uint32_t deviceId)

Emitted when a device is added. jid is the device owner's bare JID and deviceId is the ID of the device.

[signal] void QXmppOmemoManager::deviceChanged(const QString &jid, uint32_t deviceId)

Emitted when a device changed. jid is the device owner's bare JID and deviceId is the ID of the device.

[signal] void QXmppOmemoManager::deviceRemoved(const QString &jid, uint32_t deviceId)

Emitted when a device is removed. jid is the device owner's bare JID and deviceId is the ID of the device.

QXmppTask<QVector<QXmppOmemoDevice>> QXmppOmemoManager::devices()

Returns all locally stored devices except the own device.

Only devices that have been received after subscribing the corresponding device lists on the server are stored locally. Thus, only those are returned. Call QXmppOmemoManager::subscribeToDeviceLists() for contacts without presence subscription before.

You must build sessions before you can get devices with corresponding keys.

QXmppTask<QVector<QXmppOmemoDevice>> QXmppOmemoManager::devices(QList<QString> jids)

Returns the locally stored devices for the JIDs in jids, except the own device.

Only devices that have been received after subscribing the corresponding device lists on the server are stored locally. Thus, only those are returned. Call QXmppOmemoManager::subscribeToDeviceLists() for contacts without presence subscription before.

You must build sessions before you can get devices with corresponding keys.

[signal] void QXmppOmemoManager::devicesRemoved(const QString &jid)

Emitted when all devices of the owner with bare JID jid are removed.

bool QXmppOmemoManager::isNewDeviceAutoSessionBuildingEnabled()

Returns whether sessions are built when new devices are received from the server.

See also QXmppOmemoManager::setNewDeviceAutoSessionBuildingEnabled.

QXmppTask<QHash<QXmpp::TrustLevel, QMultiHash<QString, QByteArray>>> QXmppOmemoManager::keys(QXmpp::TrustLevels trustLevels = {})

Returns the JIDs of all key owners mapped to the IDs of their keys with the specified trustLevels except for the own key.

If no trust levels are passed, all keys are returned.

This should be called in order to get all stored keys which can be more than the stored devices because of trust decisions made without a published or received device.

QXmppTask<QHash<QString, QHash<QByteArray, QXmpp::TrustLevel>>> QXmppOmemoManager::keys(const QList<QString> &jids, QXmpp::TrustLevels trustLevels = {})

Returns the IDs of keys mapped to their trust levels for the key owners with the bare JIDs in jids and matching the specified trustLevels, except for the own key.

If no trust levels are passed, all keys for the JIDs are returned.

This should be called in order to get the stored keys which can be more than the stored devices because of trust decisions made without a published or received device.

QXmppTask<bool> QXmppOmemoManager::load()

Loads all locally stored OMEMO data.

This should be called after starting the client and before the login. It must only be called after setUp() has been called once for the user during one of the past login sessions. It does not need to be called if setUp() has been called during the current login session.

Returns whether everything is loaded successfully.

See also QXmppOmemoManager::setUp().

int QXmppOmemoManager::maximumDevicesPerJid() const

Returns the maximum count of devices stored per JID.

If more devices than that maximum are received for one JID from a server, they will not be stored locally and thus not used for encryption.

See also setMaximumDevicesPerJid().

int QXmppOmemoManager::maximumDevicesPerStanza() const

Returns the maximum count of devices for whom a stanza is encrypted.

If more devices than that maximum are stored for all addressed recipients of a stanza, the stanza will only be encrypted for first devices until the maximum is reached.

See also setMaximumDevicesPerStanza().

QXmppOmemoOwnDevice QXmppOmemoManager::ownDevice()

Returns the device of this client instance's current user.

QXmppTask<QByteArray> QXmppOmemoManager::ownKey()

Returns the key of this client instance.

QXmppTask<QXmppOmemoManager::Result> QXmppOmemoManager::removeContactDevices(QString jid)

Removes all devices of the contact with JID jid and the subscription to the contact's device list.

This should be called after removing a contact. The JID of the current user must not be passed. Use QXmppOmemoManager::resetAll() in order to remove all devices of the user.

Returns the result of the contact device removals.

QXmppTask<QVector<QXmppOmemoManager::DevicesResult>> QXmppOmemoManager::requestDeviceLists(QList<QString> jids)

Requests device lists from contacts with the JIDs in jids and stores them locally.

The user must be logged in while calling this. The JID of the current user must not be passed.

Returns the results of the requests for each JID.

QXmppTask<bool> QXmppOmemoManager::resetAll()

Resets all OMEMO data for all own devices and the trust data used by OMEMO.

ATTENTION: This should only be called if there is a certain reason for it since it deletes the data for this device and for other own devices from the server.

Call resetOwnDevice() if you only want to delete the OMEMO data for this device.

The user must be logged in while calling this.

Call setUp() once this method is finished if you want to set up everything again. Existing sessions are reset, which might lead to undecryptable incoming stanzas until everything is set up again.

Returns whether the action was successful.

QXmppTask<bool> QXmppOmemoManager::resetOwnDevice()

Resets all OMEMO data for this device and the trust data used by OMEMO.

ATTENTION: This should only be called when an account is removed locally or if there are unrecoverable problems with the OMEMO setup of this device.

The data on the server for other own devices is not removed. Call resetAll() for that purpose.

The user must be logged in while calling this.

Call setUp() once this method is finished if you want to set up everything again for this device. Existing sessions are reset, which might lead to undecryptable incoming stanzas until everything is set up again.

Returns whether the action was successful.

[since QXmpp 1.9] QXmppTask<void> QXmppOmemoManager::resetOwnDeviceLocally()

Resets all local OMEMO data for this device and the trust data used by OMEMO.

ATTENTION: This should only be called after an account is removed from the server since the data on the server is not reset.

Call setUp() once this method is finished and you are logged in to a new account if you want to set up everything for it.

This function was introduced in QXmpp 1.9.

QXmppTask<QXmpp::TrustSecurityPolicy> QXmppOmemoManager::securityPolicy()

Returns the security policy used by this E2EE extension.

See also setSecurityPolicy().

void QXmppOmemoManager::setAcceptedSessionBuildingTrustLevels(QXmpp::TrustLevels trustLevels)

Sets the trustLevels keys must have in order to build sessions for their devices.

See also acceptedSessionBuildingTrustLevels().

void QXmppOmemoManager::setMaximumDevicesPerJid(int maximum)

Sets the maximum count of devices stored per JID.

If more devices than that maximum are received for one JID from a server, they will not be stored locally and thus not used for encryption.

See also maximumDevicesPerJid().

void QXmppOmemoManager::setMaximumDevicesPerStanza(int maximum)

Sets the maximum count of devices for whom a stanza is encrypted.

If more devices than that maximum are stored for all addressed recipients of a stanza, the stanza will only be encrypted for first devices until the maximum is reached.

See also maximumDevicesPerStanza().

void QXmppOmemoManager::setNewDeviceAutoSessionBuildingEnabled(bool isNewDeviceAutoSessionBuildingEnabled)

Sets whether sessions are built when new devices are received from the server, controlled by isNewDeviceAutoSessionBuildingEnabled.

This can be used to not call QXmppOmemoManager::buildMissingSessions manually. But it should not be used before the initial setup and storing lots of devices locally. Otherwise, it could lead to a massive computation and network load when there are many devices for whom sessions are built.

See also isNewDeviceAutoSessionBuildingEnabled() and QXmppOmemoManager::buildMissingSessions.

QXmppTask<void> QXmppOmemoManager::setSecurityPolicy(QXmpp::TrustSecurityPolicy securityPolicy)

Sets the security policy used by this E2EE extension to securityPolicy.

See also securityPolicy().

QXmppTask<void> QXmppOmemoManager::setTrustLevel(const QMultiHash<QString, QByteArray> &keyIds, QXmpp::TrustLevel trustLevel)

Sets the trustLevel of keys identified by keyIds, which maps key owners' bare JIDs to the IDs of their keys.

If a key is not stored, it is added to the storage.

See also trustLevel().

QXmppTask<bool> QXmppOmemoManager::setUp(QString deviceLabel = {})

Sets up all OMEMO data locally and on the server.

The user must be logged in while calling this. deviceLabel is a human-readable string used to identify the own device.

Returns whether everything is set up successfully.

QXmppTask<QVector<QXmppOmemoManager::DevicesResult>> QXmppOmemoManager::subscribeToDeviceLists(QList<QString> jids)

Subscribes the current user's resource to device lists manually for the contacts with the JIDs in jids.

This should be called after each login and only for contacts without presence subscription because their device lists are not automatically subscribed. The user must be logged in while calling this.

Call QXmppOmemoManager::unsubscribeFromDeviceLists() before logout.

Returns the results of the subscription for each JID.

QXmppTask<QXmpp::TrustLevel> QXmppOmemoManager::trustLevel(const QString &keyOwnerJid, const QByteArray &keyId)

Returns the trust level of the key identified by keyOwnerJid (the key owner's bare JID) and keyId (the ID of the key).

If the key is not stored, the trust in that key is undecided.

See also setTrustLevel().

[signal] void QXmppOmemoManager::trustLevelsChanged(const QMultiHash<QString, QByteArray> &modifiedKeys)

Emitted when the trust levels of keys changed. modifiedKeys maps key owners' bare JIDs to their modified keys.

QXmppTask<QVector<QXmppOmemoManager::DevicesResult>> QXmppOmemoManager::unsubscribeFromDeviceLists()

Unsubscribes the current user's resource from all device lists that were manually subscribed by QXmppOmemoManager::subscribeToDeviceList().

This should be called before each logout. The user must be logged in while calling this.

Returns the results of the unsubscription for each JID.