File indexing completed on 2024-04-21 14:56:11
0001 /* 0002 Copyright 2006-2007 Kevin Ottens <ervin@kde.org> 0003 Copyright 2013 Lukas Tinkl <ltinkl@redhat.com> 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Lesser General Public 0007 License as published by the Free Software Foundation; either 0008 version 2.1 of the License, or (at your option) version 3, or any 0009 later version accepted by the membership of KDE e.V. (or its 0010 successor approved by the membership of KDE e.V.), which shall 0011 act as a proxy defined in Section 6 of version 3 of the license. 0012 0013 This library is distributed in the hope that it will be useful, 0014 but WITHOUT ANY WARRANTY; without even the implied warranty of 0015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0016 Lesser General Public License for more details. 0017 0018 You should have received a copy of the GNU Lesser General Public 0019 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0020 */ 0021 0022 #ifndef SOLID_POWERMANAGEMENT_H 0023 #define SOLID_POWERMANAGEMENT_H 0024 0025 #include <QObject> 0026 #include <QSet> 0027 0028 #include <kdelibs4support_export.h> 0029 0030 namespace Solid 0031 { 0032 /** 0033 * This namespace allows to query the underlying system to obtain information 0034 * about the hardware available. 0035 * 0036 * It is the single entry point for power management. Applications should use 0037 * it to control or query the power management features of the system. 0038 * 0039 * Note that it's implemented as a singleton and encapsulates the backend logic. 0040 * 0041 * @author Kevin Ottens <ervin@kde.org> 0042 */ 0043 namespace PowerManagement 0044 { 0045 /** 0046 * This enum type defines the different suspend methods. 0047 * 0048 * - StandbyState: Processes are stopped, some hardware is deactivated (ACPI S1) 0049 * - SuspendState: Most devices are deactivated, only RAM is powered (ACPI S3) 0050 * - HibernateState: State of the machine is saved to disk, and the machine is powered down (ACPI S4) 0051 * - HybridSleepState: The contents of RAM are first copied to non-volatile storage like for regular hibernation, 0052 * but then, instead of powering down, the computer enters sleep mode 0053 */ 0054 enum SleepState { StandbyState = 1, SuspendState = 2, HibernateState = 4, 0055 /// @since 4.11 0056 HybridSuspendState = 8 0057 }; 0058 0059 /** 0060 * Retrieves a high level indication of how applications should behave according to the 0061 * power management subsystem. For example, when on battery power, this method will return 0062 * true. 0063 * 0064 * @return whether apps should conserve power 0065 */ 0066 KDELIBS4SUPPORT_DEPRECATED_EXPORT bool appShouldConserveResources(); 0067 0068 /** 0069 * Retrieves the set of suspend methods supported by the system. 0070 * 0071 * @return the suspend methods supported by this system 0072 * @see Solid::PowerManagement::SleepState 0073 */ 0074 KDELIBS4SUPPORT_DEPRECATED_EXPORT QSet<SleepState> supportedSleepStates(); 0075 0076 /** 0077 * Requests that the system go to sleep 0078 * 0079 * @param state the sleep state use 0080 * @param receiver the object to call a slot on once the operation completes 0081 * @param member the slot to call 0082 */ 0083 KDELIBS4SUPPORT_DEPRECATED_EXPORT void requestSleep(SleepState state, QObject *receiver, const char *member); 0084 0085 /** 0086 * Tell the power management subsystem to suppress automatic system sleep until further 0087 * notice. 0088 * 0089 * @param reason Give a reason for not allowing sleep, to be used in giving user feedback 0090 * about why a sleep event was prevented 0091 * @return a 'cookie' value representing the suppression request. Used by the power manager to 0092 * track the application's outstanding suppression requests. Returns -1 if the request was 0093 * denied. 0094 */ 0095 KDELIBS4SUPPORT_DEPRECATED_EXPORT int beginSuppressingSleep(const QString &reason = QString()); 0096 0097 /** 0098 * Tell the power management that a particular sleep suppression is no longer needed. When 0099 * no more suppressions are active, the system will be free to sleep automatically 0100 * @param cookie The cookie acquired when requesting sleep suppression 0101 * @return true if the suppression was stopped, false if an invalid cookie was given 0102 */ 0103 KDELIBS4SUPPORT_DEPRECATED_EXPORT bool stopSuppressingSleep(int cookie); 0104 0105 /** 0106 * Tell the power management subsystem to suppress automatic screen power management until 0107 * further notice. 0108 * 0109 * @param reason Give a reason for not allowing screen power management, to be used in giving user feedback 0110 * about why a screen power management event was prevented 0111 * @return a 'cookie' value representing the suppression request. Used by the power manager to 0112 * track the application's outstanding suppression requests. Returns -1 if the request was 0113 * denied. 0114 * 0115 * @since 4.6 0116 */ 0117 KDELIBS4SUPPORT_DEPRECATED_EXPORT int beginSuppressingScreenPowerManagement(const QString &reason = QString()); 0118 0119 /** 0120 * Tell the power management that a particular screen power management suppression is no longer needed. When 0121 * no more suppressions are active, the system will be free to handle screen power management automatically 0122 * @param cookie The cookie acquired when requesting screen power management suppression 0123 * @return true if the suppression was stopped, false if an invalid cookie was given 0124 * 0125 * @note Since 4.8, this function also inhibits screensaver 0126 * 0127 * @since 4.6 0128 */ 0129 KDELIBS4SUPPORT_DEPRECATED_EXPORT bool stopSuppressingScreenPowerManagement(int cookie); 0130 0131 class KDELIBS4SUPPORT_DEPRECATED_EXPORT Notifier : public QObject 0132 { 0133 Q_OBJECT 0134 Q_SIGNALS: 0135 /** 0136 * This signal is emitted when the AC adapter is plugged or unplugged. 0137 * 0138 * @param newState whether the system runs on battery 0139 */ 0140 void appShouldConserveResourcesChanged(bool newState); 0141 0142 /** 0143 * This signal is emitted whenever the system is resuming from suspend. Applications should connect 0144 * to this signal to perform actions due after a wake up (such as updating clocks, etc.). 0145 * 0146 * @since 4.7 0147 */ 0148 void resumingFromSuspend(); 0149 0150 protected: 0151 Notifier(); 0152 }; 0153 0154 KDELIBS4SUPPORT_DEPRECATED_EXPORT Notifier *notifier(); 0155 } 0156 } 0157 0158 #endif