[PATCH weston-ivi-shell v2 02/15] ivi application protocol:
Pekka Paalanen
ppaalanen at gmail.com
Mon Mar 10 01:41:38 PDT 2014
On Fri, 7 Mar 2014 10:39:44 -0600
Jason Ekstrand <jason at jlekstrand.net> wrote:
> On Mar 7, 2014 7:56 AM, "Nobuhiko Tanibata" <
> NOBUHIKO_TANIBATA at xddp.denso.co.jp> wrote:
> >
> > Add interface ivi_application, which creates ivi_surface objects
> > tied to a given wl_surface with a given id. The given id can be
> > used in a shell to identify which application is assigned to a
> > wl_surface and layout the surface wherever the shell wants.
> > ivi_surface objects can be used to receive status of wl_surface in
> > the scenegraph of the compositor.
> >
> > Signed-off-by: Nobuhiko Tanibata
> > <NOBUHIKO_TANIBATA at xddp.denso.co.jp> ---
> >
> > Changes for v2:
> > - Rename "error" to "warning" because meaning of "error" in
> > wayland is
> fatal.
> >
> > protocol/ivi-application.xml | 88
> ++++++++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 88 insertions(+)
> > create mode 100755 protocol/ivi-application.xml
> >
> > diff --git a/protocol/ivi-application.xml
> > b/protocol/ivi-application.xml new file mode 100755
> > index 0000000..8659ec6
> > --- /dev/null
> > +++ b/protocol/ivi-application.xml
> > @@ -0,0 +1,88 @@
> > +<?xml version="1.0" encoding="UTF-8"?>
> > +<protocol name="ivi_application">
> > +
> > + <copyright>
> > + Copyright (C) 2013 DENSO CORPORATION
> > + Copyright (c) 2013 BMW Car IT GmbH
> > +
> > + 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 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>
> > +
> > + <interface name="ivi_surface" version="1">
> > + <description summary="application interface to surface in
> > ivi
> compositor"/>
> > +
> > + <request name="destroy" type="destructor">
> > + <description summary="destroy ivi_surface"/>
> > + </request>
> > +
> > + <event name="visibility">
> > + <description summary="visibility of surface in ivi
> compositor has changed">
> > + The new visibility state is provided in argument
> visibility.
> > + If visibility is 0, the surface has become
> > invisible.
> > + If visibility is not 0, the surface has become
> > visible.
> > + </description>
> > + <arg name="visibility" type="int"/>
> > + </event>
> > +
> > + </interface>
> > +
> > + <interface name="ivi_application" version="1">
> > + <description summary="interface for ivi applications to
> > use ivi
> compositor features"/>
> > +
> > + <request name="surface_create">
> > + <description summary="create surface in ivi
> > compositor">
> > + surface_create will create a new surface with
> > surface_id
> in ivi compositor,
> > + if it does not yet exists. If the surface with
> surface_id already exists in
> > + ivi compositor, the application content provided in
> argument surface will
> > + be used as surface content. If an other ivi
> > application
> already registered
> > + content for surface with surface_id, an warning
> > event
> will indicate the problem.
> > + </description>
> > + <arg name="id_surface" type="uint"/>
> > + <arg name="surface" type="object"
> > interface="wl_surface"/>
> > + <arg name="id" type="new_id" interface="ivi_surface"/>
> > + </request>
> > +
> > + <enum name="warning_code">
> > + <description summary="possible warning codes returned
> > by ivi
> compositor">
> > + These warning codes define all possible warning
> > codes
> returned by ivi compositor
> > + on server-side warnings.
> > + </description>
> > + <entry name="invalid_wl_surface" value="1"
> summary="wl_surface is invalid"/>
> > + <entry name="surface_id_in_use" value="2"
> summary="surface_id is in use and can not be shared"/>
> > + </enum>
>
> I have a couple more thoughts about these errors/warnings. For one, I
> think some of these should be errors. For instance, there is no way
> that the given wl_surface will be invalid unless the client has
> destroyed it. Honestly, I'm not even sure if it's possible, given how
> libwayland is written, to get a truely invalid wl_surface. From what
> you've written in previous e-mails, I can't quite tell but it sounds
> like you want to prevent a client from attaaching multiple
> ivi_surface objects (and IVI ID's) to the same surface. If this is
> the case then doing so should probably also be a fatal error because
> that means the client was written wrong.
>
> With regards to what happens if a client tries to use an ID that's
> already in use, I'm not 100% sure what to do there. You know IVI
> systems better than I do. Is this something that happens with some
> degree of regularity? Or is this something that only happens if the
> there is a mistake in the client code? I'll leave that up to you.
>
> That said, if there is an issue, you need to explicitly say what
> happens to the newly created ivi_surface object. The Wayland
> protocol has no concept of returning NULL. Whenever a request or
> event is fired which has a new_id parameter, both client and
> server-side objects always get created. If surface_create can throw
> a non-fatal error, we need to decide what happens to the new
> ivi_surface object. One way to do this would be to have the
> error/warning event on the ivi_surface itself instead of on
> ivi_application. Then the client would know that if it recieves the
> error/warning, that it needs to destroy the corresponding
> ivi_surface. Otherwise, like you note below, they have to roundtrip
> after every call to ivi_application.surface_create.
Hi Nobuhiko,
Jason pretty much covered everything that came to my mind, too.
I just want to stress, that if a problem is caused by e.g. bad
IVI-system configuration done by the system manufacturer rather than
something the end user did, then I think you should keep to fatal
errors. If a car manufacturer or a software vendor configures or codes
something wrong, you really want to catch all those errors ASAP.
Killing the whole client is a good way to point out such error
conditions that really should never happen at runtime. Conflicting
surface ID thing sounds like it is the system maker's fault, not an end
user mistake.
OTOH, if these problem cases can happen when the end user does
something wrong, e.g. tries to open an application twice or whatever,
the first thing would be to make sure the UI prevents such things from
occurring in the first place. If you still need non-fatal errors in the
protocol, then you have to have a solid plan on what happens with the
request that caused it. Jason explained it well, you have to define how
the already created protocol object works after the error has occurred
in the compositor, i.e. even before the client receives the error
event. The client might send requests to or requests referring the
failed object before it processes the error event. You also should say
something about how the client is expected to recover from this error.
If the client is not disconnected, there must be a way to recover
smoothly.
Jason's point about avoiding the roundtrip is a very good one.
I haven't read the rest of the patches yet, but if you have error
events defined in other protocol parts, the same comments apply.
Personally I would hope for some more explanations on what the "ID" is,
and how it is used, or at least a pointer in the .xml to more extensive
documentation. It is quite odd to see numeric IDs passed manually in
Wayland protocol.
Thanks,
pq
> > +
> > + <event name="warning">
> > + <description summary="server-side warning detected">
> > + The ivi compositor encountered warning while
> > processing
> a request by this
> > + application. The warning is defined by argument
> warning_code and optional
> > + warning_text.
> > + If the application requires to associate this
> > warning
> event to a request,
> > + it can
> > + 1. send request
> > + 2. force display roundtrip
> > + 3. check, if warning event was received
> > + but this restricts the application to have only
> > one
> open request at a time.
> > + </description>
> > + <arg name="warning_code" type="int"/>
> > + <arg name="warning_text" type="string"
> > allow-null="true"/>
> > + </event>
> > +
> > + </interface>
> > +
> > +</protocol>
> > --
> > 1.8.3.1
> >
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel at lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list