Debian Codegraph @

liblomiri-app-launch/registry.h

raw
1 /*
2 * Copyright © 2016 Canonical Ltd.
3 *
4 * This program is free software: you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 3, as published
6 * by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranties of
10 * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
11 * PURPOSE. See the GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program. If not, see <http://www.gnu.org/licenses/>.
15 *
16 * Authors:
17 * Ted Gould <[email protected]>
18 */
19
20 #include <core/signal.h>
21 #include <functional>
22 #include <list>
23 #include <memory>
24
25 #include "application.h"
26 #include "helper.h"
27
28 #pragma once
29 #pragma GCC visibility push(default)
30
31 namespace lomiri
32 {
33 namespace app_launch
34 {
35
36 /** The application registry provides a central source for finding information
37 about the applications in the system. This includes installed applications
38 and running applications.
39
40 This class also holds onto shared resources for Lomiri App Launch objects and
41 functions. Generally speaking, there should only be one of them in the
42 process. There are singleton functions, getDefault() and clearDefault(), which
43 can be used to port applications from the old C API to the new C++ one
44 but their use is discouraged. */
45 class Registry
46 {
47 public:
48 /** Sometimes apps fail, this gives us information on why they
49 failed. */
50 enum class FailureType
51 {
52 CRASH, /**< The application was running, but failed while running. */
53 START_FAILURE /**< Something in the configuration of the application made it impossible to start the
54 application */
55 };
56
57 Registry();
58 virtual ~Registry();
59
60 /* Lots of application lists */
61 /** List the applications that are currently running, each will have a valid
62 Application::Instance at call time, but that could change as soon as
63 the call occurs.
64
65 \param registry Shared registry for the tracking
66 */
67 static std::list<std::shared_ptr<Application>> runningApps(std::shared_ptr<Registry> registry = getDefault());
68 /** List all of the applications that are currently installed on the system.
69 Queries the various packaging schemes that are supported to get thier
70 list of applications.
71
72 \param registry Shared registry for the tracking
73 */
74 static std::list<std::shared_ptr<Application>> installedApps(std::shared_ptr<Registry> registry = getDefault());
75
76 /* Signals to discover what is happening to apps */
77 /** Get the signal object that is signaled when an application has been
78 started.
79
80 \note This signal handler is activated on the UAL thread
81
82 \param reg Registry to get the handler from
83 */
84 static core::Signal<const std::shared_ptr<Application>&, const std::shared_ptr<Application::Instance>&>& appStarted(
85 const std::shared_ptr<Registry>& reg = getDefault());
86
87 /** Get the signal object that is signaled when an application has stopped.
88
89 \note This signal handler is activated on the UAL thread
90
91 \param reg Registry to get the handler from
92 */
93 static core::Signal<const std::shared_ptr<Application>&, const std::shared_ptr<Application::Instance>&>& appStopped(
94 const std::shared_ptr<Registry>& reg = getDefault());
95
96 /** Get the signal object that is signaled when an application has failed.
97
98 \note This signal handler is activated on the UAL thread
99
100 \param reg Registry to get the handler from
101 */
102 static core::
103 Signal<const std::shared_ptr<Application>&, const std::shared_ptr<Application::Instance>&, FailureType>&
104 appFailed(const std::shared_ptr<Registry>& reg = getDefault());
105
106 /** Get the signal object that is signaled when an application has been
107 paused.
108
109 \note This signal handler is activated on the UAL thread
110
111 \param reg Registry to get the handler from
112 */
113 static core::Signal<const std::shared_ptr<Application>&,
114 const std::shared_ptr<Application::Instance>&,
115 const std::vector<pid_t>&>&
116 appPaused(const std::shared_ptr<Registry>& reg = getDefault());
117
118 /** Get the signal object that is signaled when an application has been
119 resumed.
120
121 \note This signal handler is activated on the UAL thread
122
123 \param reg Registry to get the handler from
124 */
125 static core::Signal<const std::shared_ptr<Application>&,
126 const std::shared_ptr<Application::Instance>&,
127 const std::vector<pid_t>&>&
128 appResumed(const std::shared_ptr<Registry>& reg = getDefault());
129
130 /** Get the signal object that is signaled when an application's info
131 has been updated.
132
133 \note This signal handler is activated on the UAL thread
134
135 \param reg Registry to get the handler from
136 */
137 static core::Signal<const std::shared_ptr<Application>&>& appInfoUpdated(
138 const std::shared_ptr<Registry>& reg = getDefault());
139
140 /** Get the signal object that is signaled when there is a new application
141 that has been added to the system.
142
143 \note This signal handler is activated on the UAL thread
144
145 \param reg Registry to get the handler from
146 */
147 static core::Signal<const std::shared_ptr<Application>&>& appAdded(
148 const std::shared_ptr<Registry>& reg = getDefault());
149
150 /** Get the signal object that is signaled when an application is
151 removed from the system.
152
153 \note This signal handler is activated on the UAL thread
154
155 \param reg Registry to get the handler from
156 */
157 static core::Signal<const AppID&>& appRemoved(const std::shared_ptr<Registry>& reg = getDefault());
158
159 /** The Application Manager, almost always if you're not Lomiri, don't
160 use this API. Testing is a special case. Subclass this interface and
161 implement these functions.
162
163 Each function here is being passed a function object that takes a boolean
164 to reply. This will accept or reject the request. The function object
165 can be copied to another thread and executed if needed.
166
167 The reply is required for the application to start. It will block (not
168 currently implemented) until approval is given. If there are multiple requests
169 sent they may be replied out of order if desired.
170 */
171 class Manager
172 {
173 public:
174 /** Application wishes to startup
175
176 \note This signal handler is activated on the UAL thread
177
178 \param app Application requesting startup
179 \param instance Instance of the app, always valid but not useful
180 unless mulit-instance app.
181 \param reply Function object to reply if it is allowed to start
182 */
183 virtual void startingRequest(const std::shared_ptr<Application>& app,
184 const std::shared_ptr<Application::Instance>& instance,
185 std::function<void(bool)> reply) = 0;
186
187 /** Application wishes to have focus. Usually this occurs when
188 a URL for the application is activated and the running app is
189 requested.
190
191 \note This signal handler is activated on the UAL thread
192
193 \param app Application requesting focus
194 \param instance Instance of the app, always valid but not useful
195 unless mulit-instance app.
196 \param reply Function object to reply if it is allowed to focus
197 */
198 virtual void focusRequest(const std::shared_ptr<Application>& app,
199 const std::shared_ptr<Application::Instance>& instance,
200 std::function<void(bool)> reply) = 0;
201
202 /** Application wishes to resume. Usually this occurs when
203 a URL for the application is activated and the running app is
204 requested.
205
206 \note This signal handler is activated on the UAL thread
207
208 \param app Application requesting resume
209 \param instance Instance of the app, always valid but not useful
210 unless mulit-instance app.
211 \param reply Function object to reply if it is allowed to resume
212 */
213 virtual void resumeRequest(const std::shared_ptr<Application>& app,
214 const std::shared_ptr<Application::Instance>& instance,
215 std::function<void(bool)> reply) = 0;
216
217 protected:
218 Manager() = default;
219 virtual ~Manager() = default;
220 };
221
222 /** Set the manager of applications, which gives permissions for them to
223 start and gain focus. In almost all cases this should be Lomiri as it
224 will be controlling applications.
225
226 This function will failure if there is already a manager set.
227
228 \param manager A reference to the Manager object to call
229 \param registry Registry to register the manager on
230 */
231 static void setManager(const std::shared_ptr<Manager>& manager, const std::shared_ptr<Registry>& registry);
232
233 /** Remove the current manager on the registry */
234 void clearManager();
235
236 /* Helper Lists */
237 /** Get a list of all the helpers for a given helper type
238
239 \param type Helper type string
240 \param registry Shared registry for the tracking
241 */
242 static std::list<std::shared_ptr<Helper>> runningHelpers(Helper::Type type,
243 std::shared_ptr<Registry> registry = getDefault());
244
245 /** Get the signal object that is signaled when helper has been
246 started.
247
248 \note This signal handler is activated on the UAL thread
249
250 \param type Helper type string
251 \param reg Registry to get the handler from
252 */
253 static core::Signal<const std::shared_ptr<Helper>&, const std::shared_ptr<Helper::Instance>&>& helperStarted(
254 Helper::Type type, const std::shared_ptr<Registry>& reg = getDefault());
255
256 /** Get the signal object that is signaled when a helper has stopped.
257
258 \note This signal handler is activated on the UAL thread
259
260 \param type Helper type string
261 \param reg Registry to get the handler from
262 */
263 static core::Signal<const std::shared_ptr<Helper>&, const std::shared_ptr<Helper::Instance>&>& helperStopped(
264 Helper::Type type, const std::shared_ptr<Registry>& reg = getDefault());
265
266 /** Get the signal object that is signaled when a helper has failed.
267
268 \note This signal handler is activated on the UAL thread
269
270 \param type Helper type string
271 \param reg Registry to get the handler from
272 */
273 static core::Signal<const std::shared_ptr<Helper>&, const std::shared_ptr<Helper::Instance>&, FailureType>&
274 helperFailed(Helper::Type type, const std::shared_ptr<Registry>& reg = getDefault());
275
276 /* Default Junk */
277 /** Use the Registry as a global singleton, this function will create
278 a Registry object if one doesn't exist. Use of this function is
279 discouraged. */
280 static std::shared_ptr<Registry> getDefault();
281 /** Clear the default. If you're using the singleton interface in the
282 Registry::getDefault() function you should call this as your service
283 and/or tests exit to ensure you don't get Valgrind errors. */
284 static void clearDefault();
285
286 /* Hide our implementation */
287 /** \private */
288 class Impl;
289 /** \private */
290 std::shared_ptr<Impl> impl;
291
292 protected:
293 Registry(const std::shared_ptr<Impl>& inimpl);
294 };
295
296 } // namespace app_launch
297 } // namespace lomiri
298
299 #pragma GCC visibility pop