← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to powerdevil/daemon/powerdevilbackendinterface.h

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
powerdevil/daemon/powerdevilbackendinterface.h
 
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 <QtCore/QObject>
 
25
#include <QtCore/QHash>
 
26
 
 
27
#include <kdemacros.h>
 
28
 
 
29
class KJob;
 
30
 
 
31
namespace PowerDevil {
 
32
 
 
33
class KDE_EXPORT BackendInterface : public QObject
 
34
{
 
35
    Q_OBJECT
 
36
    Q_DISABLE_COPY(BackendInterface)
 
37
 
 
38
public:
 
39
    explicit BackendInterface(QObject* parent = 0);
 
40
    virtual ~BackendInterface();
 
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
 
 
53
    /**
 
54
     * This enum type defines the different states of the AC adapter.
 
55
     *
 
56
     * - UnknownAcAdapterState: The AC adapter has an unknown state
 
57
     * - Plugged: The AC adapter is plugged
 
58
     * - Unplugged: The AC adapter is unplugged
 
59
     */
 
60
    enum AcAdapterState{ UnknownAcAdapterState, Plugged, Unplugged };
 
61
 
 
62
    /**
 
63
     * This enum type defines the types of system button events.
 
64
     *
 
65
     * - UnknownButtonType: An unknown button
 
66
     * - PowerButton: A power button pressed event, generally used to turn on or off the system
 
67
     * - SleepButton: A sleep button pressed event, generally used to make the system asleep
 
68
     * - LidOpen: A laptop lid open event
 
69
     * - LidClose: A laptop lid close event
 
70
     */
 
71
    enum ButtonType{ UnknownButtonType, PowerButton, SleepButton, LidOpen, LidClose };
 
72
 
 
73
    /**
 
74
     * This enum type defines the different suspend methods.
 
75
     *
 
76
     * - UnknownSuspendMethod: The name says it all
 
77
     * - Standby: Processes are stopped, some hardware is deactivated (ACPI S1)
 
78
     * - ToRam: Most devices are deactivated, only RAM is powered (ACPI S3)
 
79
     * - ToDisk: State of the machine is saved to disk, and it's powered down (ACPI S4)
 
80
     */
 
81
    enum SuspendMethod{ UnknownSuspendMethod = 0, Standby = 1, ToRam = 2, ToDisk = 4, HybridSuspend = 8 };
 
82
 
 
83
    /**
 
84
     * This type stores an OR combination of SuspendMethod values.
 
85
     */
 
86
    Q_DECLARE_FLAGS(SuspendMethods, SuspendMethod)
 
87
 
 
88
    /**
 
89
     * This enum defines the different types of brightness controls.
 
90
     *
 
91
     * - UnknownBrightnessControl: Unknown
 
92
     * - Screen: Brightness control for a monitor or laptop panel
 
93
     * - Keyboard: Brightness control for a keyboard backlight
 
94
     */
 
95
    enum BrightnessControlType{ UnknownBrightnessControl = 0, Screen = 1, Keyboard = 2 };
 
96
 
 
97
    typedef QHash<QString, BrightnessControlType> BrightnessControlsList;
 
98
 
 
99
    /**
 
100
     * This enum defines the different types brightness keys.
 
101
     *
 
102
     * - Increase: Key to increase brightness (Qt::Key_MonBrightnessUp)
 
103
     * - Decrease: Key to decrease brightness (Qt::Key_MonBrightnessDown)
 
104
     */
 
105
    enum BrightnessKeyType{ Increase, Decrease };
 
106
 
 
107
    /**
 
108
     * This enum defines capabilities of the backend
 
109
     *
 
110
     * - SignalResumeFromSuspend: The backend is able to stream the @c resumeFromSuspend signal accurately
 
111
     */
 
112
    enum Capability { NoCapabilities = 0, SignalResumeFromSuspend = 1 };
 
113
 
 
114
    Q_DECLARE_FLAGS(Capabilities, Capability)
 
115
 
 
116
    /**
 
117
     * This struct contains information for a recall notice from the vendor
 
118
     */
 
119
    struct RecallNotice {
 
120
        /** The battery uuid */
 
121
        QString batteryId;
 
122
        /** The vendor's name */
 
123
        QString vendor;
 
124
        /** The vendor's website */
 
125
        QString url;
 
126
    };
 
127
 
 
128
    /**
 
129
     * Initializes the backend. This function @b MUST be called before the backend is usable. Using
 
130
     * any method in BackendInterface without initializing it might lead to undefined behavior. The signal
 
131
     * @c backendReady or @c backendError will be streamed upon completion.
 
132
     *
 
133
     * @note Backend implementations @b MUST reimplement this function
 
134
     */
 
135
    virtual void init() = 0;
 
136
 
 
137
    /**
 
138
     * @returns the capabilities of the backend
 
139
     * @see PowerDevil::BackendInterface::Capability
 
140
     */
 
141
    Capabilities capabilities() const;
 
142
 
 
143
    /**
 
144
     * Retrieves the current state of the system battery.
 
145
     *
 
146
     * @return the current battery state
 
147
     * @see PowerDevil::BackendInterface::BatteryState
 
148
     */
 
149
    BatteryState batteryState() const;
 
150
 
 
151
    /**
 
152
     * Retrieves the current estimated remaining time of the system batteries
 
153
     *
 
154
     * @return the current global estimated remaining time in milliseconds
 
155
     */
 
156
    qulonglong batteryRemainingTime() const;
 
157
 
 
158
    /**
 
159
     * Retrieves the current state of the system AC adapter.
 
160
     *
 
161
     * @return the current AC adapter state
 
162
     * @see PowerDevil::BackendInterface::AcAdapterState
 
163
     */
 
164
    AcAdapterState acAdapterState() const;
 
165
 
 
166
 
 
167
    /**
 
168
     * Retrieves the set of suspend methods supported by the system.
 
169
     *
 
170
     * @return the suspend methods supported by this system
 
171
     * @see PowerDevil::BackendInterface::SuspendMethod
 
172
     * @see PowerDevil::BackendInterface::SuspendMethods
 
173
     */
 
174
    SuspendMethods supportedSuspendMethods() const;
 
175
 
 
176
    /**
 
177
     * Requests a suspend of the system.
 
178
     *
 
179
     * @param method the suspend method to use
 
180
     * @return the job handling the operation
 
181
     */
 
182
    virtual KJob *suspend(SuspendMethod method) = 0;
 
183
 
 
184
    /**
 
185
     * Checks if brightness controls are enabled on this system.
 
186
     *
 
187
     * @return a list of the devices available to control
 
188
     */
 
189
    BrightnessControlsList brightnessControlsAvailable() const;
 
190
 
 
191
    /**
 
192
     * Gets the screen brightness.
 
193
     *
 
194
     * @param device the name of the device that you would like to control
 
195
     * @return the brightness of the device, as a percentage
 
196
     */
 
197
    virtual float brightness(BrightnessControlType type = Screen) const;
 
198
 
 
199
    /**
 
200
     * @returns whether the lid is closed or not.
 
201
     */
 
202
    bool isLidClosed() const;
 
203
 
 
204
    /**
 
205
     * Sets the screen brightness.
 
206
     *
 
207
     * @param brightness the desired screen brightness, as a percentage
 
208
     * @param device the name of the device that you would like to control
 
209
     * @return true if the brightness change succeeded, false otherwise
 
210
     */
 
211
    virtual bool setBrightness(float brightness, BrightnessControlType type = Screen) = 0;
 
212
 
 
213
    /**
 
214
     * Should be called when the user presses a brightness key.
 
215
     *
 
216
     * @param type the type of the brightness key press
 
217
     * @see PowerDevil::BackendInterface::BrightnessKeyType
 
218
     */
 
219
    virtual void brightnessKeyPressed(BrightnessKeyType type) = 0;
 
220
 
 
221
    /**
 
222
     * Retrieves the capacities of the installed batteries in percentage.
 
223
     *
 
224
     * @returns A dictionary with the battery's capacity percentage mapped to the battery uuid.
 
225
     */
 
226
    QHash< QString, uint > capacities() const;
 
227
 
 
228
    /**
 
229
     * Returns a list of recall notices, if available
 
230
     *
 
231
     * @return a list of recall notices
 
232
     * @see PowerDevil::BackendInterface::RecallNotice
 
233
     */
 
234
    QList< RecallNotice > recallNotices() const;
 
235
 
 
236
Q_SIGNALS:
 
237
    /**
 
238
     * This signal is emitted when the AC adapter is plugged or unplugged.
 
239
     *
 
240
     * @param newState the new state of the AC adapter, it's one of the
 
241
     * type @see PowerDevil::BackendInterface::AcAdapterState
 
242
     */
 
243
    void acAdapterStateChanged(PowerDevil::BackendInterface::AcAdapterState newState);
 
244
 
 
245
    /**
 
246
     * This signal is emitted when the system battery state changed.
 
247
     *
 
248
     * @param newState the new state of the system battery, it's one of the
 
249
     * type @see PowerDevil::BackendInterface::BatteryState
 
250
     */
 
251
    void batteryStateChanged(PowerDevil::BackendInterface::BatteryState newState);
 
252
 
 
253
    /**
 
254
     * This signal is emitted when a button has been pressed.
 
255
     *
 
256
     * @param buttonType the pressed button type, it's one of the
 
257
     * type @see PowerDevil::BackendInterface::ButtonType
 
258
     */
 
259
    void buttonPressed(PowerDevil::BackendInterface::ButtonType buttonType);
 
260
 
 
261
    /**
 
262
     * This signal is emitted when the brightness changes.
 
263
     *
 
264
     * @param brightness the new brightness level
 
265
     */
 
266
    void brightnessChanged(float brightness, PowerDevil::BackendInterface::BrightnessControlType type);
 
267
 
 
268
    /**
 
269
     * This signal is emitted when the estimated battery remaining time changes.
 
270
     *
 
271
     * @param time the new remaining time
 
272
     */
 
273
    void batteryRemainingTimeChanged(qulonglong time);
 
274
 
 
275
    /**
 
276
     * This signal is emitted when the backend is ready to be used
 
277
     *
 
278
     * @see init
 
279
     */
 
280
    void backendReady();
 
281
 
 
282
    /**
 
283
     * This signal is emitted if the backend could not be initialized
 
284
     *
 
285
     * @param error Details about the error occurred
 
286
     * @see init
 
287
     */
 
288
    void backendError(const QString &error);
 
289
 
 
290
    /**
 
291
     * This signal is emitted when the PC is resuming from suspension
 
292
     */
 
293
    void resumeFromSuspend();
 
294
 
 
295
protected:
 
296
    void setCapabilities(Capabilities capabilities);
 
297
 
 
298
    void onBrightnessChanged(BrightnessControlType device, float brightness);
 
299
    void setBatteryRemainingTime(qulonglong time);
 
300
    void setButtonPressed(PowerDevil::BackendInterface::ButtonType type);
 
301
    void setBatteryState(PowerDevil::BackendInterface::BatteryState state);
 
302
    void setAcAdapterState(PowerDevil::BackendInterface::AcAdapterState state);
 
303
 
 
304
    void setCapacityForBattery(const QString &batteryId, uint percent);
 
305
    void setRecallNotices(const QList< RecallNotice > &notices);
 
306
 
 
307
    void setBackendIsReady(BrightnessControlsList availableBrightnessControls, SuspendMethods supportedSuspendMethods);
 
308
    void setBackendHasError(const QString &errorDetails);
 
309
 
 
310
protected slots:
 
311
    // This function is actually here due to HAL
 
312
    void setResumeFromSuspend();
 
313
 
 
314
private:
 
315
    class Private;
 
316
    Private * const d;
 
317
 
 
318
    friend class Core;
 
319
};
 
320
 
 
321
}
 
322
 
 
323
Q_DECLARE_OPERATORS_FOR_FLAGS(PowerDevil::BackendInterface::Capabilities)
 
324
Q_DECLARE_OPERATORS_FOR_FLAGS(PowerDevil::BackendInterface::SuspendMethods)
 
325
 
 
326
#endif // POWERDEVIL_BACKENDINTERFACE_H