Skip to content
Commit ab515cda authored by Georges Basile Stavracas Neto's avatar Georges Basile Stavracas Neto Committed by Phaedrus Leeds
Browse files

Introduce screencast session restore

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.
parent 6064be24
Loading
Loading
Loading
Loading
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment