Chapter 1. DBUS Interface

Table of Contents

Introduction
Backlight Adjustment
SetBrightness()
GetBrightness()
BrightnessChanged
SetMode()
GetMode()
ModeChanged
User Interface Front-ends
GetDescription()
DescriptionChanged
GetIcon()
IconChanged
System State Information
GetOnAc()
OnAcChanged
GetLowPowerMode()
LowPowerModeChanged
Inhibit System Sleep
InhibitAuto()
InhibitManual()
UnInhibit()
IsValid()
IsValidChanged
Actions Control
Suspend()
Hibernate()
Shutdown()
Reboot()
AllowedSuspend()
AllowedHibernate()
AllowedShutdown()
AllowedReboot()
Register()
UnRegister()
Request
Policy()
Statistics Data
GetDataTypes()
GetAxisTypes()
GetData()

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

Introduction

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

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

DBUS Service:org.gnome.PowerManager

Backlight Adjustment

Backlight brightness and state can be changed on most LCD hardware. These are the optional DBUS methods for controlling the brightness of the backlight.

DBUS Object Path:/org/gnome/PowerManager/Backlight
DBUS Interface:org.gnome.PowerManager.Backlight

SetBrightness()

This may not immediately set the brightness if we are in a low power sleep mode, if the panel is switched off, or if the panel is in an idle dim state.

DirectionTypeDescription
inunsigned integerPercentage brightness

GetBrightness()

Returns the DPMS mode state.

DirectionTypeDescription
outunsigned integerPercentage brightness

BrightnessChanged

Signals the value of the current DPMS state has changed.

DirectionTypeDescription
outunsigned integerPercentage brightness

SetMode()

These are the optional DBUS methods for controlling the power saving of the backlight of the current screen. These correspond to Xorg DPMS states:

ModeDescription
on100% power usage
standby<50% power usage
suspend<20% power usage
off<5% power usage
DirectionTypeDescription
instringRequired DPMS mode

GetMode()

Returns the DPMS mode state.

DirectionTypeDescription
outstringCurrent screen DPMS mode

ModeChanged

Signals the value of the current DPMS state has changed.

DirectionTypeDescription
outstringCurrent screen DPMS mode

User Interface Front-ends

Some user interface front-ends will be in a different process to that of any power manager and system state will have to be transmitted over DBUS. We only export the final 'result' (the icon and description) as presenting an abstract power interface is wrong for this functionality. These are the required DBUS methods for presenting an interface to the user.

DBUS Object Path: /org/gnome/PowerManager/Ui

GetDescription()

Returns the system state description, used commonly as the tooltip for a applet or system tray icon.

DirectionTypeDescription
outstringSystem state description, e.g. Laptop battery 34 minutes until charged (34%)

DescriptionChanged

Signals the system state description has changed.

DirectionTypeDescription
outstringSystem state description

GetIcon()

Returns the system icon used as the applet or system tray icon.

DirectionTypeDescription
outstringIcon name, e.g. gpm-primary-080-charging

IconChanged

Signals the system icon has changed.

DirectionTypeDescription
outstringIcon name

System State Information

Some programs may want to know if the system is running on AC power, or running in a low power mode, for instance to disable index updating. These are the required DBUS methods for showing system state.

DBUS Object Path:/org/gnome/PowerManager/Manager
DBUS Interface:org.gnome.PowerManager.Manager

GetOnAc()

Returns the system AC state, i.e. if we are not running on battery power. Note: This method may still return false on AC using a desktop system if the computer is using backup power from a monitored UPS.

DirectionTypeDescription
outbooleanIf the system is using AC power

OnAcChanged

Signals the AC state has changed.

DirectionTypeDescription
outbooleanIf the system is using AC power

GetLowPowerMode()

Returns true if low power mode has been set. This may be set on AC or battery power, both or neither depending on the users policy setting. This setting may also change with the battery level changing. Programs should respect this value for the session, and only perform cache-updates when absolutely required.

DirectionTypeDescription
outbooleanIf the session should be run in low power mode

LowPowerModeChanged

Signals the low power mode has changed.

DirectionTypeDescription
outbooleanIf the session should be run in low power mode

Inhibit System Sleep

When the power manager detects an idle session and system, it can perform a system suspend or hibernate, known as a system sleep. We can prevent the power manager doing this action, if for instance we are doing a slow network copy that will take many hours. These are the required DBUS methods for inhibiting system sleep.

DBUS Object Path: /org/gnome/PowerManager/Inhibit

InhibitAuto()

Inhibits the computer from performing the idle sleep action. Useful if you want to do an operation of long duration without the computer suspending. Requests a cookie which is used for inhibiting an action.

A cookie is a random 32bit unsigned integer used to identify the inhibit. It is required as the same application may want to call inhibit multiple times, without managing the inhibit calls itself.

DirectionTypeDescription
instringthe application name, e.g. "nautilus"
instringthe localized reason to inhibit, e.g. "Copying files"
outunsigned integerthe cookie

InhibitManual()

Inhibits the computer from performing the any sleep or shutdown action. Useful if you want to perform an operation that cannot be interrupted like a firmware re-flash or RPM transaction.

DirectionTypeDescription
instringthe application name, e.g. "rpm"
instringthe localized reason to inhibit, e.g. "performing transaction"
outunsigned integerthe cookie

UnInhibit()

Allows the computer to perform the idle sleep or user action is the number of inhibit calls is zero. If there are multiple cookies outstanding, clearing one cookie does not allow the action to happen. If the program holding the cookie exits from the system bus without calling UnInhibit() then it is automatically removed.

DirectionTypeDescription
inunsigned integerthe cookie

IsValid()

Returns true if the auto-suspend functionality would be valid. This will return false if the number of inhibit cookies is greater than zero.

DirectionTypeDescription
outbooleanIf the auto-sleep is valid

IsValidChanged

Signals the valid state has changed.

DirectionTypeDescription
outbooleanIf the auto-sleep is valid

Actions Control

This path control the session policy and provides a way to trigger actions for other programs. Using the session methods rather than the system HAL methods provides the sleep-notification features and also enables other security features, such as forgetting session keys on suspend. These are the required DBUS methods for controlling system actions.

The AllowedFoo methods check if the current user in the session is able to suspend, and has permission to do so. This may also fail if the admin has locked down the session or system action or if the computer cannot do the action due to a hardware limitation.

DBUS Object Path: /org/gnome/PowerManager/Control

Suspend()

This call will attempt to suspend the system.

Hibernate()

This call will attempt to hibernate the system.

Shutdown()

This call will attempt to shutdown the system.

Reboot()

This call will attempt to reboot the system.

AllowedSuspend()

If the current user in the session is able to suspend.

DirectionTypeDescription
outbooleanIf we are able to suspend

AllowedHibernate()

If the current user in the session is able to hibernate.

DirectionTypeDescription
outbooleanIf we are able to hibernate

AllowedShutdown()

If the current user in the session is able to shutdown.

DirectionTypeDescription
outbooleanIf we are able to shutdown

AllowedReboot()

If the current user in the session is able to reboot.

DirectionTypeDescription
outbooleanIf we are able to reboot

Register()

Registers a program that wants notification and veto on any system actions, such as suspending and shutdown.

This provides programs with information so they can do certain operations, such as flush passwords on suspend or disconnect from network shares.

NOTE: The power manager may disregard the Register() call in some situations such as critically low power conditions.

DirectionTypeDescription
instringthe application name, e.g. "networkmanager-applet"
outunsigned integerthe cookie

UnRegister()

Removes the request on the power notification. If the program holding the cookie exits from the system bus without calling UnRegister() then it is automatically removed.

DirectionTypeDescription
inunsigned integerthe cookie

Request

Signals that a system power action is required. This signal can only be actioned by clients holding a Register() cookie.

NOTE: Applications that fail to respond in a set time (typically one second) may be ignored.

DirectionTypeDescription
outstringThe system action, e.g. suspend

Policy()

Calling this method provides the power manager with a policy decision after the Request signal has been received. Applications should not respond with a negative response just because they are working - only use the negative return value to indicate that an operation cannot be safely be interrupted, such as saving a file to a network share.

DirectionTypeDescription
inunsigned integerthe cookie
inbooleanif the action is allowed

Statistics Data

Statistics data is values that can be collected by the power manager for review or profiling. These are important (but not required) methods allow the profiling of power saving methods, for instance showing on a graph that 20% more power is saved using certain CPU schedulers. These are optional DBUS methods for getting system statistics.

DBUS Object Path: /org/gnome/PowerManager/Statistics

GetDataTypes()

Gets a list of the types of data available. Data types are single strings that represent the complete data and do not indicate the axis.

DirectionTypeDescription
outlist of strings [as]The types of data we support, e.g. [ 'voltage', 'power', 'percentage' ]

GetAxisTypes()

For some presentations, for example graphs we can present the data in many different ways. This method returns the type of data that is recorded for each axis.

DirectionTypeDescription
instring The type of data (and entry from GetDataTypes())
outstringX axis type, e.g. percentage
outstringY axis type, e.g. rate

GetData()

Gets the data for a given type.

DirectionTypeDescription
inintegerThe number of seconds of data we should return
instringThe type of data we want
outarray of 3-integers [a(iii)] The data, where the 3-integers represent the X value, Y value and data value respectively.