[PATCH wayland-protocols v2] Introduce xdg-foreign protocol
Carsten Haitzler (The Rasterman)
raster at rasterman.com
Fri Aug 5 14:21:11 UTC 2016
On Fri, 5 Aug 2016 23:18:19 +0900 Carsten Haitzler (The Rasterman)
<raster at rasterman.com> said:
> On Fri, 5 Aug 2016 07:45:50 -0500 Derek Foreman <derekf at osg.samsung.com> said:
>
> > On 27/07/16 02:54 AM, Jonas Ådahl wrote:
> > > xdg-foreign is a protocol meant to enable setting up inter surface
> > > relationships across clients. Potential use cases are out-of-process
> > > dialogs, such as file dialogs, meant to be used by sandboxed processes
> > > that may not have the access it needs to implement such dialogs.
> > >
> > > It works by enabling a client to export a surface, creating a handle
> > > for the exported surface. The handle, in form of a unique string, may
> > > be shared in some way with other clients (for example the provider of
> > > the file dialog) which can then import the exported surface.
> >
> > Have you considered passing an fd (have the compositor create a pipe)
> > instead of a string?
> >
> > Then the shared token is impossible to guess.
> >
> > Even so, this looks workable and not too hard to implement.
>
> are you sure this should just be some client chosen string. this sounds bad in
> that it means if client choose bad strings they compromise their security.
>
> https://git.enlightenment.org/core/efl.git/tree/src/lib/ecore_wayland/session-recovery.xml
>
> - the compositor will provide a uuid via an event. the idea is the compositor
> picks some big long sha1 or whatever hash string. client supplies this if it
> reconnects after compositor went away unexpectedly (crash/restart/upgrade).
>
> i think a similar system but uuid's for "naming a surface" would be good. then
> client a can say "hey this dialog is for uuid xyz" as long as the client
> owning xyz can provide the uuid do this other one.
>
> the point of uuid's is so they CAN survive process restarts too, compositor
> restarts etc. unlike fd's where the last process holding that fd dies .... you
> lost the handle.
better:
https://git.enlightenment.org/core/efl.git/tree/src/lib/ecore_wl2/session-recovery.c
https://git.enlightenment.org/core/efl.git/tree/src/lib/ecore_wl2/session-recovery.h
and wrapper:
https://git.enlightenment.org/core/efl.git/tree/src/lib/ecore_wl2/ecore_wl2_window.c
> > Reviewed-by: Derek Foreman <derekf at osg.samsung.com>
> >
> > Thanks,
> > Derek
> > > Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> > > ---
> > >
> > > Changes since v1:
> > >
> > > - Spelling and grammar fixes
> > > - Wording changes (unexport -> revoke)
> > > - Fixed the "Warning! .. unstable .." paragraph (was an old version)
> > > - Added sandbox client -> unsandboxed file browser dialog example to
> > > protocol description
> > > - Removed left-over note about restriction of importing a handle only
> > > once. It should be possible to import a handle multiple times, but the
> > > protocol text had only been updated in one of two places.
> > >
> > >
> > > Jonas
> > >
> > >
> > >
> > > Makefile.am | 1 +
> > > unstable/xdg-foreign/README | 4 +
> > > unstable/xdg-foreign/xdg-foreign-unstable-v1.xml | 186 ++++++++++++++++++
> > > ++ +++ 3 files changed, 191 insertions(+)
> > > create mode 100644 unstable/xdg-foreign/README
> > > create mode 100644 unstable/xdg-foreign/xdg-foreign-unstable-v1.xml
> > >
> > > diff --git a/Makefile.am b/Makefile.am
> > > index 9e2a029..35df201 100644
> > > --- a/Makefile.am
> > > +++ b/Makefile.am
> > > @@ -9,6 +9,7 @@ unstable_protocols
> > > = \
> > > unstable/pointer-constraints/pointer-constraints-unstable-v1.xml \
> > > unstable/tablet/tablet-unstable-v1.xml
> > > \
> > > unstable/tablet/tablet-unstable-v2.xml
> > > \
> > > +
> > > unstable/xdg-foreign/xdg-foreign-unstable-v1.xml \
> > > $(NULL)
> > > stable_protocols
> > > = \ diff
> > > --git a/unstable/xdg-foreign/README b/unstable/xdg-foreign/README new file
> > > mode 100644 index 0000000..f5bcb83
> > > --- /dev/null
> > > +++ b/unstable/xdg-foreign/README
> > > @@ -0,0 +1,4 @@
> > > +xdg foreign protocol
> > > +
> > > +Maintainers:
> > > +Jonas Ådahl <jadahl at gmail.com>
> > > diff --git a/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml
> > > b/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml new file mode 100644
> > > index 0000000..c6f5775
> > > --- /dev/null
> > > +++ b/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml
> > > @@ -0,0 +1,186 @@
> > > +<?xml version="1.0" encoding="UTF-8"?>
> > > +<protocol name="xdg_foreign_unstable_v1">
> > > +
> > > + <copyright>
> > > + Copyright © 2015-2016 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 exporting xdg surface handles">
> > > + This protocol specifies a way for making it possible to reference a
> > > surface
> > > + of a different client. With such a reference, a client can, by using
> > > the
> > > + interfaces provided by this protocol, manipulate the relationship
> > > between
> > > + its own surfaces and the surface of some other client. For example,
> > > stack
> > > + some of its own surface above the other clients surface.
> > > +
> > > + In order for a client A to get a reference of a surface of client B,
> > > client
> > > + B must first export its surface using xdg_exporter.export. Upon doing
> > > this,
> > > + client B will receive a handle (a unique string) that it may share
> > > with
> > > + client A in some way (for example D-Bus). After client A has received
> > > the
> > > + handle from client B, it may use xdg_importer.import to create a
> > > reference
> > > + to the surface client B just exported. See the corresponding requests
> > > for
> > > + details.
> > > +
> > > + A possible use case for this is out-of-process dialogs. For example
> > > when a
> > > + sandboxed client without file system access needs the user to select
> > > a file
> > > + on the file system, given sandbox environment support, it can export
> > > its
> > > + surface, passing the exported surface handle to an unsandboxed
> > > process that
> > > + can show a file browser dialog and stack it above the sandboxed
> > > client's
> > > + surface.
> > > +
> > > + 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_exporter_v1" version="1">
> > > + <description summary="interface for exporting surfaces">
> > > + A global interface used for exporting surfaces that can later be
> > > imported
> > > + using xdg_importer.
> > > + </description>
> > > +
> > > + <request name="destroy" type="destructor">
> > > + <description summary="destroy the xdg_exporter object">
> > > + Notify the compositor that the xdg_exporter object will no longer
> > > be
> > > + used.
> > > + </description>
> > > + </request>
> > > +
> > > + <request name="export">
> > > + <description summary="export a surface">
> > > + The export request exports the passed surface so that it can
> > > later be
> > > + imported via xdg_importer. When called, a new xdg_exported object
> > > will
> > > + be created and xdg_exported.handle will be sent immediately. See
> > > the
> > > + corresponding interface and event for details.
> > > +
> > > + A surface may be exported multiple times, and each exported
> > > handle may
> > > + be used to create a xdg_imported multiple times. Only xdg_surface
> > > + surfaces may be exported.
> > > + </description>
> > > +
> > > + <arg name="id" type="new_id" interface="zxdg_exported_v1"
> > > + summary="the new xdg_exported object"/>
> > > + <arg name="surface" type="object" interface="wl_surface"
> > > + summary="the surface to export"/>
> > > + </request>
> > > + </interface>
> > > +
> > > + <interface name="zxdg_importer_v1" version="1">
> > > + <description summary="interface for importing surfaces">
> > > + A global interface used for importing surfaces exported by
> > > xdg_exporter.
> > > + With this interface, a client can create a reference to a surface
> > > of
> > > + another client.
> > > + </description>
> > > +
> > > + <request name="destroy" type="destructor">
> > > + <description summary="destroy the xdg_importer object">
> > > + Notify the compositor that the xdg_importer object will no longer
> > > be
> > > + used.
> > > + </description>
> > > + </request>
> > > +
> > > + <request name="import">
> > > + <description summary="import a surface">
> > > + The import request imports a surface from any client given a
> > > handle
> > > + retrieved by exporting said surface using xdg_exporter.export.
> > > When
> > > + called, a new xdg_imported object will be created. This new
> > > object
> > > + represents the imported surface, and the importing client can
> > > + manipulate its relationship using it. See xdg_imported for
> > > details.
> > > + </description>
> > > +
> > > + <arg name="id" type="new_id" interface="zxdg_imported_v1"
> > > + summary="the new xdg_imported object"/>
> > > + <arg name="handle" type="string"
> > > + summary="the exported surface handle"/>
> > > + </request>
> > > + </interface>
> > > +
> > > + <interface name="zxdg_exported_v1" version="1">
> > > + <description summary="an exported surface handle">
> > > + A xdg_exported object represents an exported reference to a
> > > surface. The
> > > + exported surface may be referenced as long as the xdg_exported
> > > object not
> > > + destroyed. Destroying the xdg_exported invalidates any relationship
> > > the
> > > + importer may have established using xdg_imported.
> > > + </description>
> > > +
> > > + <request name="destroy" type="destructor">
> > > + <description summary="unexport the exported surface">
> > > + Revoke the previously exported surface. This invalidates any
> > > + relationship the importer may have set up using the xdg_imported
> > > created
> > > + given the handle sent via xdg_exported.handle.
> > > + </description>
> > > + </request>
> > > +
> > > + <event name="handle">
> > > + <description summary="the exported surface handle">
> > > + The handle event contains the unique handle of this exported
> > > surface
> > > + reference. It may be shared with any client, which then can use
> > > it to
> > > + import the surface by calling xdg_importer.import. A handle may
> > > be
> > > + used to import the surface multiple times.
> > > + </description>
> > > +
> > > + <arg name="handle" type="string" summary="the exported surface
> > > handle"/>
> > > + </event>
> > > + </interface>
> > > +
> > > + <interface name="zxdg_imported_v1" version="1">
> > > + <description summary="an imported surface handle">
> > > + A xdg_imported object represents an imported reference to surface
> > > exported
> > > + by some client. A client can use this interface to manipulate
> > > + relationships between its own surfaces and the imported surface.
> > > + </description>
> > > +
> > > + <request name="destroy" type="destructor">
> > > + <description summary="destroy the xdg_imported object">
> > > + Notify the compositor that it will no longer use the xdg_imported
> > > + object. Any relationship that may have been set up will at this
> > > point
> > > + be invalidated.
> > > + </description>
> > > + </request>
> > > +
> > > + <request name="set_parent_of">
> > > + <description summary="set as the parent of some surface">
> > > + Set the imported surface as the parent of some surface of the
> > > client.
> > > + The passed surface must be a toplevel xdg_surface. Calling this
> > > function
> > > + sets up a surface to surface relation with the same stacking and
> > > positioning
> > > + semantics as xdg_surface.set_parent.
> > > + </description>
> > > +
> > > + <arg name="surface" type="object" interface="wl_surface"
> > > + summary="the child surface"/>
> > > + </request>
> > > +
> > > + <event name="destroyed">
> > > + <description summary="the imported surface handle has been
> > > destroyed">
> > > + The imported surface handle has been destroyed and any
> > > relationship set
> > > + up has been invalidated. This may happen for various reasons, for
> > > + example if the exported surface or the exported surface handle
> > > has been
> > > + destroyed, if the handle used for importing was invalid.
> > > + </description>
> > > + </event>
> > > + </interface>
> > > +
> > > +</protocol>
> > >
> >
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel at lists.freedesktop.org
> > https://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
>
> --
> ------------- Codito, ergo sum - "I code, therefore I am" --------------
> The Rasterman (Carsten Haitzler) raster at rasterman.com
>
--
------------- Codito, ergo sum - "I code, therefore I am" --------------
The Rasterman (Carsten Haitzler) raster at rasterman.com
More information about the wayland-devel
mailing list