Xfce Screensaver DBUS Interface
This document was originally authored by William Jon McCann.
The source material can be found in the Xfce Screensaver GIT repository.
Introduction
Xfce 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 XfceScreensaver object when making DBUS method calls:
| DBUS Service: | org.xfce.ScreenSaver |
| DBUS Object Path: | /org/xfce/ScreenSaver |
| DBUS Interface: | org.xfce.ScreenSaver |
Methods
These are the DBUS methods.
Lock
Request that the screen be locked. This bypasses all Inhibit requests.
Cycle
Request that the screen saver theme be restarted and, if applicable, switch to the next one in the list.
SimulateUserActivity
Simulate user activity. If the screensaver is activated this will attempt to deactivate and authentication will be requested if necessary. If the screensaver is not activated then the idle timers will be reset.
Inhibit
Request that saving the screen due to system idleness be blocked until UnInhibit is called or the calling process exits.
| Direction | Type | Description |
|---|---|---|
| in | string | the application name, e.g. “totem” |
| in | string | the localized reason to inhibit, e.g. “playing movie” |
| out | unsigned integer | the cookie |
A cookie is a random, unique, non-zero UINT32 used to identify the inhibit request.
UnInhibit
Cancel a previous call to Inhibit() identified by the cookie.
| Direction | Type | Description |
|---|---|---|
| in | unsigned integer | the cookie |
Throttle
Request that running themes while the screensaver is active be blocked until UnThrottle is called or the calling process exits.
| Direction | Type | Description |
|---|---|---|
| in | string | the application name, e.g. “xfce-power-manager” |
| in | string | the localized reason to inhibit, e.g. “on battery power” |
| out | unsigned integer | the cookie |
A cookie is a random, unique, non-zero UINT32 used to identify the throttle request.
UnThrottle
Cancel a previous call to Throttle() identified by the cookie.
| Direction | Type | Description |
|---|---|---|
| in | unsigned integer | the cookie |
SetActive
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.
| Direction | Type | Description |
|---|---|---|
| in | boolean | TRUE to request activation, FALSE to request deactivation |
GetActive
Returns the value of the current state of activity. See SetActive().
| Direction | Type | Description |
|---|---|---|
| out | boolean | Activation state |
GetActiveTime
Returns the number of seconds that the screensaver has been active. Returns zero if the screensaver is not active.
| Direction | Type | Description |
|---|---|---|
| out | unsigned integer | Active time in seconds |
Signals
These are the DBUS signals.
ActiveChanged
See method GetActive().
| Direction | Type | Description |
|---|---|---|
| out | boolean | Returns the value of the current state of activity. |
Examples
You can activate the screensaver like so:
dbus-send --session \
--dest=org.xfce.ScreenSaver \
--type=method_call \
--print-reply \
--reply-timeout=20000 \
/org/xfce/ScreenSaver \
org.xfce.ScreenSaver.SetActive \
boolean:true
You can monitor screensaver changes:
dbus-monitor --session \
"type='signal',interface='org.xfce.ScreenSaver'"