[PATCH wayland-protocols] Introduce xdg-foreign protocol
Yong Bakos
junk at humanoriented.com
Wed Jul 20 19:04:04 UTC 2016
Hi Jonas,
> On Jul 13, 2016, at 12:58 AM, Jonas Ådahl <jadahl at gmail.com> 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.
>
> Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
Interesting protocol. Just a wild thought: would surface-exporting be
something useful in the core Wayland protocol? (Not now, but...)
I'll need to re-read and imagine the scenarios, but I feel like there
is some inconsistency in either the descriptions or the protocol itself.
Specifically, I thought that the exported surface from client A would
be displayed by client B as an xdg_toplevel, but then I also see
set_parent_of, meaning that client B can add subsurfaces to the
imported surface?
No need to explain that in length, I think I just need to re-read.
Some notes inline below.
> ---
>
> Hi,
>
> This protocol is intended to be used by flatpak's xdg desktop portals, in order
> to have a portal dialog (such as a file chooser) to be stacked above (and maybe
> as a modal) a parent surface.
>
> A compositor that want to be able to run sandboxed Wayland clients that need to
> use portals would need to implement this protocol.
>
> In short, a sandboxed client would "export" its surface and in the process
> retrieve a server generated handle string, acting as a unique identifier for
> the exported window. In the flatpak case the client will pass the identifier
> string via D-Bus to a xdg desktop portal service provider, which will then
> import it using xdg_importer and create a xdg_imported object that it can be
> used to modify the stacking relationship.
>
> So far the only supported operation is setting an imported window to be the
> parent of some surface.
>
> Note that the protocol documentation says "xdg_surface". In the future this
> would be "xdg_toplevel".
>
>
> Jonas
>
> Makefile.am | 1 +
> unstable/xdg-foreign/README | 4 +
> unstable/xdg-foreign/xdg-foreign-unstable-v1.xml | 177 +++++++++++++++++++++++
> 3 files changed, 182 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 71d2632..06a1bb2 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -8,6 +8,7 @@ unstable_protocols = \
> unstable/relative-pointer/relative-pointer-unstable-v1.xml \
> unstable/pointer-constraints/pointer-constraints-unstable-v1.xml \
> unstable/tablet/tablet-unstable-v1.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..d8a90c3
> --- /dev/null
> +++ b/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml
> @@ -0,0 +1,177 @@
> +<?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 relatioship between its
relationship
> + own surfaces and surface of some other client, for example stack some of its
> + own surface above the other clients surface.
own surfaces and the surface of some other client. For example, a client may stack
another client's surface above some of its own.
How about something like the above wording, which fits the scenario of a client
wanting to stack a flatpak portal dialog / file chooser above its own surface(s).
> +
> + 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 have received the
has received
> + 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.
> +
> + Warning! The protocol described in this file is experimental. Each version
> + of this protocol should be considered incompatible with any other version,
> + and a client binding to a version different to the one advertised will be
> + terminated. Once the protocol is declared stable, backward compatibility
> + is guaranteed, the '_' prefix will be removed from the name and the
> + version will be reset to 1.
> + </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">
How about xdg_export instead of 'exported'?
> + <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">
> + Unexport the previously exported surface. This invalidates any
Perhaps 'revoke' instead of unexport.
> + 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 only be
> + used to import the surface once.
How would this be enforced?
> + </description>
> +
> + <arg name="handle" type="string" summary="the exported surface handle"/>
> + </event>
> + </interface>
> +
> + <interface name="zxdg_imported_v1" version="1">
How about xdg_import?
> + <description summary="an imported surface handle">
> + A xdg_imported object represents a imported reference to surface exported
an imported
> + 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
> + destroeyed, if the handle used for importing was invalid.
destroyed,
> + </description>
> + </event>
> + </interface>
> +
> +</protocol>
One blank line at the end, please.
Thank you,
yong
> --
> 2.7.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list