GNOME Screensaver 2.15.3 Documentation

William Jon McCann


            
          

Version 2.15.3


Table of Contents

1. DBUS Interface
Introduction
Methods
Lock
Cycle
SimulateUserActivity
Inhibit
UnInhibit
Throttle
UnThrottle
SetActive
GetActive
GetActiveTime
GetSessionIdle
GetSessionIdleTime
Signals
ActiveChanged
SessionIdleChanged
AuthenticationRequestBegin
AuthenticationRequestEnd
Examples

Chapter 1. DBUS Interface

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

Introduction

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

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.

DirectionTypeDescription
instringthe application name, e.g. "totem"
instringthe localized reason to inhibit, e.g. "playing movie"
outunsigned integerthe 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.

DirectionTypeDescription
inunsigned integerthe cookie

Throttle

Request that running themes while the screensaver is active be blocked until UnThrottle is called or the calling process exits.

DirectionTypeDescription
instringthe application name, e.g. "gnome-power-manager"
instringthe localized reason to inhibit, e.g. "on battery power"
outunsigned integerthe 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.

DirectionTypeDescription
inunsigned integerthe 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.

DirectionTypeDescription
inbooleanTRUE to request activation, FALSE to request deactivation

GetActive

Returns the value of the current state of activity. See SetActive().

DirectionTypeDescription
outbooleanActivation state

GetActiveTime

Returns the number of seconds that the screensaver has been active. Returns zero if the screensaver is not active.

DirectionTypeDescription
outunsigned integerActive time in seconds

GetSessionIdle

Returns the value of the current state of session idleness.

DirectionTypeDescription
outbooleanIf the session is idle

GetSessionIdleTime

Returns the number of seconds that the session has been idle. Returns zero if the session is not idle.

DirectionTypeDescription
outunsigned integerIdle time in seconds

Signals

These are the DBUS signals.

ActiveChanged

See method GetActive().

DirectionTypeDescription
outbooleanReturns the value of the current state of activity.

SessionIdleChanged

See method GetActive().

DirectionTypeDescription
outbooleanReturns the value of the current state of activity.

AuthenticationRequestBegin

Emitted before an authentication request

AuthenticationRequestEnd

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