[PATCH] unstable: add xdg-session-management protocol
Mike Blumenkrantz
zmike at osg.samsung.com
Mon Feb 26 13:58:55 UTC 2018
for a variety of cases it's desirable to have a method for negotiating
the restoration of previously-used states for a client's windows. this
helps for e.g., a compositor/client crashing (definitely not due to
bugs) or a backgrounded client deciding to temporarily destroy its
surfaces in order to conserve resources
this protocol adds a method for managing such negotiation and is loosely
based on the Enlightenment "session recovery" protocol which has been
implemented and functional for roughly two years
some further reading: https://blogs.s-osg.org/recovery-journey-discovery/
Signed-off-by: Mike Blumenkrantz <zmike at osg.samsung.com>
Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
---
Makefile.am | 1 +
unstable/xdg-session-management/README | 4 +
.../xdg-session-management-unstable-v1.xml | 181 +++++++++++++++++++++
3 files changed, 186 insertions(+)
create mode 100644 unstable/xdg-session-management/README
create mode 100644 unstable/xdg-session-management/xdg-session-management-unstable-v1.xml
diff --git a/Makefile.am b/Makefile.am
index 4b9a901..2b75114 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -17,6 +17,7 @@ unstable_protocols = \
unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml \
unstable/xdg-output/xdg-output-unstable-v1.xml \
unstable/input-timestamps/input-timestamps-unstable-v1.xml \
+ unstable/xdg-session-management/xdg-session-management-unstable-v1.xml \
$(NULL)
stable_protocols = \
diff --git a/unstable/xdg-session-management/README b/unstable/xdg-session-management/README
new file mode 100644
index 0000000..7bff401
--- /dev/null
+++ b/unstable/xdg-session-management/README
@@ -0,0 +1,4 @@
+xdg session management protocol
+
+Maintainers:
+Mike Blumenkrantz <zmike at osg.samsung.com>
diff --git a/unstable/xdg-session-management/xdg-session-management-unstable-v1.xml b/unstable/xdg-session-management/xdg-session-management-unstable-v1.xml
new file mode 100644
index 0000000..0c36c16
--- /dev/null
+++ b/unstable/xdg-session-management/xdg-session-management-unstable-v1.xml
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="session management">
+ <copyright>
+ Copyright 2018 Mike Blumenkrantz
+ Copyright 2018 Samsung Electronics Co., Ltd
+ Copyright 2018 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+ <description summary="Protocol for managing application sessions">
+ Warning! The protocol described in this file is experimental and backward
+ incompatible changes may be made. Backward compatible changes may be added
+ together with the corresponding interface version bump. Backward
+ incompatible changes are done by bumping the version number in the protocol
+ and interface names and resetting the interface version. Once the protocol
+ is to be declared stable, the 'z' prefix and the version number in the
+ protocol and interface names are removed and the interface version number is
+ reset.
+ </description>
+ <interface name="zxdg_session_manager_v1" version="1">
+ <description summary="manage sessions for applications">
+ The xdg_session_manager interface defines base requests for creating and
+ managing a session for an application. Sessions persist across application
+ and compositor restarts unless explicitly destroyed. A session is created
+ for the purpose of maintaining an application's xdg_toplevel surfaces
+ across compositor or application restarts. The compositor should remember
+ as many states as possible for surfaces in a given session, but there is
+ no requirement for which states must be remembered.
+ </description>
+ <request name="destroy" type="destructor">
+ <description summary="Destroy this object">
+ This has no effect other than to destroy the xdg_session_manager object.
+ </description>
+ </request>
+ <request name="get_session">
+ <description summary="create or restore a session">
+ Create a session object corresponding to the given session
+ identifier string. While the session object exists, the session is
+ considered to be "in use".
+
+ It is a client error if the given identifier string represents a session
+ which is already in use.
+
+ NULL is passed to initiate a new session. If an id is passed which does
+ not represent a valid session, the compositor treats it as if NULL had
+ been passed.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_session_v1"/>
+ <arg name="session" type="string" summary="the session identifier string"
+ allow-null="true"/>
+ </request>
+ </interface>
+ <interface name="zxdg_session_v1" version="1">
+ <description summary="A session for an application">
+ A xdg_session object represents a session for an application. While the
+ object exists, all surfaces which have been added to the session will
+ have states stored by the compositor which can be reapplied at a later
+ time. Two sessions cannot exist for the same identifier string.
+
+ States for surfaces added to a session are automatically updated by the
+ compositor when they are changed.
+
+ Surfaces which have been added to a session are automatically removed from
+ the session if xdg_toplevel.destroy is called for the surface.
+ </description>
+ <enum name="error">
+ <entry name="in_use" summary="a requested session is already in use"
+ value="1"/>
+ <entry name="invalid_restore"
+ summary="restore cannot be performed after initial toplevel commit"
+ value="2"/>
+ </enum>
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the session">
+ Destroy a session object, preserving the current state but not continuing
+ to make further updates if state changes occur.
+ </description>
+ </request>
+ <request name="remove" type="destructor">
+ <description summary="Remove the session">
+ Remove a session from the compositor's storage, destroying
+ all xdg_session objects and all session data recursively.
+ </description>
+ </request>
+ <request name="add_surface">
+ <description summary="add a new surface to the session">
+ Attempt to add a given surface to the session. If successful,
+ a zxdg_surface_session_v1.surface_id event is emitted with a
+ session-unique identifier which can be used to restore states of the
+ toplevel surface.
+
+ Multiple requests for the same surface will always return the same
+ string identifier.
+
+ The surface will be added to the session at the next wl_surface.commit.
+ </description>
+ <arg name="surface" type="object" interface="xdg_toplevel"/>
+ <arg name="id" type="new_id" interface="zxdg_surface_session_v1"/>
+ </request>
+ <request name="restore_surface">
+ <description summary="restore a surface state">
+ Inform the compositor that the next configured state should
+ be the same as the state which was stored by the compositor during the
+ given surface's previous session.
+
+ This request must be called prior to the first commit for an
+ xdg_toplevel surface.
+
+ See the zxdg_surface_session_v1.surface_restored event for further
+ details.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_surface_session_v1"/>
+ <arg name="surface" type="object" interface="xdg_toplevel"/>
+ <arg name="surface_id" type="string"
+ summary="the identifier for the surface"/>
+ </request>
+ <request name="remove_surface">
+ <description summary="remove a surface from the session">
+ Remove a specified surface from the session and render any corresponding
+ xdg_surface_session object inert.
+
+ Passing an unknown surface identifier has no effect.
+ </description>
+ <arg name="surface_id" type="string"/>
+ </request>
+ <event name="created">
+ <description summary="newly-created session id">
+ Emitted immediately after creating a new session object. This id can be
+ used to restore previous sessions.
+ </description>
+ <arg name="id" type="string"/>
+ </event>
+ <event name="restored">
+ <description
+ summary="the session has been restored from a previous state"/>
+ </event>
+ </interface>
+ <interface name="zxdg_surface_session_v1" version="1">
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the object">
+ Destroy the object.
+ </description>
+ </request>
+ <event name="surface_restored">
+ <description summary="a surface's session has been restored">
+ surface_restored is emitted prior to the first xdg_surface.configure for
+ a surface. It will only be emitted after zxdg_session_v1.restore_surface
+ and wl_surface.commit have been called for that surface, and it
+ indicates that the surface's session is being restored with this
+ configure event.
+ </description>
+ <arg name="surface" type="object" interface="xdg_toplevel"/>
+ </event>
+ <event name="surface_id">
+ <description summary="a surface has been added to the session">
+ surface_id is emitted after the wl_surface.commit of a surface which has
+ been passed to add_surface. The id is an identifier which can be passed
+ to restore_surface to restore the state of that surface.
+ </description>
+ <arg name="surface" type="object" interface="xdg_toplevel"/>
+ <arg name="id" type="string"/>
+ </event>
+ </interface>
+</protocol>
--
2.14.3
More information about the wayland-devel
mailing list