Mir
wayland_extensions.h
Go to the documentation of this file.
1 /*
2  * Copyright © 2018-2019 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 2 or 3 as
6  * published by the Free Software Foundation.
7  *
8  * This program is distributed in the hope that it will be useful,
9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11  * GNU General Public License for more details.
12  *
13  * You should have received a copy of the GNU General Public License
14  * along with this program. If not, see <http://www.gnu.org/licenses/>.
15  */
16 
17 #ifndef MIRAL_WAYLAND_EXTENSIONS_H
18 #define MIRAL_WAYLAND_EXTENSIONS_H
19 
20 #include "application.h"
21 
22 #include <functional>
23 #include <memory>
24 #include <string>
25 #include <optional>
26 #include <set>
27 
28 struct wl_display;
29 struct wl_client;
30 struct wl_resource;
31 
32 namespace mir { class Server; }
33 
34 namespace miral
35 {
36 class Window;
37 
38 /// Enable configuration of the Wayland extensions enabled at runtime.
39 ///
40 /// This adds the command line options '--wayland-extensions', '--add-wayland-extensions', '--drop-wayland-extensions'
41 /// and the corresponding MIR_SERVER_* environment variables and config file options.
42 /// * The server can add support for additional extensions
43 /// * The server can specify the configuration defaults
44 /// * Mir's option handling allows the defaults to be overridden
45 /// \remark Since MirAL 2.4
47 {
48 public:
49  /// Default to enabling the extensions recommended by Mir
51 
52  void operator()(mir::Server& server) const;
53 
57 
58  /// All Wayland extensions supported.
59  /// This includes both the supported() provided by Mir and any extensions
60  /// that have been added using add_extension().
61  /// \remark Since MirAL 3.0
62  auto all_supported() const -> std::set<std::string>;
63 
64  /// Context information useful for implementing Wayland extensions
65  /// \remark Since MirAL 2.5
66  class Context
67  {
68  public:
69  virtual auto display() const -> wl_display* = 0;
70  virtual void run_on_wayland_mainloop(std::function<void()>&& work) const = 0;
71 
72  protected:
73  Context() = default;
74  virtual ~Context() = default;
75  Context(Context const&) = delete;
76  Context& operator=(Context const&) = delete;
77  };
78 
79  /// A Builder creates and registers an extension protocol.
80  /// \remark Since MirAL 2.5
81  struct Builder
82  {
83  /// Name of the protocol extension's Wayland global
84  std::string name;
85 
86  /// Functor that creates and registers an extension protocol
87  /// \param context giving access to:
88  /// * the wl_display (so that, for example, the extension can be registered); and,
89  /// * allowing server initiated code to be executed on the Wayland mainloop.
90  /// \return a shared pointer to the implementation. (Mir will manage the lifetime)
91  std::function<std::shared_ptr<void>(Context const* context)> build;
92  };
93 
94  /// Information that can be used to determine if to enable a conditionally enabled extension
95  /// \remark Since MirAL 3.4
96  class EnableInfo
97  {
98  public:
99  /// The application that is being given access to this extension
100  auto app() const -> Application const&;
101  /// The name of the extension/global, always the same as given to conditionally_enable()
102  auto name() const -> const char*;
103  /// If the user has enabled or disabled this extension one of the wayland extension Mir options
104  auto user_preference() const -> std::optional<bool>;
105 
106  private:
107  friend WaylandExtensions;
108  EnableInfo(Application const& app, const char* name, std::optional<bool> user_preference);
109  struct Self;
110  std::unique_ptr<Self> const self;
111  };
112 
113  /// \remark Since MirAL 2.5
114  using Filter = std::function<bool(Application const& app, char const* protocol)>;
115 
116  /// \remark Since MirAL 3.4
117  using EnableCallback = std::function<bool(EnableInfo const& info)>;
118 
119  /// Set an extension filter callback to control the extensions available to specific clients. Deprecated in favor of
120  /// conditionally_enable(), and not be used in conjunction with conditionally_enable().
121  /// \remark Since MirAL 2.5
122  /// \deprecated In MirAL 3.4, use conditionally_enable() instead
123  [[deprecated("use conditionally_enable() instead")]]
124  void set_filter(Filter const& extension_filter);
125 
126  /**
127  * Supported wayland extensions that are not enabled by default.
128  * These can be passed into WaylandExtensions::enable() to turn them on.
129  * @{ */
130 
131  /// Enables shell components such as panels, notifications and lock screens.
132  /// It is recommended to use this in conjunction with set_filter() as malicious
133  /// clients could potentially use this protocol to steal input focus or
134  /// otherwise bother the user.
135  /// \remark Since MirAL 2.6
136  static char const* const zwlr_layer_shell_v1;
137 
138  /// Allows clients to retrieve additional information about outputs
139  /// \remark Since MirAL 2.6
140  static char const* const zxdg_output_manager_v1;
141 
142  /// Allows a client to get information and gain control over all toplevels of all clients
143  /// Useful for taskbars and app switchers
144  /// Could allow a client to extract information about other programs the user is running
145  /// \remark Since MirAL 3.1
146  static char const* const zwlr_foreign_toplevel_manager_v1;
147 
148  /// Allows clients to act as a virtual keyboard, useful for on-screen keyboards.
149  /// Clients are not required to display anything to send keyboard events using this extension,
150  /// so malicious clients could use it to take actions without user input.
151  /// \remark Since MirAL 3.4
152  static char const* const zwp_virtual_keyboard_manager_v1;
153 
154  /// Allows clients (such as on-screen keyboards) to intercept physical key events and act as a
155  /// source of text input for other clients. Input methods are not required to display anything
156  /// to use this extension, so malicious clients could use it to intercept keys events or take
157  /// actions without user input.
158  /// \remark Since MirAL 3.4
159  static char const* const zwp_input_method_manager_v2;
160 
161  /// Allows clients to take screenshots and record the screen. Only enable for clients that are
162  /// trusted to view all displayed content, including windows of other apps.
163  /// \remark Since MirAL 3.5
164  static char const* const zwlr_screencopy_manager_v1;
165 
166  /// Allows clients to act as a virtual pointer, useful for remote control and automation.
167  /// Clients are not required to display anything to send pointer events using this extension,
168  /// so malicious clients could use it to take actions without user input.
169  /// \remark Since MirAL 3.6
170  static char const* const zwlr_virtual_pointer_manager_v1;
171 
172  /**
173  * \remark Since MirAL 3.3
174  * \deprecated Use the *_manager_* versions instead
175  * @{ */
176  [[deprecated("use zwp_virtual_keyboard_manager_v1 instead")]]
177  static char const* const zwp_virtual_keyboard_v1;
178  [[deprecated("use zwp_input_method_manager_v2 instead")]]
179  static char const* const zwp_input_method_v2;
180  /** @} */
181  /** @} */
182 
183  /// Add a bespoke Wayland extension both to "supported" and "enabled by default".
184  /// \remark Since MirAL 2.5
185  void add_extension(Builder const& builder);
186 
187  /// Add a bespoke Wayland extension both to "supported" but not "enabled by default".
188  /// \remark Since MirAL 2.5
190 
191  /// The set of Wayland extensions that Mir recommends.
192  /// Also the set that is enabled by default upon construction of a WaylandExtensions object.
193  /// \remark Since MirAL 2.6
194  static auto recommended() -> std::set<std::string>;
195 
196  /// The set of Wayland extensions that core Mir supports.
197  /// Does not include bespoke extensions
198  /// A superset of recommended()
199  /// \remark Since MirAL 2.6
200  static auto supported() -> std::set<std::string>;
201 
202  /// Enable a Wayland extension by default. The user can still disable it with the drop-wayland-extensions or
203  /// wayland-extensions options. The extension can be forced to be enabled regardless of user options with
204  /// conditionally_enable().
205  /// \remark Since MirAL 2.6
206  auto enable(std::string name) -> WaylandExtensions&;
207 
208  /// Disable a Wayland extension by default. The user can still enable it with the add-wayland-extensions or
209  /// wayland-extensions options. The extension can be forced to be disabled regardless of user options with
210  /// conditionally_enable().
211  /// \remark Since MirAL 2.6
212  auto disable(std::string name) -> WaylandExtensions&;
213 
214  /// Enable a Wayland extension only when the callback returns true. The callback can use info.user_preference()
215  /// to respect the extension options the user provided, it is not required. Unlike enable() and disable(),
216  /// conditionally_enable() can override the user options.
217  /// \remark Since MirAL 3.4
218  auto conditionally_enable(std::string name, EnableCallback const& callback) -> WaylandExtensions&;
219 
220 private:
221  struct Self;
222  std::shared_ptr<Self> self;
223 };
224 
225 /// Get the MirAL application for a wl_client.
226 /// \return The application (null if no application is found)
227 /// \remark Since MirAL 2.5
228 auto application_for(wl_client* client) -> Application;
229 
230 /// Get the MirAL application for a wl_resource.
231 /// \return The application (null if no application is found)
232 /// \remark Since MirAL 2.5
233 auto application_for(wl_resource* resource) -> Application;
234 
235 /// Get the MirAL Window for a Wayland Surface, XdgSurface, etc.
236 /// Note that there may not be a corresponding miral::Window (e.g. the
237 /// surface is created and assigned properties before 'commit' creates the
238 /// miral::Window).
239 ///
240 /// \return The window (null if no window is found)
241 /// \remark Since MirAL 2.5
242 auto window_for(wl_resource* surface) -> Window;
243 }
244 
245 #endif //MIRAL_WAYLAND_EXTENSIONS_H

Copyright © 2012-2022 Canonical Ltd.
Generated on Fri Aug 26 13:27:37 UTC 2022
This documentation is licensed under the GPL version 2 or 3.