Skip to content

Commit

Permalink
Introduce screencast session restore
Browse files Browse the repository at this point in the history 
First implementation of a mechanism to restore previously configured
screencast sessions.

There are 2 important workflows happening in parallel: acquiring a
token, and using it.

 # Acquiring a restore token

 1. Applications that want to be able to restore screencast streams
    pass the `persist_mode` option to the `SelectSources()` method.
    Persist modes are explained below.

 2. `xdg-desktop-portal` pass the `persist_mode` option to the portal
    implementation.

 3. The portal implementation queries the user (usually via a dialog)
    which monitor or window to share, and whether they allow it to be
    restored.

 4. If the screencast session should be restored, the portal implementation
    hands `xdg-desktop-portal` the implementation-specific data to be
    restored. This is passed via the `restore_data` option, at the
    response of the `Start()` call.

 5. `xdg-desktop-portal` stores this data somewhere with an unique
    identifier that I called `restore_token`.

 6. `xdg-desktop-portal` pass `restore_token` to the application.

The application then should save this restore token however it thinks
it's appropriate.

 # Using the restore token

Now that the application has a restore token, it can restore a previous
stream. This is how it happens:

 1. Applications that want to restore a screencast stream pass the
    `restore_token` option to the `SelectSources()` method.

 2. `xdg-desktop-portal` receives the token, and performs a lookup
    for the implementation-specific data associated with this token.

 3. `xdg-desktop-portal` consumes this token and removes the permission.

 4. `xdg-desktop-portal` sends this restore data to the portal
    implementation as the `restore_data` option to the `SelectSources()`
    method.

 5. The portal implementation uses this restore data to match windows
    and monitors without presenting a dialog. If it fails to match (due
    to, for example, any monitors or windows not being available), it
    fallbacks to presenting the dialog.

Tokens can only be used once to restore streams. The permissions they
hold are revoked after use. That's what xdg-desktop-portal does at
step 2.3. Applications must not assume anything about tokens. Portal
implementations never have access to the restore tokens.

 # Persistence modes

There are two modes of persistence:

 1. Transient: the restore token is valid as long as the application
    is alive. It's stored in memory and revoked when the application
    closes its D-Bus connection.

 2. Persistent: the restore token is stored in disk, using the
    permissions store, and is valid until the user manually revokes
    it.

Extra care is taken to ensure that restore tokens aren't predictable.

For the multi-stream case, add a new 'id' property to the list of
stream properties. This allows applications to uniquely identify
each stream.
  • Loading branch information
@GeorgesStavracas
GeorgesStavracas committed Nov 18, 2021
1 parent a1d0188 commit 32dc3a6
Show file tree
Hide file tree
Showing 5 changed files with 573 additions and 5 deletions.
84 changes: 84 additions & 0 deletions data/org.freedesktop.impl.portal.ScreenCast.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@
@short_description: Screen cast portal backend interface
The Screen cast portal allows to create screen cast sessions.
This documentation describes version 4 of this interface.
-->
<interface name="org.freedesktop.impl.portal.ScreenCast">
<!--
Expand Down Expand Up @@ -81,6 +83,47 @@
Whether to allow selecting multiple sources. Default is no.
</para></listitem>
</varlistentry>
<varlistentry>
<term>restore_data (suv)</term>
<listitem><para>
The data to restore from a previous session.
</para>
<para>
If the stored session cannot be restored, this value is ignored
and the user will be prompted normally. This may happen when, for
example, the session contains a monitor or a window that is not
available anymore, or when the stored permissions are withdrawn.
</para>
<para>
The restore data is composed of the vendor name (e.g. "GNOME" or
"KDE"), the version of the implementation-specific private data,
and the implementation-specific private data itself.
</para>
<para>
This option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term>persist_mode u</term>
<listitem><para>
How this session should persist. Default is 0. Accepted values are:
</para>
<para>
<simplelist>
<member>0: Do not persist (default)</member>
<member>1: Permissions persist as long as the application is running</member>
<member>2: Permissions persist until explicitly revoked</member>
</simplelist>
</para>
<para>
If the permission for the session to persist is granted, a restore token will
be returned via the #org.freedesktop.portal.Request::Response signal of the
#org.freedesktop.portal.Screencast.SelectSources method.
</para>
<para>
This option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
</variablelist>
For available source types, see the AvailableSourceTypes property.
Expand Down Expand Up @@ -123,6 +166,47 @@
'multiple' was set to 'true' as part of the SelectSources method.
</para></listitem>
</varlistentry>
<varlistentry>
<term>persist_mode u</term>
<listitem><para>
Portal implementations can optionally offer ways to "reduce" the
persist mode, for example by explicitly asking the user. See the
'persist_mode' option of SelectSources for a list of possible
values.
If no persist mode is returned by the Start request, it is assumed
to be the same persist mode received during SelectSources.
This option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term>restore_data (suv)</term>
<listitem><para>
The data to be restored. This is the data that a portal
implementation sent in reaction to transient or persistent
modes.
</para>
<para>
This data will be stored in the permission store if the effective
persist mode is 2, and may be passed in the future as part of the
SelectSources() method call. The portal backend should store enough
information in 'restore_data' to be able to restore the session
later. The portal backend can deal with unavailable sources however
they see fit.
</para>
<para>
Data generated by a portal implementation must be consumable by
the same portal implementation, but not necessarily by others.
Thus, it is important to properly handle 'restore_data' not being
in a valid format. This may happen when, e.g., the user switched
to another desktop environment, or is using a different portal
implementation.
</para>
<para>
This response option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
</variablelist>
Stream properties include:
Expand Down
59 changes: 58 additions & 1 deletion data/org.freedesktop.portal.ScreenCast.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
The Screen cast portal allows to create screen cast sessions.
This documentation describes version 1 of this interface.
This documentation describes version 4 of this interface.
-->
<interface name="org.freedesktop.portal.ScreenCast">
<!--
Expand Down Expand Up @@ -119,6 +119,44 @@
This option was added in version 2 of this interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term>restore_token s</term>
<listitem><para>
The token to restore a previous session.
If the stored session cannot be restored, this value is ignored
and the user will be prompted normally. This may happen when, for
example, the session contains a monitor or a window that is not
available anymore, or when the stored permissions are withdrawn.
The restore token is invalidated after using it once. To restore
the same session again, use the new restore token sent in response
to starting this session.
This option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term>persist_mode u</term>
<listitem><para>
How this session should persist. Default is 0. Accepted values are:
<simplelist>
<member>0: Do not persist (default)</member>
<member>1: Permissions persist as long as the application is running</member>
<member>2: Permissions persist until explicitly revoked</member>
</simplelist>
Remote desktop screen cast sessions cannot persist. The only allowed
persist_mode for remote desktop sessions is 0.
If the permission for the session to persist is granted, a restore token will
be returned via the #org.freedesktop.portal.Request::Response signal of the
#org.freedesktop.portal.Screencast.Start method.
This option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
</variablelist>
For available source types, see the AvailableSourceTypes property.
Expand Down Expand Up @@ -169,10 +207,29 @@
'multiple' was set to 'true' as part of the SelectSources method.
</para></listitem>
</varlistentry>
<varlistentry>
<term>restore_token s</term>
<listitem><para>
The restore token. This token is a single use token that can later
be used to restore a session. See
#org.freedesktop.portal.ScreenCast.SelectSources for details.
This response option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
</variablelist>
Stream properties include:
<variablelist>
<varlistentry>
<term>id s</term>
<listitem><para>
Opaque identifier. Will be unique for this stream and local to this
session. Will persist with future sessions, if they are restored
using a restore token. This property was added in version 4 of this
interface. Optional.
</para></listitem>
</varlistentry>
<varlistentry>
<term>position (ii)</term>
<listitem><para>
Expand Down
Loading

0 comments on commit 32dc3a6

Please sign in to comment.