[PATCH wayland-protocols v2] Introduce xdg-foreign protocol

Derek Foreman derekf at osg.samsung.com
Sun Aug 7 13:14:32 UTC 2016


On 05/08/16 10:52 AM, Jonas Ådahl wrote:
> On Fri, Aug 05, 2016 at 07:45:50AM -0500, Derek Foreman wrote:
>> 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.
> 
> As Carsten wrote in the other E-mail, a client can be lazy and generate
> a bad string. The client also wouldn't be able to generate a globally
> unique string, so to import a handle, the importing client would also
> need to associate the string with some kind of client id.

Why would clients be generating strings?

I think maybe I was too terse, I've explained what I'd intended the fd
to be used for in my other reply.

I'm fine with the proposal as-is though,  I just though perhaps a method
in which nobody generated a string at all would be better. :)

Thanks,
Derek

>>
>> Even so, this looks workable and not too hard to implement.
>>
>> Reviewed-by: Derek Foreman <derekf at osg.samsung.com>
> 
> Thanks!
> 
> 
> Jonas
> 
>>
>> 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
> 



More information about the wayland-devel mailing list