QXmppPepBookmarkManager Class

Manages XEP-0402: PEP Native Bookmarks. More...

Header:	`#include <QXmppPepBookmarkManager.h>`
Since:	QXmpp 1.16
Inherits:	QXmppClientExtension and QXmppPubSubEventHandler

List of all members, including inherited members
QXmppPepBookmarkManager is part of Managers.

Public Functions

	QXmppPepBookmarkManager()
const std::optional<QList<QXmppMucBookmark>> &	bookmarks() const
QXmppTask<QXmpp::Result<>>	removeBookmark(const QString &jid)
QXmppTask<QXmpp::Result<>>	setBookmark(QXmppMucBookmark &&bookmark)

Reimplemented Public Functions

virtual QStringList	discoveryFeatures() const override
virtual bool	handlePubSubEvent(const QDomElement &element, const QString &pubSubService, const QString &nodeName) override

Signals

void	bookmarksAdded(const QList<QXmppMucBookmark> &newBookmarks)
void	bookmarksChanged(const QList<QXmppPepBookmarkManager::BookmarkChange> &bookmarkUpdates)
void	bookmarksRemoved(const QList<QString> &removedBookmarkJids)
void	bookmarksReset()

Detailed Description

Bookmarks are automatically fetched when the session is established (unless the stream has been resumed, in which case the cached bookmarks are still up to date). Changes made from other clients arrive as PubSub event notifications and trigger the corresponding signals.

If the fetch fails, the bookmarks are unknown: bookmarks() returns std::nullopt. Bookmarks fetched on an earlier connection are discarded in that case, because they may be outdated by now. bookmarksReset() is emitted in both cases, so it also signals a failed fetch.

Setup

QXmppPepBookmarkManager requires QXmppPubSubManager to be registered with the client:

auto *pubsub = client.addNewExtension<QXmppPubSubManager>();
auto *bookmarks = client.addNewExtension<QXmppPepBookmarkManager>();

Usage

connect(bm, &QXmppPepBookmarkManager::bookmarksReset, this, [bm]() {
    const auto &bookmarks = bm->bookmarks();
    if (!bookmarks) {
        // the bookmarks could not be fetched and are unknown now
        return;
    }
    for (const auto &bookmark : *bookmarks) {
        qDebug() << bookmark.jid() << bookmark.name();
    }
});

QXmppMucBookmark bookmark;
bookmark.setJid(u"room@conference.example.org"_s);
bookmark.setName(u"My Room"_s);
bookmark.setNick(u"alice"_s);
bookmark.setAutojoin(true);
bm->setBookmark(std::move(bookmark)).then(this, [](auto result) {
    if (std::holds_alternative<QXmppError>(result)) { return; }
});

Member Function Documentation

QXmppPepBookmarkManager::QXmppPepBookmarkManager()

Default constructor.

const std::optional<QList<QXmppMucBookmark>> &QXmppPepBookmarkManager::bookmarks() const

Returns the currently cached list of bookmarks.

Returns std::nullopt if the bookmarks are unknown, i.e. they have not been fetched yet or the last fetch failed. This is different from an empty list, which means that there are no bookmarks on the server.

A failed fetch also discards previously fetched bookmarks, so this can switch back to std::nullopt on a later connection. Connect to bookmarksReset() to be notified whenever the fetch completes, successfully or not.

`[signal]` void QXmppPepBookmarkManager::bookmarksAdded(const QList<QXmppMucBookmark> &newBookmarks)

Emitted with the newBookmarks that have been added. This is triggered by PubSub event notifications.

`[signal]` void QXmppPepBookmarkManager::bookmarksChanged(const QList<QXmppPepBookmarkManager::BookmarkChange> &bookmarkUpdates)

Emitted with the bookmarkUpdates describing the bookmarks that have been changed.

`[signal]` void QXmppPepBookmarkManager::bookmarksRemoved(const QList<QString> &removedBookmarkJids)

Emitted with the removedBookmarkJids of the bookmarks that have been retracted.

`[signal]` void QXmppPepBookmarkManager::bookmarksReset()

Emitted when the total set of bookmarks is replaced, i.e. when the bookmarks have been fetched after connecting, when fetching them failed and when the bookmarks node has been purged or deleted.

bookmarks() may be std::nullopt when this is emitted (the bookmarks could not be fetched). It must be checked before dereferencing it.

`[override virtual]` QStringList QXmppPepBookmarkManager::discoveryFeatures() const

Reimplements: QXmppClientExtension::discoveryFeatures() const.

Supported service discovery features.

`[override virtual]` bool QXmppPepBookmarkManager::handlePubSubEvent(const QDomElement &element, const QString &pubSubService, const QString &nodeName)

Reimplements: QXmppPubSubEventHandler::handlePubSubEvent(const QDomElement &element, const QString &pubSubService, const QString &nodeName).

Handles an incoming PubSub element for the given pubSubService and nodeName.

Returns true if the event was handled.

QXmppTask<QXmpp::Result<>> QXmppPepBookmarkManager::removeBookmark(const QString &jid)

Retracts the bookmark for the room at jid via XEP-0402: PEP Native Bookmarks.

Does nothing if no bookmark for jid exists. The retraction is propagated to all connected clients, which will trigger bookmarksRemoved() on this manager.

QXmppTask<QXmpp::Result<>> QXmppPepBookmarkManager::setBookmark(QXmppMucBookmark &&bookmark)

Publishes or updates a bookmark via XEP-0402: PEP Native Bookmarks.

If a bookmark for the same JID already exists it is replaced. The change is propagated to all connected clients via PubSub event notification, which will trigger bookmarksChanged() on this manager.

The JID of bookmark must not be empty.

Contents