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

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

GNOME 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
GnomeScreensaver object when making DBUS method calls:

DBUS Service:			"org.gnome.ScreenSaver"
DBUS Object Path:		"/org/gnome/ScreenSaver"
DBUS Interface:                 "org.gnome.ScreenSaver"

Methods
=======

        Name:           Lock
        Args:           (none)
        Returns:        (nothing)
        Description:    Request that the screen be locked

        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.

        Name:           Poke
        Args:           (none)
        Returns:        (nothing)
        Description:    Simulate user activity.

        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.

        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.

        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.

        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().


Examples
========

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

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


You can activate the screensaver like so:

dbus-send --session \
          --dest=org.gnome.ScreenSaver \
          --type=method_call \
          --print-reply \
          --reply-timeout=20000 \
          /org/gnome/ScreenSaver \
          org.gnome.ScreenSaver.setActive \
          boolean:true


You can monitor screensaver changes:

dbus-monitor --session \
          "type='signal',interface='org.gnome.ScreenSaver'"


Or watch for a specific screensaver signal:

dbus-monitor --session \
          "type='signal',interface='org.gnome.ScreenSaver',member='ActiveChanged'"
