expanding the inhibit spec

[Ryan Lortie]

On Tue, Jan 7, 2014, at 13:16, Ryan Lortie wrote:
> (with the toolkit maintainer hat on) I want to expand the Inhibit spec:


Here's a bit more concrete of a proposal after thinking about it for a
day.  I really like the logind API (and am particularly fond of using
fds instead of integer cookies) so my design borrows heavily from there.
 Here's what I expect in terms of an app-facing API.  It's a single
method:


bus name     org.freedesktop.Inhibit
object path  /org/freedesktop/Inhibit
interface    org.freedesktop.Inhibit

  Inhibit (in  s     what,
           in  a{sv} who,
           in  s     why,
           out h     fd);


Where 'what' and 'why' are as per the logind spec.

Who is a dictionary that has these optional keys:

 - desktop-file-name: the name of the desktop file of this app
 - application-id:    the org.freedesktop.Application-style app id
 - window-xid:        the (uint32) xid of the window causing the
 inhibit, if on X11
 - window-wayland-id: ???

with the requirement that at least one of these things must be set.


The output fd would work in the same way as it does for logind.  You
simply close the fd when you're no longer interested.


Copying the fd-based design from logind means that we can in many cases
trivially forward the requests and pass the fd from logind directly back
to the application, allowing for the possibility of a simple stateless
forwarding proxy implementation (which could even exit after a period of
inactivity).


Eventually, if we are convinced that it is widely useful, we may want to
add an additional API to deal with (what I consider to be the separate
case of) delaying the suspend process for a short while:

  Delay (in  s what,
         out h fd);

with "what" limited to "sleep" and the following semantics for the fd
(from the client's viewpoint):

 - reads a \1 byte when suspend wants to occur
 - replies by writing a \1 byte to say "okay.  i'm ready"
 - reads a \0 byte when suspend has come back
 - can close at any time to cancel the delay

This allows us to avoid having a PrepareToSleep() signal that must be
emitted (in particular, when it must be emitted in the "welcome back"
case in order for clients to re-establish their delays).  Clients can
reuse the same fd for as many sleep cycles as they like.  As with
logind, the delay would only work for a short period of time.  logind's
default of 5s seems reasonable.

Note that there is no "why" or "who" about delays -- this is because
delays never result in any kind of UI being presented.  The only reason
"who" might be useful is for debugging and in that case it will be
possible to discover the bus name of the requester and map it back to
them in that way.


Individual desktop environments might want to have ways for other
components in the desktop to query the list of things that are causing
the logout/screensaver/etc to be inhibited, but I do not consider this
to be a desirable feature of an application-facing API.  Desktops would
be free to decide these details for themselves.

Cheers