workspace/libs/solid/control/powermanager.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2006-2007 Kevin Ottens <ervin@kde.org>
   3     Copyright (C) 2008 Dario Freddi <drf54321@gmail.com>
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Library General Public
   7     License version 2 as published by the Free Software Foundation.
   8
   9     This library is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12     Library General Public License for more details.
  13
  14     You should have received a copy of the GNU Library General Public License
  15     along with this library; see the file COPYING.LIB.  If not, write to
  16     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17     Boston, MA 02110-1301, USA.
  18
  19 */
  20
  21 #ifndef SOLID_CONTROL_POWERMANAGER_H
  22 #define SOLID_CONTROL_POWERMANAGER_H
  23
  24 #include <QtCore/QObject>
  25 #include <QtCore/QHash>
  26
  27 #include "solid_control_export.h"
  28
  29 class KJob;
  30
  31 namespace Solid
  32 {
  33 namespace Control
  34 {
  35     /**
  36      * This namespace allows to query the underlying system to obtain information
  37      * about the hardware available.
  38      *
  39      * It's the unique entry point for power management. Applications should use
  40      * it to control or query the power management features of the system.
  41      *
  42      * Note that it's implemented as a singleton and encapsulates the backend logic.
  43      *
  44      * @author Kevin Ottens <ervin@kde.org>
  45      */
  46     namespace PowerManager
  47     {
  48        /**
  49          * This enum type defines the different states of the system battery.
  50          *
  51          * - NoBatteryState: No battery available
  52          * - Normal: The battery is at its normal charge level
  53          * - Warning: The battery is at its warning charge level
  54          * - Low: The battery is at its low charge level
  55          * - Critical: The battery is at its critical charge level
  56          */
  57         enum BatteryState{ NoBatteryState, Normal, Warning, Low, Critical };
  58
  59         /**
  60          * This enum type defines the different states of the AC adapter.
  61          *
  62          * - UnknownAcAdapterState: The AC adapter has an unknown state
  63          * - Plugged: The AC adapter is plugged
  64          * - Unplugged: The AC adapter is unplugged
  65          */
  66         enum AcAdapterState{ UnknownAcAdapterState, Plugged, Unplugged };
  67
  68         /**
  69          * This enum type defines the types of system button events.
  70          *
  71          * - UnknownButtonType: An unknown button
  72          * - PowerButton: A power button pressed event, generally used to turn on or off the system
  73          * - SleepButton: A sleep button pressed event, generally used to make the system asleep
  74          * - LidOpen: A laptop lid open event
  75          * - LidClose: A laptop lid close event
  76          */
  77         enum ButtonType{ UnknownButtonType, PowerButton, SleepButton, LidOpen, LidClose };
  78
  79         /**
  80          * This enum type defines the different suspend methods.
  81          *
  82          * - UnknownSuspendMethod: The name says it all
  83          * - Standby: Processes are stopped, some hardware is deactivated (ACPI S1)
  84          * - ToRam: Most devices are deactivated, only RAM is powered (ACPI S3)
  85          * - ToDisk: State of the machine is saved to disk, and it's powered down (ACPI S4)
  86          */
  87         enum SuspendMethod{ UnknownSuspendMethod = 0, Standby = 1, ToRam = 2, ToDisk = 4};
  88
  89         /**
  90          * This type stores an OR combination of SuspendMethod values.
  91          */
  92         Q_DECLARE_FLAGS(SuspendMethods, SuspendMethod)
  93
  94         /**
  95          * This enum type defines the different CPU frequency policies.
  96          *
  97          * - UnknownCpuFreqPolicy: The name says it all
  98          * - OnDemand: Frequency is changed by the kernel depending on the processor load
  99          * - Conservative: Frequency is changed by the kernel depending on the processor load; the stepping is less aggressive than OnDemand.  This may be equivalent to OnDemand depending on the operating system.
 100          * - Userspace: Frequency is changed by a userspace agent depending on the processor load
 101          * - Powersave: Frequency is always set to the lowest available
 102          * - Performance: Frequency is always set to the highest available
 103          */
 104         enum CpuFreqPolicy{ UnknownCpuFreqPolicy = 0, OnDemand = 1, Userspace = 2, Powersave = 4, Performance = 8, Conservative = 16 };
 105
 106         /**
 107          * This type stores an OR combination of CpuFreqPolicy values.
 108          */
 109         Q_DECLARE_FLAGS(CpuFreqPolicies, CpuFreqPolicy)
 110
 111         /**
 112          * This enum defines the different types of brightness controls.
 113          *
 114          * - UnknownBrightnessControl: Unknown
 115          * - Screen: Brightness control for a monitor or laptop panel
 116          * - Keyboard: Brightness control for a keyboard backlight
 117          */
 118         enum BrightnessControlType{ UnknownBrightnessControl = 0, Screen = 1, Keyboard = 2 };
 119
 120         typedef QHash<QString, BrightnessControlType> BrightnessControlsList;
 121
 122
 123         /**
 124          * Retrieves the list of power management schemes available on this system.
 125          *
 126          * @return the available power management schemes
 127          */
 128         SOLIDCONTROL_EXPORT QStringList supportedSchemes();
 129
 130         /**
 131          * Retrieves a localized description corresponding to the given scheme.
 132          *
 133          * @param schemeName the name of the scheme we request the description for
 134          * @return the associated description
 135          */
 136         SOLIDCONTROL_EXPORT QString schemeDescription(const QString &schemeName);
 137
 138         /**
 139          * Retrieves the name of the current power management scheme used
 140          * by the system.
 141          *
 142          * @return the current scheme
 143          */
 144         SOLIDCONTROL_EXPORT QString scheme();
 145
 146         /**
 147          * Changes the current power management scheme.
 148          *
 149          * @param name the name of the new scheme
 150          * @return true if the scheme change succeeded, false otherwise
 151          */
 152         SOLIDCONTROL_EXPORT bool setScheme(const QString &name);
 153
 154
 155         /**
 156          * Retrieves the current state of the system battery.
 157          *
 158          * @return the current battery state
 159          * @see Solid::Control::PowerManager::BatteryState
 160          */
 161         SOLIDCONTROL_EXPORT BatteryState batteryState();
 162
 163         /**
 164          * Retrieves the current charge percentage of the system batteries.
 165          *
 166          * @return the current global battery charge percentage
 167          */
 168         SOLIDCONTROL_EXPORT int batteryChargePercent();
 169
 170         /**
 171          * Retrieves the current estimated remaining time of the system batteries
 172          *
 173          * @return the current global estimated remaining time in milliseconds
 174          */
 175         SOLIDCONTROL_EXPORT int batteryRemainingTime();
 176
 177         /**
 178          * Retrieves the current state of the system AC adapter.
 179          *
 180          * @return the current AC adapter state
 181          * @see Solid::Control::PowerManager::AcAdapterState
 182          */
 183         SOLIDCONTROL_EXPORT AcAdapterState acAdapterState();
 184
 185
 186         /**
 187          * Retrieves the set of suspend methods supported by the system.
 188          *
 189          * @return the suspend methods supported by this system
 190          * @see Solid::Control::PowerManager::SuspendMethod
 191          * @see Solid::Control::PowerManager::SuspendMethods
 192          */
 193         SOLIDCONTROL_EXPORT SuspendMethods supportedSuspendMethods();
 194
 195         /**
 196          * Requests a suspend of the system.
 197          *
 198          * @param method the suspend method to use
 199          * @return the job handling the operation
 200          */
 201         SOLIDCONTROL_EXPORT KJob *suspend(SuspendMethod method);
 202
 203
 204         /**
 205          * Retrieves the set of CPU frequency policies supported by the system.
 206          *
 207          * @return the CPU frequency policies supported by this system
 208          * @see Solid::Control::PowerManager::CpuFreqPolicy
 209          * @see Solid::Control::PowerManager::CpuFreqPolicies
 210          */
 211         SOLIDCONTROL_EXPORT CpuFreqPolicies supportedCpuFreqPolicies();
 212
 213         /**
 214          * Retrieves the current CPU frequency policy of the system.
 215          *
 216          * @return the current CPU frequency policy used by the system
 217          * @see Solid::Control::PowerManager::CpuFreqPolicy
 218          */
 219         SOLIDCONTROL_EXPORT CpuFreqPolicy cpuFreqPolicy();
 220
 221         /**
 222          * Changes the current CPU frequency policy of the system.
 223          *
 224          * @param newPolicy the new policy
 225          * @return true if the policy change succeeded, false otherwise
 226          * @see Solid::Control::PowerManager::CpuFreqPolicy
 227          */
 228         SOLIDCONTROL_EXPORT bool setCpuFreqPolicy(CpuFreqPolicy newPolicy);
 229
 230         /**
 231          * Checks if a CPU can be disabled.
 232          *
 233          * @param cpuNum the number of the CPU we want to check
 234          * @return true if the given CPU can be disabled, false otherwise
 235          */
 236         SOLIDCONTROL_EXPORT bool canDisableCpu(int cpuNum);
 237
 238         /**
 239          * Enables or disables a CPU.
 240          *
 241          * @param cpuNum the number of the CPU we want to enable or disable
 242          * @param enabled the new state of the CPU
 243          * @return true if the state change succeeded, false otherwise
 244          */
 245         SOLIDCONTROL_EXPORT bool setCpuEnabled(int cpuNum, bool enabled);
 246
 247         /**
 248          * Checks if brightness controls are enabled on this system.
 249          *
 250          * @return a list of the devices available to control
 251          */
 252         SOLIDCONTROL_EXPORT BrightnessControlsList brightnessControlsAvailable();
 253
 254         /**
 255          * Gets the screen brightness.
 256          *
 257          * @param device the name of the device that you would like to control
 258          * @return the brightness of the device, as a percentage
 259          */
 260         SOLIDCONTROL_EXPORT float brightness(const QString &device = QString());
 261
 262         /**
 263          * Sets the screen brightness.
 264          *
 265          * @param brightness the desired screen brightness, as a percentage
 266          * @param device the name of the device that you would like to control
 267          * @return true if the brightness change succeeded, false otherwise
 268          */
 269         SOLIDCONTROL_EXPORT bool setBrightness(float brightness, const QString &device = QString());
 270
 271         class SOLIDCONTROL_EXPORT Notifier : public QObject
 272         {
 273             Q_OBJECT
 274         Q_SIGNALS:
 275             /**
 276              * This signal is emitted when the power management scheme has changed.
 277              *
 278              * @param newScheme the new scheme name
 279              */
 280             void schemeChanged(QString newScheme);
 281
 282             /**
 283              * This signal is emitted when the AC adapter is plugged or unplugged.
 284              *
 285              * @param newState the new state of the AC adapter, it's one of the
 286              * type @see Solid::Control::PowerManager::AcAdapterState
 287              */
 288             void acAdapterStateChanged(int newState);
 289
 290             /**
 291              * This signal is emitted when the system battery state changed.
 292              *
 293              * @param newState the new state of the system battery, it's one of the
 294              * type @see Solid::Control::PowerManager::BatteryState
 295              */
 296             void batteryStateChanged(int newState);
 297
 298             /**
 299              * This signal is emitted when a button has been pressed.
 300              *
 301              * @param buttonType the pressed button type, it's one of the
 302              * type @see Solid::Control::PowerManager::ButtonType
 303              */
 304             void buttonPressed(int buttonType);
 305
 306             /**
 307              * This signal is emitted when the brightness changes.
 308              *
 309              * @param brightness the new brightness level
 310              */
 311              void brightnessChanged(float brightness);
 312
 313             /**
 314              * This signal is emitted when the estimated battery remaining time changes.
 315              *
 316              * @param brightness the new remaining time
 317              */
 318              void batteryRemainingTimeChanged(int time);
 319         };
 320
 321         SOLIDCONTROL_EXPORT Notifier *notifier();
 322     }
 323 }
 324 }
 325
 326 Q_DECLARE_OPERATORS_FOR_FLAGS(Solid::Control::PowerManager::SuspendMethods)
 327 Q_DECLARE_OPERATORS_FOR_FLAGS(Solid::Control::PowerManager::CpuFreqPolicies)
 328
 329 #endif