Contents

QXmppRosterManager Class

The QXmppRosterManager class provides access to a connected client's roster. More...

Header: #include <QXmppRosterManager.h>
Inherits: QXmppClientExtension

Public Types

Result

Public Functions

QXmppRosterManager(QXmppClient *client)
(since QXmpp 1.5 Returns true on success.) QXmppTask<QXmppRosterManager::Result> addRosterItem(const QString &bareJid, const QString &name = {}, const QSet<QString> &groups = {})
(since QXmpp 1.16) QXmppTask<void> clearCache()
QMap<QString, QXmppPresence> getAllPresencesForBareJid(const QString &bareJid) const
QXmppPresence getPresence(const QString &bareJid, const QString &resource) const
QStringList getResources(const QString &bareJid) const
QStringList getRosterBareJids() const
QXmppRosterIq::Item getRosterEntry(const QString &bareJid) const
bool isRosterReceived() const
(since QXmpp 1.5 Returns true on success.) QXmppTask<QXmppRosterManager::Result> removeRosterItem(const QString &bareJid)
(since QXmpp 1.5) QXmppTask<QXmppRosterManager::Result> renameRosterItem(const QString &bareJid, const QString &name)
(since QXmpp 1.16) void setStorage(std::unique_ptr<QXmppRosterStorage> storage)
(since QXmpp 1.16) QXmppRosterStorage *storage() const
(since QXmpp 1.5) QXmppTask<QXmpp::SendResult> subscribeTo(const QString &bareJid, const QString &reason = {})
(since QXmpp 1.5 Returns true on success.) QXmppTask<QXmpp::SendResult> unsubscribeFrom(const QString &bareJid, const QString &reason = {})
(since QXmpp 1.16) QXmppTask<QXmppRosterManager::Result> updateRosterGroups(const QString &bareJid, const QSet<QString> &groups)

Public Slots

bool acceptSubscription(const QString &bareJid, const QString &reason = {})
bool addItem(const QString &bareJid, const QString &name = {}, const QSet<QString> &groups = {})
bool refuseSubscription(const QString &bareJid, const QString &reason = {})
bool removeItem(const QString &bareJid)
bool renameItem(const QString &bareJid, const QString &name)
bool subscribe(const QString &bareJid, const QString &reason = {})
bool unsubscribe(const QString &bareJid, const QString &reason = {})

Signals

void itemAdded(const QString &bareJid)
void itemChanged(const QString &bareJid)
void itemRemoved(const QString &bareJid)
void presenceChanged(const QString &bareJid, const QString &resource)
void rosterReceived()
void subscriptionReceived(const QString &bareJid)
(since QXmpp 1.5) void subscriptionRequestReceived(const QString &subscriberBareJid, const QXmppPresence &presence)

Detailed Description

Note: Its object should not be created using its constructor. Instead QXmppClient::findExtension<QXmppRosterManager>() should be used to get the instantiated object of this class.

It stores all the Roster and Presence details of all the roster entries (that is all the bareJids) in the client's friend's list. It provides the functionality to get all the bareJids in the client's roster and Roster and Presence details of the same.

After the QXmpp connected successfully to the XMPP server the signal QXmppClient::connected() is emitted and the roster is requested from the server. Once QXmpp receives the roster the signal QXmppRosterManager::rosterReceived() is emitted and after that the methods of this class can be used to get the roster entries.

QXmppRosterManager::isRosterReceived() can be used to find out whether the roster has been received yet.

The itemAdded(), itemChanged() and itemRemoved() signals are emitted whenever roster entries are added, changed or removed.

The presenceChanged() signal is emitted whenever the presence for a roster item changes.

XEP-0283: Moved

XEP-0283: Moved

provides a way to inform other users that an account has moved. This allows a presence subscription request from a new account to be automatically linked to the old account. However, this requires verification via a corresponding PubSub node on the old account.

The roster manager automatically checks entries using the QXmppMovedManager. For this to work, the moved manager must be added to the QXmppClient. If the moved manager is not found or the specified old JID is incorrect, the entry in the presence subscription request will be removed.

The received and verified presence subscription request is emitted via subscriptionRequestReceived() and the old JID can be found in QXmppPresence::oldJid(). It is safe to assume that this old JID is valid since QXmpp 1.10.2.

Accepting moved subscription requests automatically is discouraged in [section 4.3](https://xmpp.org/extensions/xep-0283.html#receive-notification-client) of the XEP.

Behaviour in previous versions

Support in the roster manager and in QXmppPresence was initially added in 1.9.0.

In QXmpp 1.9.0 until 1.9.4 and 1.10.0 until 1.10.1 subscription requests with a Moved element are verified and automatically accepted without emitting subscriptionRequestReceived(). If verification fails, the **invalid** old JID is passed in subscriptionRequestReceived()!

Member Type Documentation

[alias] QXmppRosterManager::Result

Empty result containing QXmpp::Success or a QXmppError.

Member Function Documentation

[explicit] QXmppRosterManager::QXmppRosterManager(QXmppClient *client)

Constructs a roster manager.

client.

[slot] bool QXmppRosterManager::acceptSubscription(const QString &bareJid, const QString &reason = {})

Accepts an existing subscription request or pre-approves future subscription requests. Returns true on success.

You can call this method in reply to the subscriptionRequest() signal or to create a pre-approved subscription.

Note: Pre-approving subscription requests is only allowed, if the server supports RFC6121 and advertises the 'urn:xmpp:features:pre-approval' stream feature.

reason and bareJid.

See also QXmppStreamFeatures::preApprovedSubscriptionsSupported().

[slot] bool QXmppRosterManager::addItem(const QString &bareJid, const QString &name = {}, const QSet<QString> &groups = {})

Adds a new item with bare JID bareJid to the roster without sending any subscription requests. name is an optional name for the item and groups specifies optional groups for the item.

As a result, the server will initiate a roster push, causing the itemAdded() or itemChanged() signal to be emitted. Returns true on success.

[since QXmpp 1.5 Returns true on success.] QXmppTask<QXmppRosterManager::Result> QXmppRosterManager::addRosterItem(const QString &bareJid, const QString &name = {}, const QSet<QString> &groups = {})

Adds a new item with bare JID bareJid to the roster without sending any subscription requests. name is an optional name for the item and groups specifies optional groups for the item.

As a result, the server will initiate a roster push, causing the itemAdded() or itemChanged() signal to be emitted.

This function was introduced in QXmpp 1.5 Returns true on success..

[since QXmpp 1.16] QXmppTask<void> QXmppRosterManager::clearCache()

Wipes the cached roster (in-memory and storage) and resets the version.

Use this on account switch or explicit logout where the previous roster must not leak into the next session.

This function was introduced in QXmpp 1.16.

QMap<QString, QXmppPresence> QXmppRosterManager::getAllPresencesForBareJid(const QString &bareJid) const

Returns a QMap<QString, QXmppPresence> of resource and its respective presence for all the resources of the given bareJid. A bareJid can have multiple resources and each resource will have a presence associated with it.

QXmppPresence QXmppRosterManager::getPresence(const QString &bareJid, const QString &resource) const

Returns the QXmppPresence of the given resource of the given bareJid.

QStringList QXmppRosterManager::getResources(const QString &bareJid) const

Returns the list of associated resources for the given bareJid as a QStringList.

QStringList QXmppRosterManager::getRosterBareJids() const

Returns a QStringList list of all the bareJids present in the roster.

QXmppRosterIq::Item QXmppRosterManager::getRosterEntry(const QString &bareJid) const

Returns the roster entry of the given bareJid. If bareJid is not in the database and empty QXmppRosterIq::Item will be returned.

bool QXmppRosterManager::isRosterReceived() const

Returns true if the roster has been received, otherwise false.

On disconnecting this is reset to false if no stream management is used by the client and so the stream cannot be resumed later.

[signal] void QXmppRosterManager::itemAdded(const QString &bareJid)

This signal is emitted when the roster entry of a particular bareJid is added as a result of roster push.

[signal] void QXmppRosterManager::itemChanged(const QString &bareJid)

This signal is emitted when the roster entry of a particular bareJid changes as a result of roster push.

bareJid.

[signal] void QXmppRosterManager::itemRemoved(const QString &bareJid)

This signal is emitted when the roster entry of a particular bareJid is removed as a result of roster push.

bareJid.

[signal] void QXmppRosterManager::presenceChanged(const QString &bareJid, const QString &resource)

This signal is emitted when the presence of a particular bareJid and resource changes.

[slot] bool QXmppRosterManager::refuseSubscription(const QString &bareJid, const QString &reason = {})

Refuses a subscription request. Returns true on success.

You can call this method in reply to the subscriptionRequest() signal.

reason and bareJid.

[slot] bool QXmppRosterManager::removeItem(const QString &bareJid)

Removes the roster item with bare JID bareJid and cancels subscriptions to and from the contact.

As a result, the server will initiate a roster push, causing the itemRemoved() signal to be emitted. Returns true on success.

[since QXmpp 1.5 Returns true on success.] QXmppTask<QXmppRosterManager::Result> QXmppRosterManager::removeRosterItem(const QString &bareJid)

Removes the roster item with bare JID bareJid and cancels subscriptions to and from the contact.

As a result, the server will initiate a roster push, causing the itemRemoved() signal to be emitted.

This function was introduced in QXmpp 1.5 Returns true on success..

[slot] bool QXmppRosterManager::renameItem(const QString &bareJid, const QString &name)

Renames the roster item with bare JID bareJid to name; returns true on success.

As a result, the server will initiate a roster push, causing the itemChanged() signal to be emitted.

[since QXmpp 1.5] QXmppTask<QXmppRosterManager::Result> QXmppRosterManager::renameRosterItem(const QString &bareJid, const QString &name)

Renames the roster item with bare JID bareJid to name.

As a result, the server will initiate a roster push, causing the itemChanged() signal to be emitted.

This function was introduced in QXmpp 1.5.

[signal] void QXmppRosterManager::rosterReceived()

This signal is emitted when the Roster IQ is received after a successful connection. That is the roster entries are empty before this signal is emitted. One should use getRosterBareJids() and getRosterEntry() only after this signal has been emitted.

Note: If the previous stream could be resumed, this signal is not emitted since QXmpp 1.4. Changes since the last connection are reported via the itemAdded(), itemChanged() and itemRemoved() signals.

[since QXmpp 1.16] void QXmppRosterManager::setStorage(std::unique_ptr<QXmppRosterStorage> storage)

Sets the storage backend used to persist the roster between sessions and transfers ownership.

Pass an empty unique_ptr to fall back to the default in-memory storage. Any previously configured storage is destroyed.

Must be called before the QXmppClient connects to the server; switching storage mid-session is unsupported and will leave the cache inconsistent.

This function was introduced in QXmpp 1.16.

See also storage().

[since QXmpp 1.16] QXmppRosterStorage *QXmppRosterManager::storage() const

Returns the storage backend used to persist the roster between sessions.

By default this is an internally owned QXmppRosterMemoryStorage. Call setStorage() to plug in a persistent backend. The returned pointer is owned by the manager and stays valid for the manager's lifetime (or until setStorage() is called again).

This function was introduced in QXmpp 1.16.

See also setStorage().

[slot] bool QXmppRosterManager::subscribe(const QString &bareJid, const QString &reason = {})

Requests a subscription to the given contact; returns true on success.

As a result, the server will initiate a roster push, causing the itemAdded() or itemChanged() signal to be emitted.

reason and bareJid.

[since QXmpp 1.5] QXmppTask<QXmpp::SendResult> QXmppRosterManager::subscribeTo(const QString &bareJid, const QString &reason = {})

Requests a subscription to the given contact.

As a result, the server will initiate a roster push, causing the itemAdded() or itemChanged() signal to be emitted.

reason and bareJid.

This function was introduced in QXmpp 1.5.

[signal] void QXmppRosterManager::subscriptionReceived(const QString &bareJid)

This signal is emitted when a contact asks to subscribe to your presence.

You can either accept the request by calling acceptSubscription() or refuse it by calling refuseSubscription().

Note: If you set QXmppConfiguration::autoAcceptSubscriptions() to true, this signal will not be emitted. This is only valid for non moved or verified moved subscription. If the subscription is a moved one and the roster's old-jid's subscription is not either from or both then QXmppConfiguration::autoAcceptSubscriptions() is ignored.

bareJid.

[signal, since QXmpp 1.5] void QXmppRosterManager::subscriptionRequestReceived(const QString &subscriberBareJid, const QXmppPresence &presence)

This signal is emitted when a JID asks to subscribe to the user's presence.

The user can either accept the request by calling acceptSubscription() or refuse it by calling refuseSubscription().

Since *QXmpp 1.10.2* only verified XEP-0283: Moved old JIDs are passed in presence. If verification fails or the given old JID is not valid, the attribute is cleared in the QXmppPresence. See the QXmppRosterManager class description for more details.

Note: If QXmppConfiguration::autoAcceptSubscriptions() is set to true or the subscription request is automatically accepted by the QXmppMovedManager, this signal will not be emitted.

subscriberBareJid is the bare JID that wants to subscribe to the user's presence. presence is the presence stanza, e.g. containing the message (presence.statusText()), XEP-0283: Moved old JID or other information.

This function was introduced in QXmpp 1.5.

[slot] bool QXmppRosterManager::unsubscribe(const QString &bareJid, const QString &reason = {})

Removes a subscription to the given contact.

As a result, the server will initiate a roster push, causing the itemChanged() signal to be emitted. Returns true on success.

reason and bareJid.

[since QXmpp 1.5 Returns true on success.] QXmppTask<QXmpp::SendResult> QXmppRosterManager::unsubscribeFrom(const QString &bareJid, const QString &reason = {})

Removes a subscription to the given contact.

As a result, the server will initiate a roster push, causing the itemChanged() signal to be emitted.

reason and bareJid.

This function was introduced in QXmpp 1.5 Returns true on success..

[since QXmpp 1.16] QXmppTask<QXmppRosterManager::Result> QXmppRosterManager::updateRosterGroups(const QString &bareJid, const QSet<QString> &groups)

Updates the groups of the roster item with bare JID bareJid.

The given groups replace the contact's existing groups entirely; pass the full desired set. The contact's name and other properties are preserved.

As a result, the server will initiate a roster push, causing the itemChanged() signal to be emitted.

This function was introduced in QXmpp 1.16.