Debian Codegraph @

liblomiri-app-launch/helper.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 <memory>
21 #include <vector>
22
23 #include "config.h"
24
25 #ifdef LAL_USE_MIRCLIENT
26 #include <mir_toolkit/mir_prompt_session.h>
27 #endif
28
29 #include "appid.h"
30 #include "type-tagger.h"
31
32 #pragma once
33 #pragma GCC visibility push(default)
34
35 namespace lomiri
36 {
37 namespace app_launch
38 {
39
40 class Registry;
41
42 /** Class representing an untrusted helper in the system. Untrusted
43 helpers are used by trusted helpers to get some amount of functionality
44 from a package in the system. Typically this is via a Click hook
45 in a Click package.
46
47 In order to setup a untrusted helper the trusted helper needs to
48 install a small executable that gives the equivallent of a Desktop
49 Exec string to the system. This is done by installing the executable
50 in the ``/usr/lib/$(arch)/lomiri-app-launch/$(helper type)/exec-tool``.
51 A simple example can be seen in [URL Dispatcher's URL Overlay
52 helper](http://bazaar.launchpad.net/~indicator-applet-developers/url-dispatcher/trunk.15.10/view/head:/service/url-overlay.c).
53 It is important to note that the helper will be confined with the apparmor
54 profile associated with the AppID that is being used. For Click based
55 applications this means that an untrusted helper should be its own
56 stanza in the Click manifest with its own ``apparmor`` hook. This will
57 configure the confinement for the helper.
58
59 Many times an untrusted helper runs in a non-user-facing mode, it is
60 important that UAL **DOES NOT** implement a lifecycle for the helper. It
61 is the responsibility of the trusted helper to do that. Many times this
62 is a timeout or other similar functionality. These are the tools to
63 implement those in a reasonable fashion (services don't have to worry
64 about AppArmor, cgroups, or jobs) but it doesn't not implement them
65 by itself.
66 */
67 class Helper
68 {
69 protected:
70 Helper() = default;
71 virtual ~Helper() = default;
72
73 public:
74 /** \private */
75 struct TypeTag;
76 /** \private */
77 struct URLTag;
78
79 /** \private */
80 typedef TypeTagger<TypeTag, std::string> Type;
81 /** \private */
82 typedef TypeTagger<URLTag, std::string> URL;
83
84 /** Create a new helper object from an AppID
85
86 \param type Type of untrusted helper
87 \param appid AppID of the helper
88 \param registry Shared registry instance
89 */
90 static std::shared_ptr<Helper> create(Type type, AppID appid, std::shared_ptr<Registry> registry);
91
92 /** Get the AppID for this helper */
93 virtual AppID appId() const = 0;
94
95 /** Running instance of a a Helper */
96 class Instance
97 {
98 protected:
99 Instance() = default;
100 virtual ~Instance() = default;
101
102 public:
103 /** Check to see if this instance is running */
104 virtual bool isRunning() = 0;
105
106 /** Stop a running helper */
107 virtual void stop() = 0;
108
109 bool operator==(const Instance& b) const;
110 bool operator!=(const Instance& b) const;
111 };
112
113 /** Check to see if there are any instances of this untrusted helper */
114 virtual bool hasInstances() = 0;
115 /** Get the list of instances of this helper */
116 virtual std::vector<std::shared_ptr<Instance>> instances() = 0;
117
118 /** Launch an instance of a helper with an optional set of URLs
119 that get passed to the helper.
120
121 \param urls List of URLs to passed to the untrusted helper
122 */
123 virtual std::shared_ptr<Instance> launch(std::vector<URL> urls = {}) = 0;
124
125 #ifdef LAL_USE_MIRCLIENT
126 /** Launch an instance of a helper that is run in a Mir Trusted
127 Prompt session. The session should be created by the trusted
128 helper using the Mir function ``mir_connection_create_prompt_session_sync()``.
129
130 \param session Mir trusted prompt session
131 \param urls List of URLs to passed to the untrusted helper
132 */
133 virtual std::shared_ptr<Instance> launch(MirPromptSession* session, std::vector<URL> urls = {}) = 0;
134 #endif
135 /** Set the exec from a helper utility. This function should only
136 be used inside a helper exec util.
137
138 \param exec The exec line to use for the helper with the AppID given
139 */
140 static void setExec(std::vector<std::string> exec);
141
142 bool operator==(const Helper& b) const;
143 bool operator!=(const Helper& b) const;
144 };
145
146 } // namespace app_launch
147 } // namespace lomiri
148
149 #pragma GCC visibility pop