QXmpp::Hooks Class

Detailed Description

Hooks connect extensions without requiring a common base class or virtual functions in public headers. Any extension (or the application) can define a hook by declaring a type. Other extensions add handlers to it using the hook's type. Nothing needs to be declared in QXmpp itself and handlers can be added before the extension defining the hook is added to the client.

A hook is defined by a type with a static Name and a Signature. The name identifies the hook, the signature is the type of the handlers. The return type of the signature decides how the handlers are run:

• void: all handlers are run.
• QXmpp::HookResult: the handlers are run until one returns QXmpp::HookResult::Stop.
• Any other type: the hook has a single responder. Only the first handler is run and run() returns its result as std::optional, std::nullopt if there is no handler. Adding another handler logs a warning, it is still added and the sequence decides which one is used, e.g. an application can replace a handler of QXmpp with HookSequence::Early.

Hooks whose signature returns a QXmppTask are asynchronous: a handler can wait for a result (e.g. a database query) before the next handler is run. Handlers of asynchronous hooks may also return the value directly. If the owner of the single responder of an asynchronous hook is destroyed or its task is dropped, the result is std::nullopt; the next handler is not run instead.

Names use a reverse domain prefix, so hooks of different projects don't collide. Hooks of QXmpp start with org.qxmpp.

struct AffiliationChanged {
    static constexpr QStringView Name = u"org.qxmpp.muc.affiliation-changed";
    using Signature = void(const QString &roomJid, const QXmpp::Muc::Item &item);
};

A Hooks object is a lightweight handle to the hooks of a client together with an owner. Handlers added through it are removed when the owner is destroyed. Extensions usually add their handlers in their constructor using QXmppClientExtension::hooks():

MyManager::MyManager()
    : d(std::make_unique<MyManagerPrivate>())
{
    hooks().add<QXmpp::Muc::AffiliationChanged>(d.get(), &MyManagerPrivate::onAffiliationChanged);
}

The extension defining a hook runs it:

hooks().run<QXmpp::Muc::AffiliationChanged>(roomJid, item);

To collect values from multiple handlers (a fold), pass a mutable reference as argument, like QXmpp::Disco::CollectInfo does.

Keys

A hook can have a Key type. Handlers are then added for a key and run() only runs the handlers of the given key. Keys can be strings, enums of QXmpp with a string representation and tuples of them, e.g. the tag name and namespace of an element.

struct EventReceived {
    static constexpr QStringView Name = u"org.qxmpp.pubsub.event-received";
    using Key = QStringView;
    using Signature = QXmpp::HookResult(const QDomElement &element, const QString &service, const QString &node);
};

hooks().add<EventReceived>(u"urn:xmpp:mix:nodes:info", this, &MyManager::handleEvent);
hooks().run<EventReceived>(node, element, service, node);

Registries

Registries can be built on hooks, so they share the lifetime rules of handlers. For example, QXmpp::E2ee::Providers stores each end-to-end encryption provider as the single responder of a keyed hook:

struct PackLookup {
    static constexpr QStringView Name = u"org.example.stickers.pack-lookup";
    using Key = QString;
    using Signature = StickerPack();
};

class StickerPacks
{
public:
    explicit StickerPacks(QXmpp::Hooks hooks) : m_hooks(std::move(hooks)) { }

    void add(StickerPack pack) const
    {
        const auto id = pack.id;
        m_hooks.add<PackLookup>(id, [pack = std::move(pack)] { return pack; });
    }
    std::optional<StickerPack> find(const QString &id) const
    {
        return m_hooks.run<PackLookup>(id);
    }

private:
    QXmpp::Hooks m_hooks;
};

// in an extension, e.g. in its constructor
StickerPacks(hooks()).add(pack);

Adapted hooks

A type with a Target hook and a static adapt() function adds typed handlers to another hook, e.g. a hook working on serialized data. adapt() turns the handler into a handler of the target. For a keyed target, the static key() function returns the key. Handlers are added with add() like to other hooks, the target is run with run():

struct ConfigChanged {
    static constexpr QStringView Name = u"org.example.config-changed";
    using Key = QString;
    using Signature = void(const QString &json);
};

template<typename T>
struct Changed {
    using Target = ConfigChanged;
    static QString key() { return T::Id; }

    template<typename Handler>
        requires std::invocable<Handler &, T>
    static auto adapt(Handler &&handler)
    {
        return [handler = std::forward<Handler>(handler)](const QString &json) mutable {
            handler(T::fromJson(json));
        };
    }
};

hooks().add<Changed<ProxySettings>>([](ProxySettings &&settings) { ... });

Hook names should be prefixed to avoid collisions, QXmpp uses "org.qxmpp.". Handlers with a signature or key type differing from the one of the existing handlers of the same hook are rejected.