mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-10-06 16:09:43 +00:00
doc: structure the portal documentation a bit better
This commit is contained in:
Peter Hutterer
Wim Taymans
parent
0261b78870
commit
82e427745d
|
|
@ -26,6 +26,7 @@ additional checks are performed yet.
|
|||
List of Media Session modules:
|
||||
|
||||
- \subpage page_media_session_module_access_flatpak
|
||||
- \subpage page_media_session_module_access_portal
|
||||
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -2,22 +2,23 @@
|
|||
|
||||
This document explains how clients from the portal are handled.
|
||||
|
||||
The portal is a DBus service that exposes a couple of interfaces to
|
||||
The portal is a DBus service that exposes interfaces to
|
||||
request access to the PipeWire daemon to perform a certain set of
|
||||
functions.
|
||||
functions. The PipeWire daemon runs outside the sandbox, the portal is a way
|
||||
for clients inside the sandbox to connect to and use PipeWire.
|
||||
|
||||
The portal makes it possible to use PipeWire without having to expose
|
||||
the local PipeWire socket in the sandboxed application. It is the
|
||||
portal can connects to PipeWire on behalf of the client. The client
|
||||
becomes a portal managed client. PipeWire can detect and enforce
|
||||
The PipeWire socket is not exposed in the sandbox. Instead, The portal
|
||||
connects to PipeWire on behalf of the client, informing PipeWire that this
|
||||
client is a portal-managed client. PipeWire can detect and enforce
|
||||
extra permission checks on the portal managed clients.
|
||||
|
||||
Once such portal is the Camera portal that provides a PipeWire session
|
||||
to stream video from a camera.
|
||||
Once such portal is the [Camera
|
||||
portal](https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-org.freedesktop.portal.Camera)
|
||||
that provides a PipeWire session to stream video from a camera.
|
||||
|
||||
# Use cases
|
||||
|
||||
## new portal managed clients need device permissions configured
|
||||
### new portal managed clients need device permissions configured
|
||||
|
||||
When a new client is detected, the available objects need to be
|
||||
scanned and permissions configured for each of them.
|
||||
|
|
@ -25,7 +26,7 @@ scanned and permissions configured for each of them.
|
|||
Only the devices belonging to the media_roles given by the
|
||||
portal are considered.
|
||||
|
||||
## new devices need to be made visible to portal managed clients
|
||||
### new devices need to be made visible to portal managed clients
|
||||
|
||||
Newly created objects are made visible to a client when the client
|
||||
is allowed to interact with it.
|
||||
|
|
@ -33,7 +34,7 @@ is allowed to interact with it.
|
|||
Only the devices belonging to the media_roles given by the
|
||||
portal are considered.
|
||||
|
||||
## permissions for a device need to be revoked
|
||||
### permissions for a device need to be revoked
|
||||
|
||||
The session manager listens to changes in the permissions of devices
|
||||
and will remove the client permissions accordingly.
|
||||
|
|
@ -47,35 +48,36 @@ where these permissions can be managed.
|
|||
|
||||
## The portal
|
||||
|
||||
The portal itself will make a connection to the PipeWire daemon to
|
||||
configure the session. It then hands the file descriptor of the PipeWire
|
||||
connection to the client. The client can then use the file descriptor
|
||||
to interface with the PipeWire session.
|
||||
A sandboxed client cannot connect to PipeWire directly. Instead, it connects
|
||||
to the sandbox side of the portal which then connects the PipeWire daemon to
|
||||
configure the session. The portal then hands the file descriptor of the
|
||||
PipeWire connection to the client and the client can use this file descriptor
|
||||
to interface with the PipeWire session directly.
|
||||
|
||||
When the portal connects, it will set the following properties on the
|
||||
client object:
|
||||
|
||||
* "pipewire.access.portal.is_portal" = true when this connection is the
|
||||
portal itself and not a client it is managing.
|
||||
* "pipewire.access.portal.app_id" the application id of the client.
|
||||
* "pipewire.access.portal.media_roles" media roles of the client.
|
||||
Currently "Camera" is defined.
|
||||
- `"pipewire.access.portal.is_portal" = true` for the connection of the
|
||||
portal itself (as opposed to a client managed by the portal).
|
||||
- `"pipewire.access.portal.app_id"` the [application id](https://docs.flatpak.org/en/latest/conventions.html#application-ids) of the client.
|
||||
- `"pipewire.access.portal.media_roles"` media roles of the client.
|
||||
Currently only `"Camera"` is defined.
|
||||
|
||||
Before returning the connection to a client, the portal will configure
|
||||
minimal permissions on the client. No objects are initialy visible. It is
|
||||
the task of the session manager to make the objects in the graph
|
||||
visible, depending on the client media_roles.
|
||||
Before returning the connection to a client, the portal configures
|
||||
minimal permissions on the client. No objects are initially visible. It is
|
||||
the task of the \ref page_session_manager to make the objects in the graph
|
||||
visible, depending on the client's `media_roles` (see also \ref
|
||||
PW_KEY_MEDIA_ROLE).
|
||||
|
||||
## The PipeWire portal module
|
||||
|
||||
\subpage page_module_portal
|
||||
The pipewire daemon uses the \ref page_module_portal to find the PID of the
|
||||
processes that owns the DBus name `org.freedesktop.portal.Desktop`
|
||||
(see the [XDG Desktop Portal](https://github.com/flatpak/xdg-desktop-portal)).
|
||||
|
||||
The pipewire daemon uses the portal module to find the PID of the
|
||||
processes that owns the DBus name "org.freedesktop.portal.Desktop".
|
||||
|
||||
It can then detect clients that connect from this PID and tag them
|
||||
as PW_KEY_ACCESS "portal". It will also set ALL permissions for this
|
||||
client so that it can resume. See also \ref page_module_access.
|
||||
Client connections from this PID are tagged as \ref PW_KEY_ACCESS
|
||||
`"portal"` (see \ref page_module_access). It will also set ALL permissions for
|
||||
this client so that it can resume.
|
||||
|
||||
|
||||
## The client
|
||||
|
|
@ -92,33 +94,14 @@ will have limited permissions.
|
|||
## The session manager
|
||||
|
||||
The session manager listens for new clients to appear. It will use the
|
||||
PW_KEY_ACCESS property to find portal connections.
|
||||
\ref PW_KEY_ACCESS property to find portal connections.
|
||||
|
||||
Based on the media_roles it will enable or disable access to PipeWire
|
||||
Based on the `media_roles` it will enable or disable access to PipeWire
|
||||
objects. It might have to consult a database to decide what is
|
||||
allowed.
|
||||
|
||||
The permission store can be used for this. Usually the portal also
|
||||
implements "org.freedesktop.impl.portal.PermissionStore" for this.
|
||||
|
||||
# Implementation
|
||||
|
||||
## pipewire-media-session
|
||||
|
||||
The example media session has an access-portal module that handles the
|
||||
clients that have a PW_KEY_ACCESS as "portal". Other clients are
|
||||
ignored.
|
||||
|
||||
It currently only handles the camera media_roles and asks the permission
|
||||
store for camera device permissions. It receives an array of app_id
|
||||
and the associated permissions. It enables all camera objects when the
|
||||
camera permissions is given to the app_id of the client.
|
||||
|
||||
For new nodes that appear, it will check if the client is allowed to
|
||||
see them or not and set the permissions on the new object accordingly.
|
||||
|
||||
It watches changes in the permission stored and updates the permissions
|
||||
of the objects of clients accordingly.
|
||||
|
||||
implements support for `org.freedesktop.impl.portal.PermissionStore`,
|
||||
see for example the \ref page_media_session_module_access_portal.
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -40,6 +40,37 @@
|
|||
|
||||
#include "media-session.h"
|
||||
|
||||
/** \page page_media_session_module_access_portal Media Session Module: Access Portal
|
||||
*
|
||||
* The Access Portal module manages media roles for clients
|
||||
* started through a portal (see \ref page_module_portal). Clients must have a
|
||||
* \ref PW_KEY_ACCESS or \ref PW_KEY_CLIENT_ACCESS property value of
|
||||
* `"portal"`, all other clients are ignored. The portal is expected to assign
|
||||
*`"pipewire.access.portal.media_roles"` to this client, these roles are
|
||||
* checked against the
|
||||
* [org.freedesktop.impl.portal.PermissionStore](https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-org.freedesktop.impl.portal.PermissionStore).
|
||||
* Where permitted, the resulting client media role becomes the permitted
|
||||
* set of roles.
|
||||
*
|
||||
* @note Currently only the "Camera" media role is supported.
|
||||
*
|
||||
* The Permission Store entry table used by this module is `"devices"`, the
|
||||
* resource ID is `"camera"`.
|
||||
*
|
||||
* ## Module Properties
|
||||
*
|
||||
* This module requires the following properties on the client object:
|
||||
*
|
||||
* - `"pipewire.access.portal.is_portal"`: set to `"true"` for the portal
|
||||
* client itself, empty or `"false"` otherwise
|
||||
* - `"pipewire.access.portal.app_id"`: the application ID of the client
|
||||
* - `"pipewire.access.portal.media_roles"` the media roles that should be
|
||||
* assigned to this client (if permitted by the PermissionStore).
|
||||
*
|
||||
* The above properties must be set by the portal initiating the client
|
||||
* connection.
|
||||
*
|
||||
*/
|
||||
#define NAME "access-portal"
|
||||
#define SESSION_KEY "access-portal"
|
||||
|
||||
|
|
|
|||
|
|
@ -46,6 +46,37 @@
|
|||
#include "pipewire/private.h"
|
||||
|
||||
/** \page page_module_portal PipeWire Module: Portal
|
||||
*
|
||||
* The `portal` module performs access control management for clients started
|
||||
* inside an XDG portal.
|
||||
*
|
||||
* The module connects to the session DBus and subscribes to
|
||||
* `NameOwnerChanged` signals for the `org.freedesktop.portal.Desktop` name.
|
||||
* The PID of the DBus name owner is the portal.
|
||||
*
|
||||
* A client connection from the portal PID to PipeWire gets assigned a \ref
|
||||
* PW_KEY_ACCESS of `"portal"` and set to permissions ALL - it is the
|
||||
* responsibility of the portal to limit the permissions before passing the
|
||||
* connection on to the client. See \ref page_access for details on
|
||||
* permissions.
|
||||
*
|
||||
* Clients connecting from other PIDs are ignored by this module.
|
||||
*
|
||||
* ## Module Options
|
||||
*
|
||||
* There are no module-specific options.
|
||||
*
|
||||
* ## General options
|
||||
*
|
||||
* There are no general options for this module.
|
||||
*
|
||||
* ## Example configuration
|
||||
*\code{.unparsed}
|
||||
* context.modules = [
|
||||
* { name = libpipewire-portal }
|
||||
* ]
|
||||
*\endcode
|
||||
*
|
||||
*/
|
||||
|
||||
#define NAME "portal"
|
||||
|
|
|
|||
Loading…
Reference in a new issue