1 /*************************************************************************** 2 * Copyright (C) 2010 by Dario Freddi <drf@kde.org> * 3 * * 4 * This program is free software; you can redistribute it and/or modify * 5 * it under the terms of the GNU General Public License as published by * 6 * the Free Software Foundation; either version 2 of the License, or * 7 * (at your option) any later version. * 8 * * 9 * This program 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 * 12 * GNU General Public License for more details. * 13 * * 14 * You should have received a copy of the GNU General Public License * 15 * along with this program; if not, write to the * 16 * Free Software Foundation, Inc., * 17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA . * 18 ***************************************************************************/ 19 20 21 #ifndef POWERDEVIL_BACKENDINTERFACE_H 22 #define POWERDEVIL_BACKENDINTERFACE_H 23 24 #include <QObject> 25 #include <QHash> 26 27 #include "powerdevilbrightnesslogic.h" 28 29 class KJob; 30 31 namespace PowerDevil { 32 33 class Q_DECL_EXPORT BackendInterface : public QObject 34 { 35 Q_OBJECT 36 Q_DISABLE_COPY(BackendInterface) 37 38 public: 39 explicit BackendInterface(QObject* parent = nullptr); 40 ~BackendInterface() override; 41 42 /** 43 * This enum type defines the different states of the system battery. 44 * 45 * - NoBatteryState: No battery available 46 * - Normal: The battery is at its normal charge level 47 * - Warning: The battery is at its warning charge level 48 * - Low: The battery is at its low charge level 49 * - Critical: The battery is at its critical charge level 50 */ 51 enum BatteryState{ NoBatteryState, Normal, Warning, Low, Critical }; 52 Q_ENUM(BatteryState) 53 54 /** 55 * This enum type defines the different states of the AC adapter. 56 * 57 * - UnknownAcAdapterState: The AC adapter has an unknown state 58 * - Plugged: The AC adapter is plugged 59 * - Unplugged: The AC adapter is unplugged 60 */ 61 enum AcAdapterState{ UnknownAcAdapterState, Plugged, Unplugged }; 62 Q_ENUM(AcAdapterState) 63 64 /** 65 * This enum type defines the types of system button events. 66 * 67 * - UnknownButtonType: An unknown button 68 * - PowerDown: A power down pressed event, generally used to turn on or off the system. KWin emits on long power button presses. 69 * - PowerButton: A power button pressed event, generally used to turn on or off the system 70 * - SleepButton: A sleep button pressed event, generally used to make the system asleep 71 * - LidOpen: A laptop lid open event 72 * - LidClose: A laptop lid close event 73 */ 74 enum ButtonType{ UnknownButtonType, PowerButton, PowerDownButton, SleepButton, LidOpen, LidClose, HibernateButton }; 75 Q_ENUM(ButtonType) 76 77 /** 78 * This enum type defines the different suspend methods. 79 * 80 * - UnknownSuspendMethod: The name says it all 81 * - Standby: Processes are stopped, some hardware is deactivated (ACPI S1) 82 * - ToRam: Most devices are deactivated, only RAM is powered (ACPI S3) 83 * - ToDisk: State of the machine is saved to disk, and it's powered down (ACPI S4) 84 * - SuspendThenHibernate: Same as ToRam, but after a delay it switches to ToDisk 85 */ 86 enum SuspendMethod{ UnknownSuspendMethod = 0, Standby = 1, ToRam = 2, ToDisk = 4, HybridSuspend = 8, SuspendThenHibernate = 16 }; 87 Q_ENUM(SuspendMethod) 88 89 /** 90 * This type stores an OR combination of SuspendMethod values. 91 */ 92 Q_DECLARE_FLAGS(SuspendMethods, SuspendMethod) 93 94 /** 95 * This enum defines the different types of brightness controls. 96 * 97 * - UnknownBrightnessControl: Unknown 98 * - Screen: Brightness control for a monitor or laptop panel 99 * - Keyboard: Brightness control for a keyboard backlight 100 */ 101 enum BrightnessControlType{ UnknownBrightnessControl = 0, Screen = 1, Keyboard = 2 }; 102 Q_ENUM(BrightnessControlType) 103 104 typedef QHash<QString, BrightnessControlType> BrightnessControlsList; 105 106 /** 107 * This enum defines capabilities of the backend 108 * 109 * - SignalResumeFromSuspend: The backend is able to stream the @c resumeFromSuspend signal accurately 110 */ 111 enum Capability { NoCapabilities = 0, SignalResumeFromSuspend = 1 }; 112 Q_ENUM(Capability) 113 114 Q_DECLARE_FLAGS(Capabilities, Capability) 115 116 /** 117 * Initializes the backend. This function @b MUST be called before the backend is usable. Using 118 * any method in BackendInterface without initializing it might lead to undefined behavior. The signal 119 * @c backendReady or @c backendError will be streamed upon completion. 120 * 121 * @note Backend implementations @b MUST reimplement this function 122 */ 123 virtual void init() = 0; 124 125 /** 126 * @returns the capabilities of the backend 127 * @see PowerDevil::BackendInterface::Capability 128 */ 129 Capabilities capabilities() const; 130 131 /** 132 * Retrieves the current state of the system battery. 133 * 134 * @return the current battery state 135 * @see PowerDevil::BackendInterface::BatteryState 136 */ 137 BatteryState batteryState() const; 138 139 /** 140 * Retrieves the current estimated remaining time of the system batteries 141 * 142 * @return the current global estimated remaining time in milliseconds 143 */ 144 qulonglong batteryRemainingTime() const; 145 146 /** 147 * Retrieves the current state of the system AC adapter. 148 * 149 * @return the current AC adapter state 150 * @see PowerDevil::BackendInterface::AcAdapterState 151 */ 152 AcAdapterState acAdapterState() const; 153 154 /** 155 * Retrieves the set of suspend methods supported by the system. 156 * 157 * @return the suspend methods supported by this system 158 * @see PowerDevil::BackendInterface::SuspendMethod 159 * @see PowerDevil::BackendInterface::SuspendMethods 160 */ 161 SuspendMethods supportedSuspendMethods() const; 162 163 /** 164 * Requests a suspend of the system. 165 * 166 * @param method the suspend method to use 167 * @return the job handling the operation 168 */ 169 virtual KJob *suspend(SuspendMethod method) = 0; 170 171 /** 172 * Checks if brightness controls are enabled on this system. 173 * 174 * @return a list of the devices available to control 175 */ 176 BrightnessControlsList brightnessControlsAvailable() const; 177 178 /** 179 * Gets the device brightness value. 180 * 181 * @param device the name of the device that you would like to control 182 * @return the brightness of the device, as an integer from 0 to brightnessValueMax 183 */ 184 virtual int brightness(BrightnessControlType type = Screen) const; 185 186 /** 187 * Gets the maximum device brightness value. 188 * 189 * @param device the name of the device that you would like to control 190 * @return the maximum brightness of the device 191 */ 192 virtual int brightnessMax(BrightnessControlType type = Screen) const; 193 194 /** 195 * Gets the maximum device brightness step. 196 * 197 * @param device the name of the device that you would like to control 198 * @return the maximum brightness of the device 199 */ 200 virtual int brightnessSteps(BrightnessControlType type = Screen) const; 201 202 /** 203 * @returns whether the lid is closed or not. 204 */ 205 bool isLidClosed() const; 206 /** 207 * @returns whether the a lid is present 208 */ 209 bool isLidPresent() const; 210 211 void setLidPresent(bool present); 212 213 /** 214 * Sets the device brightness value. 215 * 216 * @param brightnessValue the desired device brightness, as an integer from 0 to brightnessValueMax 217 * @param device the name of the device that you would like to control 218 * @return true if the brightness change succeeded, false otherwise 219 */ 220 virtual void setBrightness(int value, BrightnessControlType type = Screen) = 0; 221 222 /** 223 * Should be called when the user presses a brightness key. 224 * 225 * @param type the type of the brightness key press 226 * @return the new brightness value, or -1 if it could not be changed or determined 227 * @see PowerDevil::BrightnessLogic::BrightnessKeyType 228 */ 229 virtual int brightnessKeyPressed(BrightnessLogic::BrightnessKeyType type, BrightnessControlType controlType = Screen) = 0; 230 231 /** 232 * Retrieves the capacities of the installed batteries in percentage. 233 * 234 * @returns A dictionary with the battery's capacity percentage mapped to the battery uuid. 235 */ 236 QHash<QString, uint> capacities() const; 237 238 Q_SIGNALS: 239 /** 240 * This signal is emitted when the AC adapter is plugged or unplugged. 241 * 242 * @param newState the new state of the AC adapter, it's one of the 243 * type @see PowerDevil::BackendInterface::AcAdapterState 244 */ 245 void acAdapterStateChanged(PowerDevil::BackendInterface::AcAdapterState newState); 246 247 /** 248 * This signal is emitted when the system battery state changed. 249 * 250 * @param newState the new state of the system battery, it's one of the 251 * type @see PowerDevil::BackendInterface::BatteryState 252 */ 253 void batteryStateChanged(PowerDevil::BackendInterface::BatteryState newState); 254 255 /** 256 * This signal is emitted when a button has been pressed. 257 * 258 * @param buttonType the pressed button type, it's one of the 259 * type @see PowerDevil::BackendInterface::ButtonType 260 */ 261 void buttonPressed(PowerDevil::BackendInterface::ButtonType buttonType); 262 263 /** 264 * This signal is emitted when the brightness changes. 265 * 266 * @param brightnessInfo a copy of the current brightness information 267 * @param type the device type 268 */ 269 void brightnessChanged(const BrightnessLogic::BrightnessInfo &brightnessInfo, BrightnessControlType type); 270 271 /** 272 * This signal is emitted when the estimated battery remaining time changes. 273 * 274 * @param time the new remaining time 275 */ 276 void batteryRemainingTimeChanged(qulonglong time); 277 278 /** 279 * This signal is emitted when the backend is ready to be used 280 * 281 * @see init 282 */ 283 void backendReady(); 284 285 /** 286 * This signal is emitted if the backend could not be initialized 287 * 288 * @param error Details about the error occurred 289 * @see init 290 */ 291 void backendError(const QString &error); 292 293 /** 294 * This signal is emitted when the PC is resuming from suspension 295 */ 296 void resumeFromSuspend(); 297 298 /** 299 * This signal is emitted when the PC is about to suspend 300 */ 301 void aboutToSuspend(); 302 303 /** 304 * This signal is emitted when the laptop lid is closed or opened 305 * 306 * @param closed Whether the lid is now closed or not 307 */ 308 void lidClosedChanged(bool closed); 309 310 protected: 311 void setCapabilities(Capabilities capabilities); 312 313 void onBrightnessChanged(BrightnessControlType device, int value, int valueMax); 314 void setBatteryRemainingTime(qulonglong time); 315 void setButtonPressed(PowerDevil::BackendInterface::ButtonType type); 316 void setBatteryState(PowerDevil::BackendInterface::BatteryState state); 317 void setAcAdapterState(PowerDevil::BackendInterface::AcAdapterState state); 318 319 void setCapacityForBattery(const QString &batteryId, uint percent); 320 321 void setBackendIsReady(BrightnessControlsList availableBrightnessControls, SuspendMethods supportedSuspendMethods); 322 void setBackendHasError(const QString &errorDetails); 323 324 // Steps logic 325 int calculateNextStep(int value, int valueMax, BrightnessControlType controlType, BrightnessLogic::BrightnessKeyType type); 326 327 private: 328 class Private; 329 Private * const d; 330 331 friend class Core; 332 }; 333 334 } 335 336 Q_DECLARE_OPERATORS_FOR_FLAGS(PowerDevil::BackendInterface::Capabilities) 337 Q_DECLARE_OPERATORS_FOR_FLAGS(PowerDevil::BackendInterface::SuspendMethods) 338 339 #endif // POWERDEVIL_BACKENDINTERFACE_H 340