Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IpcCallContext.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 <QString>
9
10namespace PhosphorIpc {
11
12class IpcRouter;
13
14// Lets a target fail the wire call that runs it, the way QDBusContext
15// lets a D-Bus adaptor send an error reply. A target class inherits it
16// next to QObject:
17//
18// class Control : public QObject, protected PhosphorIpc::IpcCallContext
19// {
20// Q_OBJECT
21// public:
22// Q_INVOKABLE int focus(int pane)
23// {
24// if (!exists(pane)) {
25// sendErrorReply(QStringLiteral("no pane %1").arg(pane));
26// return 0;
27// }
28// ...
29// }
30// };
31//
32// The client then gets {"type":"error","code":"CALL_FAILED","message":...}
33// in place of the reply, and the method's return value is dropped.
34// IpcRouter::invoke reports InvokeOutcome::CallFailed with the message.
35//
36// The base can be protected, as above. The router records the running call
37// for the target's most-derived object (dynamic_cast<const void*>, so the
38// target must be built with RTTI, Qt's default), and a context answers
39// only for its own object. The record lives on the router's thread for
40// the length of the call. A method that runs for any other reason (a
41// direct C++ call, a queued slot, a call into another object from inside
42// a wire call) sees no call: calledFromIpc() is false and
43// sendErrorReply() does nothing. That holds inside a nested event loop
44// the method runs (QEventLoop::exec, QDialog::exec): the object's other
45// slots that run in it see no call. It does not hold for
46// QCoreApplication::processEvents, which runs those slots at the
47// method's own loop level, where they see the method's call; a method
48// that waits for something defers its reply instead. A sendErrorReply()
49// or deferReply() made in such a slot does nothing and warns, since the
50// error or deferral was most likely meant for the method's call.
51//
52// A call that cannot answer before its method returns (it runs a process,
53// waits for the user) defers its reply: deferReply() returns an
54// IpcPendingReply that the target keeps and finishes later. See
55// IpcPendingReply.h for the rules. connectionId() names the client
56// connection that made the call, so a target can send that client events of
57// its own (IpcRouter::sendEvent, on the router that runs the call) and drop
58// the client's work when the connection closes
59// (IpcRouter::connectionClosed).
60class PHOSPHORIPC_EXPORT IpcCallContext
61{
62public:
63 virtual ~IpcCallContext();
64
65protected:
66 IpcCallContext() = default;
69
70 // True while the router runs a wire call on this object.
71 [[nodiscard]] bool calledFromIpc() const;
72
73 // Fails the running wire call with `message`. A second call replaces
74 // the message. Outside a wire call it does nothing. After deferReply()
75 // the error still goes out when the method returns, unless the pending
76 // reply has answered the call already, and the pending reply then has
77 // nothing left to answer.
78 void sendErrorReply(const QString& message);
79
80 // The connection that made the running wire call: a number the router
81 // gives each client connection it accepts, unique in the process and
82 // never reused, also across routers. 0 outside a wire call and for a
83 // call that came from no connection (a direct IpcRouter::invoke).
84 [[nodiscard]] quint64 connectionId() const;
85
86 // The process ID of the client that made the running wire call: the
87 // process that connected, which the router reads from the socket
88 // (SO_PEERCRED) once, when it accepts the connection. The kernel gives
89 // it, so a client cannot claim another process's ID. It stays the
90 // connecting process's ID when that process hands the socket to
91 // another or exits. 0 outside a wire call, for a call that came from
92 // no connection (a direct IpcRouter::invoke), and where the router
93 // could not read it (a platform other than Linux, or a failed
94 // getsockopt).
95 [[nodiscard]] qint64 connectionPid() const;
96
97 // Defers the running wire call's reply. The router sends nothing when
98 // the method returns, and drops its return value. The call is answered
99 // through the returned object (finish or fail) or, if that object goes
100 // away unanswered, with a CALL_ABANDONED error.
101 //
102 // Returns an object that holds no call (isValid() false):
103 // - outside a wire call;
104 // - on a second deferReply() in the same call (with a warning);
105 // - for a call from no connection. IpcRouter::invoke then reports
106 // InvokeOutcome::Deferred, since there is no client to answer later;
107 // - when the connection has IpcRouter::MaxPendingCallsPerConnection
108 // deferred calls waiting for their answer already. The call then
109 // fails with CALL_FAILED when the method returns, so a client
110 // cannot pile up deferred work without bound.
112
113private:
114 friend class IpcRouter;
115
116 // One wire call that runs on this thread. A call made from inside
117 // another (a nested event loop) keeps the outer one to restore.
118 struct Call
119 {
120 const void* object = nullptr;
121 // The thread's event loop level when the call started. A slot run
122 // by a nested event loop inside the method sees a higher level,
123 // and no call.
124 int loopLevel = 0;
125 bool failed = false;
126 QString message;
127 Call* outer = nullptr;
128 // The router that runs the call, the connection and request it came
129 // from and the connection's process (all 0 for a direct
130 // IpcRouter::invoke).
131 IpcRouter* router = nullptr;
132 quint64 connectionId = 0;
133 qint64 connectionPid = 0;
134 qint64 requestId = 0;
135 // Set by deferReply(). pendingToken is the router's key for the
136 // pending reply, 0 when the call came from no connection.
137 bool deferred = false;
138 quint64 pendingToken = 0;
139 };
140 static Call*& current();
141 [[nodiscard]] Call* call() const;
142 // Warns when this object's method runs a wire call further out, at
143 // another event loop level: `what` was called from a slot of a nested
144 // loop and did nothing.
145 void warnIfNestedInCall(const char* what) const;
146};
147
148} // namespace PhosphorIpc
quint64 connectionId() const
void sendErrorReply(const QString &message)
qint64 connectionPid() const
friend class IpcRouter
Definition IpcCallContext.h:114
IpcCallContext & operator=(const IpcCallContext &)=delete
IpcCallContext(const IpcCallContext &)=delete
IpcPendingReply deferReply()
Definition IpcPendingReply.h:61
Definition IpcRouter.h:89
Definition IpcCallContext.h:10