Enable configuration of the Wayland extensions enabled at runtime. More...

#include <wayland_extensions.h>

Classes
struct	Builder
	A Builder creates and registers an extension protocol. More...

class	Context
	Context information useful for implementing Wayland extensions. More...

class	EnableInfo
	Information that can be used to determine if to enable a conditionally enabled extension. More...

Public Types
using	Filter = std::function< bool(Application const &app, char const *protocol)>

using	EnableCallback = std::function< bool(EnableInfo const &info)>

Public Member Functions
	WaylandExtensions ()
	Default to enabling the extensions recommended by Mir. More...

void	operator() (mir::Server &server) const

	~WaylandExtensions ()

	WaylandExtensions (WaylandExtensions const &)

auto	operator= (WaylandExtensions const &) -> WaylandExtensions &

auto	all_supported () const -> std::set< std::string >
	All Wayland extensions supported. This includes both the supported() provided by Mir and any extensions that have been added using add_extension(). More...

void	set_filter (Filter const &extension_filter)
	Set an extension filter callback to control the extensions available to specific clients. Deprecated in favor of conditionally_enable(), and not be used in conjunction with conditionally_enable(). The filter may be called multiple times for a each client/extension pair (for example, once each time a client creates or destroys a wl_registry). More...

void	add_extension (Builder const &builder)
	Add a bespoke Wayland extension both to "supported" and "enabled by default". More...

void	add_extension_disabled_by_default (Builder const &builder)
	Add a bespoke Wayland extension both to "supported" but not "enabled by default". More...

auto	enable (std::string name) -> WaylandExtensions &
	Enable a Wayland extension by default. The user can still disable it with the drop-wayland-extensions or wayland-extensions options. The extension can be forced to be enabled regardless of user options with conditionally_enable(). More...

auto	disable (std::string name) -> WaylandExtensions &
	Disable a Wayland extension by default. The user can still enable it with the add-wayland-extensions or wayland-extensions options. The extension can be forced to be disabled regardless of user options with conditionally_enable(). More...

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.user_preference() to respect the extension options the user provided, it is not required. Unlike enable() and disable(), conditionally_enable() can override the user options. The callback may be called multiple times for a each client/extension pair (for example, once each time a client creates or destroys a wl_registry). All client processing will be blocked while the callback is being executed. To minimise the impact on client responsiveness users may want to cache the result of any expensive checks made in the callback. More...

Static Public Member Functions
static auto	recommended () -> std::set< std::string >
	The set of Wayland extensions that Mir recommends. Also the set that is enabled by default upon construction of a WaylandExtensions object. More...

static auto	supported () -> std::set< std::string >
	The set of Wayland extensions that core Mir supports. Does not include bespoke extensions A superset of recommended() More...

Static Public Attributes

static char const *const	zwlr_layer_shell_v1
	Supported wayland extensions that are not enabled by default. More...

static char const *const	zxdg_output_manager_v1
	Allows clients to retrieve additional information about outputs. More...

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 taskbars and app switchers Could allow a client to extract information about other programs the user is running. More...

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 to display anything to send keyboard events using this extension, so malicious clients could use it to take actions without user input. More...

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 text input for other clients. Input methods are not required to display anything to use this extension, so malicious clients could use it to intercept keys events or take actions without user input. More...

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 view all displayed content, including windows of other apps. More...

static char const *const	zwlr_virtual_pointer_manager_v1
	Allows clients to act as a virtual pointer, useful for remote control and automation. Clients are not required to display anything to send pointer events using this extension, so malicious clients could use it to take actions without user input. More...

static char const *const	zwp_virtual_keyboard_v1

static char const *const	zwp_input_method_v2

Detailed Description

Enable configuration of the Wayland extensions enabled at runtime.

This adds the command line options '–wayland-extensions', '–add-wayland-extensions', '–drop-wayland-extensions' and the corresponding MIR_SERVER_* environment variables and config file options.

The server can add support for additional extensions
The server can specify the configuration defaults
Mir's option handling allows the defaults to be overridden
Remarks
Since MirAL 2.4

Member Typedef Documentation

◆ EnableCallback

using miral::WaylandExtensions::EnableCallback = std::function<bool(EnableInfo const& info)>

Remarks: Since MirAL 3.4

◆ Filter

using miral::WaylandExtensions::Filter = std::function<bool(Application const& app, char const* protocol)>

Remarks: Since MirAL 2.5

Constructor & Destructor Documentation

◆ WaylandExtensions() [1/2]

miral::WaylandExtensions::WaylandExtensions ( )

Default to enabling the extensions recommended by Mir.

◆ ~WaylandExtensions()

miral::WaylandExtensions::~WaylandExtensions ( )

◆ WaylandExtensions() [2/2]

miral::WaylandExtensions::WaylandExtensions ( WaylandExtensions const & )

Member Function Documentation

◆ add_extension()

void miral::WaylandExtensions::add_extension ( Builder const & builder )

Add a bespoke Wayland extension both to "supported" and "enabled by default".

Remarks: Since MirAL 2.5

◆ add_extension_disabled_by_default()

void miral::WaylandExtensions::add_extension_disabled_by_default ( Builder const & builder )

Add a bespoke Wayland extension both to "supported" but not "enabled by default".

Remarks: Since MirAL 2.5

◆ all_supported()

auto miral::WaylandExtensions::all_supported ( ) const -> std::set< std::string >

All Wayland extensions supported. This includes both the supported() provided by Mir and any extensions that have been added using add_extension().

Remarks: Since MirAL 3.0

◆ conditionally_enable()

auto miral::WaylandExtensions::conditionally_enable	(	std::string	name,
		EnableCallback const &	callback
	)		-> WaylandExtensions &

Enable a Wayland extension only when the callback returns true. The callback can use info.user_preference() to respect the extension options the user provided, it is not required. Unlike enable() and disable(), conditionally_enable() can override the user options. The callback may be called multiple times for a each client/extension pair (for example, once each time a client creates or destroys a wl_registry). All client processing will be blocked while the callback is being executed. To minimise the impact on client responsiveness users may want to cache the result of any expensive checks made in the callback.

Remarks: Since MirAL 3.4

◆ disable()

auto miral::WaylandExtensions::disable ( std::string name ) -> WaylandExtensions &

Disable a Wayland extension by default. The user can still enable it with the add-wayland-extensions or wayland-extensions options. The extension can be forced to be disabled regardless of user options with conditionally_enable().

Remarks: Since MirAL 2.6

◆ enable()

auto miral::WaylandExtensions::enable ( std::string name ) -> WaylandExtensions &

Enable a Wayland extension by default. The user can still disable it with the drop-wayland-extensions or wayland-extensions options. The extension can be forced to be enabled regardless of user options with conditionally_enable().

Remarks: Since MirAL 2.6

◆ operator()()

void miral::WaylandExtensions::operator() ( mir::Server & server ) const

◆ operator=()

auto miral::WaylandExtensions::operator= ( WaylandExtensions const & ) -> WaylandExtensions &

◆ recommended()

static auto miral::WaylandExtensions::recommended ( ) -> std::set< std::string >

static

The set of Wayland extensions that Mir recommends. Also the set that is enabled by default upon construction of a WaylandExtensions object.

Remarks: Since MirAL 2.6

◆ set_filter()

void miral::WaylandExtensions::set_filter ( Filter const & extension_filter )

Set an extension filter callback to control the extensions available to specific clients. Deprecated in favor of conditionally_enable(), and not be used in conjunction with conditionally_enable(). The filter may be called multiple times for a each client/extension pair (for example, once each time a client creates or destroys a wl_registry).

Remarks: Since MirAL 2.5

Deprecated:: In MirAL 3.4, use conditionally_enable() instead

◆ supported()

static auto miral::WaylandExtensions::supported ( ) -> std::set< std::string >

static

The set of Wayland extensions that core Mir supports. Does not include bespoke extensions A superset of recommended()

Remarks: Since MirAL 2.6

Member Data Documentation

◆ zwlr_foreign_toplevel_manager_v1

char const* const miral::WaylandExtensions::zwlr_foreign_toplevel_manager_v1

static

Allows a client to get information and gain control over all toplevels of all clients Useful for taskbars and app switchers Could allow a client to extract information about other programs the user is running.

Remarks: Since MirAL 3.1

◆ zwlr_layer_shell_v1

char const* const miral::WaylandExtensions::zwlr_layer_shell_v1

static

Supported wayland extensions that are not enabled by default.

These can be passed into WaylandExtensions::enable() to turn them on. Enables shell components such as panels, notifications and lock screens. It is recommended to use this in conjunction with set_filter() as malicious clients could potentially use this protocol to steal input focus or otherwise bother the user.

Remarks: Since MirAL 2.6

◆ zwlr_screencopy_manager_v1

char const* const miral::WaylandExtensions::zwlr_screencopy_manager_v1

static

Allows clients to take screenshots and record the screen. Only enable for clients that are trusted to view all displayed content, including windows of other apps.

Remarks: Since MirAL 3.5

◆ zwlr_virtual_pointer_manager_v1

char const* const miral::WaylandExtensions::zwlr_virtual_pointer_manager_v1

static

Allows clients to act as a virtual pointer, useful for remote control and automation. Clients are not required to display anything to send pointer events using this extension, so malicious clients could use it to take actions without user input.

Remarks: Since MirAL 3.6

◆ zwp_input_method_manager_v2

char const* const miral::WaylandExtensions::zwp_input_method_manager_v2

static

Allows clients (such as on-screen keyboards) to intercept physical key events and act as a source of text input for other clients. Input methods are not required to display anything to use this extension, so malicious clients could use it to intercept keys events or take actions without user input.

Remarks: Since MirAL 3.4

◆ zwp_input_method_v2

char const* const miral::WaylandExtensions::zwp_input_method_v2

static

◆ zwp_virtual_keyboard_manager_v1

char const* const miral::WaylandExtensions::zwp_virtual_keyboard_manager_v1

static

Allows clients to act as a virtual keyboard, useful for on-screen keyboards. Clients are not required to display anything to send keyboard events using this extension, so malicious clients could use it to take actions without user input.

Remarks: Since MirAL 3.4

◆ zwp_virtual_keyboard_v1

char const* const miral::WaylandExtensions::zwp_virtual_keyboard_v1

static

Remarks: Since MirAL 3.3

Deprecated:: Use the *_manager_* versions instead

◆ zxdg_output_manager_v1

char const* const miral::WaylandExtensions::zxdg_output_manager_v1

static

Allows clients to retrieve additional information about outputs.

Remarks: Since MirAL 2.6

The documentation for this class was generated from the following file:

include/miral/miral/wayland_extensions.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ EnableCallback

◆ Filter

Constructor & Destructor Documentation

◆ WaylandExtensions() [1/2]

◆ ~WaylandExtensions()

◆ WaylandExtensions() [2/2]

Member Function Documentation

◆ add_extension()

◆ add_extension_disabled_by_default()

◆ all_supported()

◆ conditionally_enable()

◆ disable()

◆ enable()

◆ operator()()

◆ operator=()

◆ recommended()

◆ set_filter()

◆ supported()

Member Data Documentation

◆ zwlr_foreign_toplevel_manager_v1

◆ zwlr_layer_shell_v1

◆ zwlr_screencopy_manager_v1

◆ zwlr_virtual_pointer_manager_v1

◆ zwp_input_method_manager_v2

◆ zwp_input_method_v2

◆ zwp_virtual_keyboard_manager_v1

◆ zwp_virtual_keyboard_v1

◆ zxdg_output_manager_v1