QXmpp: QXmppRosterManager Class Reference

QXmpp Version: 1.14.4

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

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

`#include <QXmppRosterManager.h>`

Inheritance diagram for QXmppRosterManager:

## Public Types
using | Result = std::variant<QXmpp::Success, QXmppError>
| Empty result containing QXmpp::Success or a QXmppError.

## Public Member Functions
| QXmppRosterManager (QXmppClient *stream)
bool | isRosterReceived () const
QStringList | getRosterBareJids () const
QXmppRosterIq::Item | getRosterEntry (const QString &bareJid) const
QStringList | getResources (const QString &bareJid) const
QMap< QString, QXmppPresence > | getAllPresencesForBareJid (const QString &bareJid) const
QXmppPresence | getPresence (const QString &bareJid, const QString &resource) const
QXmppTask< Result > | addRosterItem (const QString &bareJid, const QString &name={}, const QSet< QString > &groups={})
QXmppTask< Result > | removeRosterItem (const QString &bareJid)
QXmppTask< Result > | renameRosterItem (const QString &bareJid, const QString &name)
QXmppTask< QXmpp::SendResult > | subscribeTo (const QString &bareJid, const QString &reason={})
QXmppTask< QXmpp::SendResult > | unsubscribeFrom (const QString &bareJid, const QString &reason={})
Q_SLOT bool | acceptSubscription (const QString &bareJid, const QString &reason={})
Q_SLOT bool | refuseSubscription (const QString &bareJid, const QString &reason={})
Q_SLOT bool | addItem (const QString &bareJid, const QString &name={}, const QSet< QString > &groups={})
Q_SLOT bool | removeItem (const QString &bareJid)
Q_SLOT bool | renameItem (const QString &bareJid, const QString &name)
Q_SLOT bool | subscribe (const QString &bareJid, const QString &reason={})
Q_SLOT bool | unsubscribe (const QString &bareJid, const QString &reason={})
Q_SIGNAL void | rosterReceived ()
Q_SIGNAL void | presenceChanged (const QString &bareJid, const QString &resource)
| This signal is emitted when the presence of a particular bareJid and resource changes.
Q_SIGNAL void | subscriptionReceived (const QString &bareJid)
Q_SIGNAL void | subscriptionRequestReceived (const QString &subscriberBareJid, const QXmppPresence &presence)
Q_SIGNAL void | itemAdded (const QString &bareJid)
Q_SIGNAL void | itemChanged (const QString &bareJid)
Q_SIGNAL void | itemRemoved (const QString &bareJid)
Public Member Functions inherited from QXmppClientExtension
| QXmppClientExtension ()
virtual QStringList | discoveryFeatures () const
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.

## Friends
class | QXmppMixManager

## Detailed Description

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

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 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()!

## Constructor & Destructor Documentation

## ◆ QXmppRosterManager()

QXmppRosterManager::QXmppRosterManager | ( | QXmppClient * | client | ) |
| explicit

Constructs a roster manager.

## Member Function Documentation

## ◆ acceptSubscription()

bool QXmppRosterManager::acceptSubscription | ( | const QString & | bareJid,
|  | const QString & | reason = {} )

Accepts an existing subscription request or pre-approves future subscription requests.

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.

See also
  QXmppStreamFeatures::preApprovedSubscriptionsSupported()

## ◆ addItem()

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

Adds a new item the roster without sending any subscription requests.

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

Parameters

  bareJid |
  name | Optotional name for the item.
  groups | Optional groups for the item.

## ◆ addRosterItem()

QXmppTask< QXmppRosterManager::Result > QXmppRosterManager::addRosterItem | ( | const QString & | bareJid,
|  | const QString & | name = {},
|  | const QSet< QString > & | groups = {} )

Adds a new item to the roster without sending any subscription requests.

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

Parameters

  bareJid |
  name | Optional name for the item.
  groups | Optional groups for the item.

Since
  QXmpp 1.5

## ◆ getAllPresencesForBareJid()

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

Get all the presences of all the resources of the given bareJid. A bareJid can have multiple resources and each resource will have a presence associated with it.

Parameters

  bareJid | as a QString

Returns
  Map of resource and its respective presence QMap<QString, QXmppPresence>

## ◆ getPresence()

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

Get the presence of the given resource of the given bareJid.

Parameters

  bareJid | as a QString
  resource | as a QString

Returns
  QXmppPresence

## ◆ getResources()

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

Get all the associated resources with the given bareJid.

Parameters

  bareJid | as a QString

Returns
  list of associated resources as a QStringList

## ◆ getRosterBareJids()

QStringList QXmppRosterManager::getRosterBareJids | ( |  | ) | const

Function to get all the bareJids present in the roster.

Returns
  QStringList list of all the bareJids

## ◆ getRosterEntry()

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

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

Parameters

  bareJid | as a QString

## ◆ isRosterReceived()

bool QXmppRosterManager::isRosterReceived | ( |  | ) | const

Function to check whether the roster has been received or not.

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

Returns
  true if roster received else false

## ◆ itemAdded()

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

## ◆ itemChanged()

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

## ◆ itemRemoved()

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

## ◆ onRegistered()

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

Called after the extension has been added to a QXmppClient.

Parameters

  client |

Reimplemented from QXmppClientExtension.

## ◆ onUnregistered()

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

Called after the extension has been removed from a QXmppClient.

Parameters

  client |

Reimplemented from QXmppClientExtension.

## ◆ refuseSubscription()

bool QXmppRosterManager::refuseSubscription | ( | const QString & | bareJid,
|  | const QString & | reason = {} )

Refuses a subscription request.

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

## ◆ removeItem()

bool QXmppRosterManager::removeItem | ( | const QString & | bareJid | ) |

Removes a roster item 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.

Parameters

  bareJid |

## ◆ removeRosterItem()

QXmppTask< QXmppRosterManager::Result > QXmppRosterManager::removeRosterItem | ( | const QString & | bareJid | ) |

Removes a roster item 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.

Parameters

  bareJid |

Since
  QXmpp 1.5

## ◆ renameItem()

bool QXmppRosterManager::renameItem | ( | const QString & | bareJid,
|  | const QString & | name )

Renames a roster item.

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

Parameters

  bareJid |
  name |

## ◆ renameRosterItem()

QXmppTask< QXmppRosterManager::Result > QXmppRosterManager::renameRosterItem | ( | const QString & | bareJid,
|  | const QString & | name )

Renames a roster item.

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

Parameters

  bareJid |
  name |

Since
  QXmpp 1.5

## ◆ rosterReceived()

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

## ◆ subscribe()

bool QXmppRosterManager::subscribe | ( | 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.

## ◆ subscribeTo()

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.

Since
  QXmpp 1.5

## ◆ subscriptionReceived()

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

## ◆ subscriptionRequestReceived()

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

Parameters

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

Since
  QXmpp 1.5

## ◆ unsubscribe()

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.

## ◆ unsubscribeFrom()

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.

Since
  QXmpp 1.5

The documentation for this class was generated from the following files:

- QXmppRosterManager.h
- QXmppRosterManager.cpp