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 <zm...@osg.samsung.com> Signed-off-by: Jonas Ã…dahl <jad...@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 <zm...@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 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel