Mir
wayland_extensions.h
Go to the documentation of this file.
1/*
2 * Copyright © 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
28struct wl_display;
29struct wl_client;
30struct wl_resource;
31
32namespace mir { class Server; }
33
34namespace miral
35{
36class 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{
48public:
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
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
220private:
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
228auto 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
233auto 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
242auto window_for(wl_resource* surface) -> Window;
243}
244
245#endif //MIRAL_WAYLAND_EXTENSIONS_H
Context information useful for implementing Wayland extensions.
Definition: wayland_extensions.h:67
Context & operator=(Context const &)=delete
virtual void run_on_wayland_mainloop(std::function< void()> &&work) const =0
virtual auto display() const -> wl_display *=0
Context(Context const &)=delete
Information that can be used to determine if to enable a conditionally enabled extension.
Definition: wayland_extensions.h:97
auto app() const -> Application const &
The application that is being given access to this extension.
auto name() const -> const char *
The name of the extension/global, always the same as given to conditionally_enable()
auto user_preference() const -> std::optional< bool >
If the user has enabled or disabled this extension one of the wayland extension Mir options.
Enable configuration of the Wayland extensions enabled at runtime.
Definition: wayland_extensions.h:47
static char const *const zwlr_layer_shell_v1
Supported wayland extensions that are not enabled by default.
Definition: wayland_extensions.h:136
static auto supported() -> std::set< std::string >
The set of Wayland extensions that core Mir supports. Does not include bespoke extensions A superset ...
void add_extension_disabled_by_default(Builder const &builder)
Add a bespoke Wayland extension both to "supported" but not "enabled by default".
static char const *const zwp_virtual_keyboard_manager_v1
Allows clients to act as a virtual keyboard, useful for on-screen keyboards. Clients are not required...
Definition: wayland_extensions.h:152
static char const *const zwp_input_method_manager_v2
Allows clients (such as on-screen keyboards) to intercept physical key events and act as a source of ...
Definition: wayland_extensions.h:159
void add_extension(Builder const &builder)
Add a bespoke Wayland extension both to "supported" and "enabled by default".
static char const *const zwlr_virtual_pointer_manager_v1
Allows clients to act as a virtual pointer, useful for remote control and automation....
Definition: wayland_extensions.h:170
static auto recommended() -> std::set< std::string >
The set of Wayland extensions that Mir recommends. Also the set that is enabled by default upon const...
static char const *const zwp_input_method_v2
Definition: wayland_extensions.h:179
static char const *const zwp_virtual_keyboard_v1
Definition: wayland_extensions.h:177
auto operator=(WaylandExtensions const &) -> WaylandExtensions &
WaylandExtensions(WaylandExtensions const &)
static char const *const zxdg_output_manager_v1
Allows clients to retrieve additional information about outputs.
Definition: wayland_extensions.h:140
void operator()(mir::Server &server) const
auto enable(std::string name) -> WaylandExtensions &
Enable a Wayland extension by default. The user can still disable it with the drop-wayland-extensions...
auto disable(std::string name) -> WaylandExtensions &
Disable a Wayland extension by default. The user can still enable it with the add-wayland-extensions ...
auto all_supported() const -> std::set< std::string >
All Wayland extensions supported. This includes both the supported() provided by Mir and any extensio...
static char const *const zwlr_foreign_toplevel_manager_v1
Allows a client to get information and gain control over all toplevels of all clients Useful for task...
Definition: wayland_extensions.h:146
static char const *const zwlr_screencopy_manager_v1
Allows clients to take screenshots and record the screen. Only enable for clients that are trusted to...
Definition: wayland_extensions.h:164
void set_filter(Filter const &extension_filter)
Set an extension filter callback to control the extensions available to specific clients....
auto conditionally_enable(std::string name, EnableCallback const &callback) -> WaylandExtensions &
Enable a Wayland extension only when the callback returns true. The callback can use info....
WaylandExtensions()
Default to enabling the extensions recommended by Mir.
Handle class to manage a Mir surface. It may be null (e.g. default initialized)
Definition: window.h:36
Definition: runner.h:27
Mir Abstraction Layer.
Definition: runner.h:35
auto application_for(wl_resource *resource) -> Application
Get the MirAL application for a wl_resource.
auto application_for(wl_client *client) -> Application
Get the MirAL application for a wl_client.
auto window_for(wl_resource *surface) -> Window
Get the MirAL Window for a Wayland Surface, XdgSurface, etc. Note that there may not be a correspondi...
A Builder creates and registers an extension protocol.
Definition: wayland_extensions.h:82
std::function< std::shared_ptr< void >(Context const *context)> build
Functor that creates and registers an extension protocol.
Definition: wayland_extensions.h:91
std::string name
Name of the protocol extension's Wayland global.
Definition: wayland_extensions.h:84

Copyright © 2012-2023 Canonical Ltd.
Generated on Sun Jan 29 22:43:39 UTC 2023
This documentation is licensed under the GPL version 2 or 3.