Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IpcTarget.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
6#include <PhosphorIpc/phosphoripc_export.h>
7
8#include <QObject>
9#include <QPointer>
10#include <QQmlParserStatus>
11#include <QString>
12#include <QVariantList>
13#include <QtCore/qtclasshelpermacros.h>
14#include <QtQml/qqmlregistration.h>
15
16namespace PhosphorIpc {
17
18// Pointer-only member; full definition only needed in the .cpp.
19class IpcRouter;
20
21// QML-side declarative wrapper for IpcRouter target registration.
22// Instantiated by user QML; auto-registers with the application's
23// IpcRouter in componentComplete(). Functions and signals declared
24// on the IpcTarget item itself form the exposed surface, the
25// schema generator walks the IpcTarget's own metaobject.
26//
27// Router discovery: looks for the QQmlEngine property
28// "phosphorIpcRouter" stashed by IpcEngine::install(). If the
29// application forgot to install the router, the IpcTarget logs a
30// qWarning at componentComplete and stays inert (no registration);
31// the rest of the QML tree continues to work.
32//
33// Lifetime: the router's QHash<QString, QPointer<QObject>> entry
34// auto-clears when this QObject is destroyed, but IpcTarget also
35// explicitly unregisters in its destructor so the registry's
36// targetUnregistered signal fires. The destructor passes `this` to
37// `unregisterTarget(name, obj)` so the router can reject the call
38// if the registration was rejected (duplicate name) and a different
39// target now owns the registry slot. Without that ownership check
40// a duplicate-rejected IpcTarget would tear down the legitimate
41// owner's binding on destruction.
42class PHOSPHORIPC_EXPORT IpcTarget : public QObject, public QQmlParserStatus, protected IpcCallContext
43{
44 Q_OBJECT
45 Q_INTERFACES(QQmlParserStatus)
46 QML_ELEMENT
47 Q_PROPERTY(QString target READ target WRITE setTarget NOTIFY targetChanged)
48public:
49 explicit IpcTarget(QObject* parent = nullptr);
50 ~IpcTarget() override;
51 Q_DISABLE_COPY_MOVE(IpcTarget)
52
53 [[nodiscard]] QString target() const;
54 void setTarget(const QString& name);
55
56 // Push an event to every subscriber for (target, signalName).
57 // QML plugin authors call this whenever a wire-visible state
58 // transition happens, explicit per-transition, in contrast
59 // to an auto-introspected Qt-signal hook. The args list is
60 // serialised to JSON via the router's variant-to-JSON helper
61 // (the same one used for sync call return values), so any
62 // QVariantList-shaped payload works.
63 Q_INVOKABLE void emitEvent(const QString& signalName, const QVariantList& args = {});
64
65 // Fails the wire call that runs the QML function, as
66 // IpcCallContext::sendErrorReply does for a C++ target. The client
67 // gets a CALL_FAILED error with `message`, and the function's
68 // return value is dropped. Outside a wire call it does nothing.
69 // IpcTarget's own methods are not callable over the wire.
70 Q_INVOKABLE void sendErrorReply(const QString& message);
71
72 // QQmlParserStatus, register with the router after QML has
73 // finished setting up the item (so the `target` property is
74 // populated).
75 void classBegin() override;
76 void componentComplete() override;
77
78Q_SIGNALS:
80
81private:
82 QString m_target;
83 QPointer<IpcRouter> m_router;
84 bool m_registered = false;
85};
86
87} // namespace PhosphorIpc
Definition IpcRouter.h:89
void setTarget(const QString &name)
QString target() const
IpcTarget(QObject *parent=nullptr)
void componentComplete() override
void sendErrorReply(const QString &message)
void emitEvent(const QString &signalName, const QVariantList &args={})
void classBegin() override
Definition IpcCallContext.h:10