screensaver and power manager dbus interfaces

Richard Hughes hughsient at gmail.com
Thu Jun 1 01:01:31 EEST 2006


Okay, my first post to this list, so I hope I'm aiming in the right
direction.

gnome power manager :		org.gnome.PowerManager
gnome screensaver   :		org.gnome.ScreenSaver

This should probably be cross desktop and less gnome-y as there's no
reason another program shouldn't just drop in as a replacement for
either xfce, kde or just a slim-line gnome replacement.

The interfaces we have now are attached.

Comments appreciated.

Richard

-------------- next part --------------
The GNOME Power Manager DBUS API
------------------------------

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

GNOME Power Manager exposes a DBUS API for programs to obtain
information about the DPMS state and to change it if required.

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

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

Methods
=======

	Name:		Suspend
	Args:		(none)
	Returns:	BOOLEAN
	Description:	This call will attempt to suspend the system.

	Name:		Hibernate
	Args:		(none)
	Returns:	BOOLEAN
	Description:	This call will attempt to hibernate the system.

	Name:		Shutdown
	Args:		(none)
	Returns:	BOOLEAN
	Description:	This call will attempt to shutdown the system.

	Name:		CanSuspend
	Args:		(none)
	Returns:	BOOLEAN
	Description:	This call Finds if the current user in the session
			is able to suspend, and has permission to do so.

	Name:		CanHibernate
	Args:		(none)
	Returns:	BOOLEAN
	Description:	This call Finds if the current user in the session
			is able to hibernate, and has permission to do so.

	Name:		setDpmsMode
	Args:		STRING
			value:	on		100%
				standby		<80%
				suspend		<30W
				off		<8W
	Returns:	(nothing)
	Description:	DPMS is a standard from the VESA consortium for
			managing the power supply of monitors.
			This call requests a change in the state of DPMS for
			the current screen.

	Name:		getDpmsMode
	Args:		(none)
	Returns:	STRING
	Descriptions:	Returns the DPMS mode state.
			See setDpmsMode().

	Name:		InhibitInactiveSleep
	Args:		STRING "application-name"
			STRING "reason to inhibit"
	Returns:	INT cookie
			This is a random number used to identify the inhibit.
	Descriptions:	Inhibits the computer from performing the idle sleep
			action. Useful if you want to do an operation of long 
			duration without the computer suspending.

	Name:		AllowInactiveSleep
	Args:		INT cookie
	Returns:	(none)
	Descriptions:	Allows the computer to perform the idle sleep action.
			Applications that quit without calling this method will
			be automatically unregistered, but this is not
			recommended as the user will be warned.

Signals
=======

	Name:		DpmsModeChanged
	Args:		BOOLEAN state
	Returns:	Returns the value of the current state of activity.
	Description:	See method setDpmsMode().

Examples
========

You can get the DPMS mode by running the following:

dbus-send --session \
	  --dest=org.gnome.PowerManager \
	  --type=method_call \
	  --print-reply \
	  --reply-timeout=2000 \
	  /org/gnome/PowerManager \
	  org.gnome.PowerManager.getDpmsMode

You can set the DPMS mode by running the following:

dbus-send --session \
	  --dest=org.gnome.PowerManager \
	  --type=method_call \
	  --print-reply \
	  --reply-timeout=2000 \
	  /org/gnome/PowerManager \
	  org.gnome.PowerManager.setDpmsMode \
	  string:suspend

You can put the system into hibernation using the following:

dbus-send --session \
	  --dest=org.gnome.PowerManager \
	  --type=method_call \
	  --print-reply \
	  --reply-timeout=2000 \
	  /org/gnome/PowerManager \
	  org.gnome.PowerManager.Hibernate
-------------- next part --------------
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().

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

        Name:           AuthenticationRequestEnd
        Args:           (none)
        Description:    Emitted after an authentication request

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.getSessionIdleTime


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='SessionIdleChanged'"


More information about the xdg mailing list