Table of Contents
This API is currently unstable and is likely to change in the future.
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 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 |
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.
Direction | Type | Description |
---|---|---|
in | unsigned integer | Percentage brightness |
Returns the DPMS mode state.
Direction | Type | Description |
---|---|---|
out | unsigned integer | Percentage brightness |
Signals the value of the current DPMS state has changed.
Direction | Type | Description |
---|---|---|
out | unsigned integer | Percentage brightness |
These are the optional DBUS methods for controlling the power saving of the backlight of the current screen. These correspond to Xorg DPMS states:
Mode | Description |
---|---|
on | 100% power usage |
standby | <50% power usage |
suspend | <20% power usage |
off | <5% power usage |
Direction | Type | Description |
---|---|---|
in | string | Required DPMS mode |
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
Returns the system state description, used commonly as the tooltip for a applet or system tray icon.
Direction | Type | Description |
---|---|---|
out | string | System state description, e.g. Laptop battery 34 minutes until charged (34%) |
Signals the system state description has changed.
Direction | Type | Description |
---|---|---|
out | string | System state description |
Returns the system icon used as the applet or system tray icon.
Direction | Type | Description |
---|---|---|
out | string | Icon name, e.g. gpm-primary-080-charging |
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 |
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.
Direction | Type | Description |
---|---|---|
out | boolean | If the system is using AC power |
Signals the AC state has changed.
Direction | Type | Description |
---|---|---|
out | boolean | If the system is using AC power |
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.
Direction | Type | Description |
---|---|---|
out | boolean | If the session should be run in low power mode |
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
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.
Direction | Type | Description |
---|---|---|
in | string | the application name, e.g. "nautilus" |
in | string | the localized reason to inhibit, e.g. "Copying files" |
out | unsigned integer | the cookie |
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.
Direction | Type | Description |
---|---|---|
in | string | the application name, e.g. "rpm" |
in | string | the localized reason to inhibit, e.g. "performing transaction" |
out | unsigned integer | the cookie |
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.
Direction | Type | Description |
---|---|---|
in | unsigned integer | the cookie |
Returns true if the auto-suspend functionality would be valid. This will return false if the number of inhibit cookies is greater than zero.
Direction | Type | Description |
---|---|---|
out | boolean | If the auto-sleep is valid |
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
If the current user in the session is able to suspend.
Direction | Type | Description |
---|---|---|
out | boolean | If we are able to suspend |
If the current user in the session is able to hibernate.
Direction | Type | Description |
---|---|---|
out | boolean | If we are able to hibernate |
If the current user in the session is able to shutdown.
Direction | Type | Description |
---|---|---|
out | boolean | If we are able to shutdown |
If the current user in the session is able to reboot.
Direction | Type | Description |
---|---|---|
out | boolean | If we are able to reboot |
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.
Direction | Type | Description |
---|---|---|
in | string | the application name, e.g. "networkmanager-applet" |
out | unsigned integer | the cookie |
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.
Direction | Type | Description |
---|---|---|
in | unsigned integer | the cookie |
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.
Direction | Type | Description |
---|---|---|
out | string | The system action, e.g. suspend |
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.
Direction | Type | Description |
---|---|---|
in | unsigned integer | the cookie |
in | boolean | if the action is allowed |
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
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.
Direction | Type | Description |
---|---|---|
out | list of strings [as] | The types of data we support, e.g. [ 'voltage', 'power', 'percentage' ] |
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.
Direction | Type | Description |
---|---|---|
in | string |
The type of data (and entry from GetDataTypes() )
|
out | string | X axis type, e.g. percentage |
out | string | Y axis type, e.g. rate |