Skip to content

Commit 29e6746

Browse files
AdrianVovkAdrianVovk
committed
Introduce save/restore portal
1 parent b949162 commit 29e6746

File tree

9 files changed

+720
-0
lines changed

9 files changed

+720
-0
lines changed

‎data/meson.build‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ portal_sources = files(
2929
'org.freedesktop.portal.Realtime.xml',
3030
'org.freedesktop.portal.RemoteDesktop.xml',
3131
'org.freedesktop.portal.Request.xml',
32+
'org.freedesktop.portal.SaveRestore.xml',
3233
'org.freedesktop.portal.ScreenCast.xml',
3334
'org.freedesktop.portal.Screenshot.xml',
3435
'org.freedesktop.portal.Secret.xml',
@@ -61,6 +62,7 @@ portal_impl_sources = files(
6162
'org.freedesktop.impl.portal.Print.xml',
6263
'org.freedesktop.impl.portal.RemoteDesktop.xml',
6364
'org.freedesktop.impl.portal.Request.xml',
65+
'org.freedesktop.impl.portal.SaveRestore.xml',
6466
'org.freedesktop.impl.portal.ScreenCast.xml',
6567
'org.freedesktop.impl.portal.Screenshot.xml',
6668
'org.freedesktop.impl.portal.Secret.xml',

‎data/org.freedesktop.impl.portal.SaveRestore.xml‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
<?xml version="1.0"?>
2+
<!--
3+
Copyright Red Hat
4+
5+
SPDX-License-Identifier: LGPL-2.1-or-later
6+
7+
This library is free software; you can redistribute it and/or
8+
modify it under the terms of the GNU Lesser General Public
9+
License as published by the Free Software Foundation; either
10+
version 2.1 of the License, or (at your option) any later version.
11+
12+
This library is distributed in the hope that it will be useful,
13+
but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15+
Lesser General Public License for more details.
16+
17+
You should have received a copy of the GNU Lesser General Public
18+
License along with this library. If not, see <http://www.gnu.org/licenses/>.
19+
20+
Author: Adrian Vovk <[email protected]>
21+
-->
22+
23+
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
24+
<!--
25+
org.freedesktop.impl.portal.SaveRestore:
26+
@short_description: Save/restore portal backend interface
27+
28+
The save/restore portal allows the session to coordinate with apps to
29+
implement a session-wide state save/restore feature.
30+
31+
Portal backends that implement this interface must implement at least
32+
version 2 of the :ref:`org.freedesktop.impl.portal.Session` interface.
33+
34+
This documentation describes version 1 of this interface.
35+
-->
36+
<interface name="org.freedesktop.impl.portal.SaveRestore">
37+
<!--
38+
Register:
39+
@session_handle: Object path for the ref:`org.freedesktop.impl.portal.Session` object representing the session being created
40+
@app_id: App id of the application
41+
@options: Vardict with optional further information
42+
@restore: Vardict directing the app how to restore its state. See :ref:`org.freedesktop.portal.SaveRestore.Register`
43+
44+
Registers an app with the save/restore API.
45+
46+
There are currently no supported keys in the @options vardict.
47+
48+
A note about instance IDs: the backend should make sure to incorporate
49+
information about the session (i.e. the name of the session manager and/or
50+
desktop environment) into the process that generates instance IDs. This
51+
allows apps that use instance IDs correctly to automatically support
52+
use-cases where people switch between different session types.
53+
-->
54+
<method name="Register">
55+
<arg type="o" name="session_handle" direction="in"/>
56+
<arg type="s" name="app_id" direction="in"/>
57+
<annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
58+
<arg type="a{sv}" name="options" direction="in"/>
59+
<annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QVariantMap"/>
60+
<arg type="a{sv}" name="restore" direction="out"/>
61+
</method>
62+
63+
<!--
64+
SaveHint:
65+
@session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
66+
67+
The SaveHint signal is sent to an app whenever the system thinks it
68+
would be a good moment for the app to save its state. The system should
69+
not be sending this regularly, but only in situations that might otherwise
70+
lead to data loss. For instance: this signal might be emitted before the
71+
whole system suspends, or before an individual app will be frozen and
72+
removed from the run queue to preserve resources, or before imminent
73+
system power loss.
74+
75+
Apps are expected to respond to this signal by calling
76+
:ref:`org.freedesktop.portal.impl.SaveRestore.SaveHintResponse` within
77+
3 seconds.
78+
-->
79+
<signal name="SaveHint">
80+
<arg type="o" name="session_handle" direction="out"/>
81+
</signal>
82+
83+
<!--
84+
SaveHintResponse:
85+
@session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
86+
87+
Acknowledges that the caller received the :ref:`org.freedesktop.impl.portal.SaveRestore::SaveHint`
88+
signal. This method should be called within 3 seconds of receiving the signal.
89+
-->
90+
<method name="SaveHintResponse">
91+
<arg type="o" name="session_handle" direction="in"/>
92+
</method>
93+
94+
<!--
95+
Quit:
96+
@session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
97+
98+
The Quit signal is sent to an app whenever the system decides to
99+
terminate the app to free up system resources (i.e. memory). The app
100+
should immediately save its state to disk and then exit cleanly, within
101+
3 seconds of receiving this signal. The app may be transparently restarted
102+
by the system at a later date.
103+
-->
104+
<signal name="Quit">
105+
<arg type="o" name="session_handle" direction="out"/>
106+
</signal>
107+
108+
<property name="version" type="u" access="read"/>
109+
</interface>
110+
</node>

‎data/org.freedesktop.portal.SaveRestore.xml‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
<?xml version="1.0"?>
2+
<!--
3+
Copyright Red Hat
4+
5+
SPDX-License-Identifier: LGPL-2.1-or-later
6+
7+
This library is free software; you can redistribute it and/or
8+
modify it under the terms of the GNU Lesser General Public
9+
License as published by the Free Software Foundation; either
10+
version 2.1 of the License, or (at your option) any later version.
11+
12+
This library is distributed in the hope that it will be useful,
13+
but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15+
Lesser General Public License for more details.
16+
17+
You should have received a copy of the GNU Lesser General Public
18+
License along with this library. If not, see <http://www.gnu.org/licenses/>.
19+
20+
Author: Adrian Vovk <[email protected]>
21+
-->
22+
23+
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
24+
<!--
25+
org.freedesktop.portal.SaveRestore:
26+
@short_description: Portal for coordinating app state save and restore
27+
28+
The SaveRestore interface allows the session to coordinate with applications
29+
to implement a session-wide state save/restore feature. Apps that can save
30+
their state to disk should register with this portal. In exchange, the system
31+
will present the user with the option to restore session state after their
32+
session ends (i.e. after a reboot). It is not a portal in the strict sense,
33+
since it does not involve user interaction. Applications are expected to
34+
use this interface indirectly, via integration with their UI toolkit.
35+
36+
This documentation describes version 1 of this interface.
37+
-->
38+
<interface name="org.freedesktop.portal.SaveRestore">
39+
<!--
40+
Register:
41+
@options: Vardict with optional further information
42+
@handle: Object path for the created :ref:`org.freedesktop.portal.Session` object
43+
@restore: Vardict directing the app how to restore its state
44+
45+
Registers this app with the save/restore API. If the user logs out while
46+
the app is registered, the system will remember that this app was running
47+
and relaunch it on next log-in. The app can then register itself again
48+
on next startup to be notified of what state (if any) it should restore.
49+
50+
During a clean shutdown, the app should close the created session using
51+
:ref:`org.freedesktop.portal.Session.Close`. If the app disconnects from
52+
the bus without closing the session first, the system will consider the
53+
shutdown unclean and will report this to the app on its next startup.
54+
55+
Supported keys in the @options vardict include:
56+
57+
* ``session_handle_token`` (``s``)
58+
59+
A string that will be used as the last element of the session handle. Must be a valid
60+
object path element. See the :ref:`org.freedesktop.portal.Session` documentation for
61+
more information about the session handle.
62+
63+
Supported keys in the @restore vardict include:
64+
65+
* ``instance-id`` (``s``)
66+
67+
A short alphanumeric string that identifies different instances of a
68+
multi-instance app. This allows multi-instance apps to keep the state
69+
of each instance separated. Single-instance apps should use this as
70+
well, because the system will return different identifiers when running
71+
different graphical sessions. For instance: if a user switches between
72+
GNOME and KDE regularly, even single-instance apps will need to save
73+
and load their state under different instance IDs.
74+
75+
* ``restore-reason`` (``u``)
76+
77+
Tells the app which state it needs to restore. Supported values:
78+
79+
- ``PRISTINE``: 0. The app should not attempt to restore any state.
80+
81+
- ``LAUNCH``: 1. This is a normal launch, so the app should restore
82+
some state (i.e. previous window size and position, default view on
83+
the home page) but it shouldn't attempt a full state restore. The
84+
exception is apps that have a preference that allows the user to
85+
decide if the app should always save and restore its state: if the
86+
user opts into this behavior, then it's permissible for the app to
87+
treat ``LAUNCH`` as equivalent to ``RESTORE``.
88+
89+
- ``RECOVER``: 2. This is the first launch after the app unexpectedly
90+
disconnected from the bus. The app should try to restore as much
91+
state as it can, but it should be careful to avoid crash loops. Apps
92+
can handle this by prompting users before attempting to restore state,
93+
or by strategically throwing away some state. For instance: a web
94+
browser may choose to restore open tabs but not restore the web
95+
content inside of each tab, instead showing a placeholder page and
96+
prompting the user to reload the tab. To support this feature
97+
properly, apps should periodically save their state while taking care
98+
to avoid unnecessary I/O. For instance: apps can flush their state
99+
to disk every 15 seconds, but only while the app is focused.
100+
101+
- ``RESTORE``: 3. The app should attempt to restore as much state as
102+
possible.
103+
104+
* ``discrard-instance-ids`` (``as``)
105+
106+
A list of instance IDs (as above) that the system is done with and will
107+
no longer return to the app. The app should clean up any state it has
108+
associated with these IDs, and then report completion via
109+
:ref:`org.freedesktop.portal.SaveRestore.DiscardInstanceIdsResponse`.
110+
-->
111+
<method name="Register">
112+
<annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QVariantMap"/>
113+
<arg type="a{sv}" name="options" direction="in"/>
114+
<arg type="o" name="handle" direction="out"/>
115+
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
116+
<arg type="a{sv}" name="restore" direction="out"/>
117+
</method>
118+
119+
<!--
120+
SaveHint:
121+
@session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
122+
123+
The SaveHint signal is sent to an app whenever the system thinks it
124+
would be a good moment for the app to save its state. In response, apps
125+
should immediately save their state and then respond with
126+
:ref:`org.freedesktop.portal.SaveRestore.SaveHintResponse`.
127+
128+
Note that apps should not be using this signal as the only reason to
129+
save their state. This signal will be emitted relatively rarely. Each
130+
app should periodically save its own state at moments where it makes
131+
sense for the app.
132+
-->
133+
<signal name="SaveHint">
134+
<arg type="o" name="session_handle" direction="out"/>
135+
</signal>
136+
137+
<!--
138+
SaveHintResponse:
139+
@session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
140+
141+
Acknowledges that the caller received the :ref:`org.freedesktop.portal.SaveRestore::SaveHint`
142+
signal. This method should be called within 3 seconds of receiving the signal.
143+
-->
144+
<method name="SaveHintResponse">
145+
<arg type="o" name="session_handle" direction="in"/>
146+
</method>
147+
148+
<!--
149+
Quit:
150+
@session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
151+
152+
The Quit signal is sent to an app whenever the system decides to
153+
terminate the app to free up system resources (i.e. memory). The app
154+
should immediately save its state to disk and then exit cleanly, within
155+
3 seconds of receiving this signal. The app may be transparently restarted
156+
by the system at a later date.
157+
-->
158+
<signal name="Quit">
159+
<arg type="o" name="session_handle" direction="out"/>
160+
</signal>
161+
162+
<property name="version" type="u" access="read"/>
163+
</interface>
164+
</node>

‎doc/api-reference.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ All apps have access to the portals below:
5959
doc-org.freedesktop.portal.Realtime.rst
6060
doc-org.freedesktop.portal.RemoteDesktop.rst
6161
doc-org.freedesktop.portal.Request.rst
62+
doc-org.freedesktop.portal.SaveRestore.rst
6263
doc-org.freedesktop.portal.ScreenCast.rst
6364
doc-org.freedesktop.portal.Screenshot.rst
6465
doc-org.freedesktop.portal.Secret.rst

‎doc/impl-dbus-interfaces.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ accessible to sandboxed applications.
2525
doc-org.freedesktop.impl.portal.Print.rst
2626
doc-org.freedesktop.impl.portal.RemoteDesktop.rst
2727
doc-org.freedesktop.impl.portal.Request.rst
28+
doc-org.freedesktop.impl.portal.SaveRestore.rst
2829
doc-org.freedesktop.impl.portal.ScreenCast.rst
2930
doc-org.freedesktop.impl.portal.Screenshot.rst
3031
doc-org.freedesktop.impl.portal.Secret.rst

‎src/meson.build‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ xdg_desktop_portal_sources = files(
104104
'realtime.c',
105105
'registry.c',
106106
'remote-desktop.c',
107+
'save-restore.c',
107108
'screen-cast.c',
108109
'screenshot.c',
109110
'secret.c',

0 commit comments

Comments
 (0)