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:           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:           InhibitActivation
        Args:           DBUS_TYPE_STRING reason
                        reason: Description of the reason why saving the screen
                                should be inhibited.
        Returns:        (nothing)
        Description:    Request that saving the screen due to system idleness
                        be blocked until AllowActivation is called or the
                        calling process exits.

        Name:           AllowActivation
        Args:           (none)
        Returns:        (nothing)
        Description:    Cancel any previous call to InhibitActivation() by the
                        calling process.

        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:           setThrottleEnabled
        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 theme throttle.
                        Set to TRUE to request that the screensaver not run
                        themes while the screensaver is active.

        Name:           getThrottleEnabled
        Args:           (none)
        Returns:        DBUS_TYPE_BOOLEAN
        Descriptions:   Returns the value of the current throttle state
                        See setThrottleEnabled().


Signals
=======

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

	Name:           ThrottleEnabledChanged
        Args:           DBUS_TYPE_BOOLEAN state
        Returns:        Returns the value of the current throttle state.
        Description:    See method getThrottleEnabled().


Examples
========

You can get the idle time 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
