screensaver dbus interfaces

[Stephan Kulow]

Hi!

I implemented the required functionality for KDE trunk (currently 3.80)
and while I'd like to leave out some functions that I see as too specific
for generic use, I'd like to discuss this. KDE currently registers the 
interface as org.freedesktop.ScreenSaver and extends it with some internal 
functions on its own. I patched Richard's original mail and hinted it where 
it's not obvious :)

Greetings, Stephan

The Screensaver DBUS API
------------------------------

This API is currently unstable and is likely to change in the future.

Screensaver exposes a DBUS API for programs to obtain
information about the screensaver state and to interact with
the screensaver in limited ways.

The following constants are used to uniquely refer to the
Screensaver object when making DBUS method calls:

DBUS Service:                   "org.freedesktop.ScreenSaver"
DBUS Object Path:            "/ScreenSaver"
(coolo) I removed the duplicated org.gnome from it as there shouldn't be too 
many different screensaver objects in the Service.

DBUS Interface:                 "org.freedkestop.ScreenSaver"

Methods
=======

        Name:           Lock
        Args:           (none)
        Returns:        (nothing)
        Description:    Request that the screen be locked.
(coolo) This will always require a password for unlock, while setActive
          will use whatever is configured

        Name:           Cycle
        Args:           (none)
        Returns:        (nothing)
        Description:    Request that the screen saver theme be restarted
                        and if applicable switch to the next one in the list.
(coolo) remove - KDE's random theme is a hack on its own and it is not 
applicable.

        Name:           SimulateUserActivity
        Args:           (none)
        Returns:        (nothing)
        Description:    Simulate user activity.
(coolo) g-s renamed it, the original proposal contained Poke


        Name:           Inhibit
        Args:           DBUS_TYPE_STRING "application-name"
                        DBUS_TYPE_STRING "reason for inhibit"
        Returns:        INT cookie
                        This is a random number used to identify the request.
        Description:    Request that saving the screen due to system idleness
                        be blocked until UnInhibit is called or the
                        calling process exits.

        Name:           UnInhibit
        Args:           DBUS_TYPE_UINT32 cookie
        Returns:        (nothing)
        Description:    Cancel a previous call to Inhibit() identified by the
                            cookie.

        Name:           Throttle
        Args:           DBUS_TYPE_STRING "application-name"
                        DBUS_TYPE_STRING "reason for throttle"
        Returns:        INT cookie
                        This is a random number used to identify the request.
        Description:    Request that running themes while the screensaver is
                        active be blocked until UnThrottle is called or the
                        calling process exits.
(coolo) Richard and me discussed and the documentation is lacking that this
call will have the consequence that only the blank theme is used in case the 
session becomes idle after the call.

        Name:           UnThrottle
        Args:           DBUS_TYPE_UINT32 cookie
        Returns:        (nothing)
        Description:    Cancel a previous call to Throttle() identified by the
                            cookie.

        Name:           SetActive
        Args:           DBUS_TYPE_BOOLEAN state
                        state: TRUE to request activation,
                               FALSE to request deactivation
        Returns:        (nothing)
        Description:    Request a change in the state of the screensaver.
                        Set to TRUE to request that the screensaver activate.
                        Active means that the screensaver has blanked the
                        screen and may run a graphical theme.  This does
                        not necessary mean that the screen is locked.
(coolo) We discussed and couldn't really agree if the function should return a 
bool to indicate an activation problem (not so interesting for FALSE).

        Name:           GetActive
        Args:           (none)
        Returns:        DBUS_TYPE_BOOLEAN
        Descriptions:   Returns the value of the current state of activity.
                        See setActive().

        Name:           GetActiveTime
        Args:           (none)
        Returns:        DBUS_TYPE_UINT32
        Descriptions:   Returns the number of seconds that the screensaver has
                        been active.  Returns zero if the screensaver is not
                        active.

        Name:           GetSessionIdle
        Args:           (none)
        Returns:        DBUS_TYPE_BOOLEAN
        Descriptions:   Returns the value of the current state of session
                           idleness.
(coolo) I see no use in this method. From what I understood, it's there to 
indicate that the screensaver would run.

        Name:           GetSessionIdleTime
        Args:           (none)
        Returns:        DBUS_TYPE_UINT32
        Descriptions:   Returns the number of seconds that the session has
                        been idle.  Returns zero if the session is not idle.

Signals
=======

        Name:           ActiveChanged
        Args:           DBUS_TYPE_BOOLEAN state
        Returns:        Returns the value of the current state of activity.
        Description:    See method getActive().

        Name:           SessionIdleChanged
        Args:           DBUS_TYPE_BOOLEAN state
        Returns:        Returns the value of the current state of activity.
        Description:    See method getActive().
(coolo) see GetSessionIdle

        Name:           AuthenticationRequestBegin
        Args:           (none)
        Description:    Emitted before an authentication request

        Name:           AuthenticationRequestEnd
        Args:           (none)
        Description:    Emitted after an authentication request
(coolo) I see no use of this signals. Richard explained to me, that the power 
manager reacts on these, but I would like to discuss if it's not more logical 
if the power manager provides a way to indicate the start and end of 
processes that require attention (to power the display).

Examples
========

You can get the number of seconds the screensaver has been active by
running the following:

dbus-send --session \
          --dest=org.freedesktop.ScreenSaver \
          --type=method_call \
          --print-reply \
          --reply-timeout=20000 \
          /ScreenSaver \
          org.freedesktop.ScreenSaver.getSessionIdleTime