Renames & Add new properties to QBatteryInfo
[qt:qtsystems.git] / src / systeminfo / qbatteryinfo.cpp
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Copyright (C) 2014 BlackBerry Limited. All rights reserved.
5 ** Contact: http://www.qt-project.org/legal
6 **
7 ** This file is part of the QtSystems module of the Qt Toolkit.
8 **
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** Commercial License Usage
11 ** Licensees holding valid commercial Qt licenses may use this file in
12 ** accordance with the commercial license agreement provided with the
13 ** Software or, alternatively, in accordance with the terms contained in
14 ** a written agreement between you and Digia.  For licensing terms and
15 ** conditions see http://qt.digia.com/licensing.  For further information
16 ** use the contact form at http://qt.digia.com/contact-us.
17 **
18 ** GNU Lesser General Public License Usage
19 ** Alternatively, this file may be used under the terms of the GNU Lesser
20 ** General Public License version 2.1 as published by the Free Software
21 ** Foundation and appearing in the file LICENSE.LGPL included in the
22 ** packaging of this file.  Please review the following information to
23 ** ensure the GNU Lesser General Public License version 2.1 requirements
24 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** In addition, as a special exception, Digia gives you certain additional
27 ** rights.  These rights are described in the Digia Qt LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file.  Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 **
39 ** $QT_END_LICENSE$
40 **
41 ****************************************************************************/
42
43 #include "qbatteryinfo.h"
44
45 #include <QtCore/qnumeric.h>
46
47 #if defined(QT_SIMULATOR)
48 #  include "simulator/qsysteminfo_simulator_p.h"
49 #elif defined(Q_OS_LINUX)
50 #if defined(QT_NO_UPOWER)
51 #include "linux/qbatteryinfo_linux_p.h"
52 #else
53 #include "linux/qbatteryinfo_upower_p.h"
54 #endif
55 #elif defined(Q_OS_WIN)
56 #  include "windows/qbatteryinfo_win_p.h"
57 #elif defined(Q_OS_MAC)
58 #  include "mac/qbatteryinfo_mac_p.h"
59 #else
60 QT_BEGIN_NAMESPACE
61 class QBatteryInfoPrivate
62 {
63 public:
64     QBatteryInfoPrivate(QBatteryInfo *) {}
65     QBatteryInfoPrivate(int batteryIndex, QBatteryInfo *): index(batteryIndex) {}
66
67     int batteryCount() { return -1; }
68     int batteryIndex() { return index; }
69     bool isValid() { return false; }
70     void setBatteryIndex(int batteryIndex) { index = batteryIndex; }
71     int currentFlow() { return 0; }
72     int cycleCount() { return -1; }
73     int maximumCapacity() { return -1; }
74     int remainingCapacity() { return -1; }
75     int remainingChargingTime() { return -1; }
76     int voltage() { return -1; }
77     QBatteryInfo::ChargerType chargerType() { return QBatteryInfo::UnknownCharger; }
78     QBatteryInfo::ChargingState chargingState() { return QBatteryInfo::UnknownChargingState; }
79     QBatteryInfo::LevelStatus levelStatus() { return QBatteryInfo::LevelUnknown; }
80     QBatteryInfo::Health health() { return QBatteryInfo::HealthUnknown; }
81     float temperature() { return qQNaN(); }
82 private:
83     int index;
84 };
85 QT_END_NAMESPACE
86 #endif
87
88 #include <QtCore/qmetaobject.h>
89
90 QT_BEGIN_NAMESPACE
91
92 /*!
93     \class QBatteryInfo
94     \inmodule QtSystemInfo
95     \brief The QBatteryInfo class provides various information about the battery.
96     \ingroup systeminfo
97
98     Note that on some platforms, listening to the signals could lead to a heavy CPU usage. Therefore,
99     you are strongly suggested to disconnect the signals when no longer needed in your application.
100
101     Battery index starts at 0, which indicates the first battery.
102 */
103
104 /*!
105     \enum QBatteryInfo::ChargerType
106     This enum describes the type of charger used.
107
108     \value UnknownCharger           The charger type is unknown, or no charger.
109     \value WallCharger              Using wall (mains) charger.
110     \value USBCharger               Using USB charger when the system cannot differentiate the current.
111     \value VariableCurrentCharger   Using variable current charger such as bicycle or solar.
112 */
113
114 /*!
115     \enum QBatteryInfo::ChargingState
116     This enum describes the charging state:
117
118     \value UnknownChargingState  The charging state is unknown or charging error occured.
119     \value NotCharging           The battery is not charging, i.e. too low charger power.
120     \value Charging              The battery is charging.
121     \value Discharging           The battery is discharging.
122     \value Full                  The battery is fully charged.
123 */
124
125 /*!
126     \enum QBatteryInfo::BatteryStatus
127     This enum describes the status of the battery.
128
129     \value BatteryStatusUnknown      Battery level undetermined.
130     \value BatteryEmpty              Battery is considered be empty and device needs to shut down.
131     \value BatteryLow                Battery level is low and warnings need to be issued to the user.
132     \value BatteryOk                 Battery level is Ok. It is above "Low" but not "Full".
133     \value BatteryFull               Battery is fully charged.
134 */
135
136 /*!
137     \fn void QBatteryInfo::batteryCountChanged(int count);
138
139     This signal is emitted when the number of batteries available has changed to \a count.
140 */
141
142 /*!
143     \fn void QBatteryInfo::chargerTypeChanged(QBatteryInfo::ChargerType type);
144
145     This signal is emitted when the charger has changed to \a type.
146 */
147
148 /*!
149     \fn void QBatteryInfo::chargingStateChanged(int battery, QBatteryInfo::ChargingState state);
150
151     This signal is emitted when the charging state of the \a battery has changed to \a state.
152 */
153
154 /*!
155     \fn void QBatteryInfo::currentFlowChanged(int battery, int flow);
156
157     This signal is emitted when the current flow of the \a battery has changed to \a flow, measured
158     in milliamperes (mA).
159 */
160
161 /*!
162     \fn void QBatteryInfo::remainingCapacityChanged(int battery, int capacity);
163
164     This signal is emitted when the remaining capacity of the \a battery has changed to \a capacity,
165     which is measured in mAh.
166 */
167
168 /*!
169     \fn void QBatteryInfo::remainingChargingTimeChanged(int battery, int seconds);
170
171     This signal is emitted when the remaining charging time of the \a battery has changed to \a seconds.
172 */
173
174 /*!
175     \fn void QBatteryInfo::voltageChanged(int battery, int voltage);
176
177     This signal is emitted when the current voltage of the \a battery has changed to \a voltage,
178     measured in millivolts (mV).
179 */
180
181 /*!
182     \fn void QBatteryInfo::batteryStatusChanged(int battery, QBatteryInfo::BatteryStatus status);
183
184     This signal is emitted when the battery status of the \a battery has changed to \a status.
185 */
186
187 /*!
188     Constructs a QBatteryInfo object with the given \a parent.
189 */
190 QBatteryInfo::QBatteryInfo(QObject *parent)
191     : QObject(parent)
192 #if !defined(QT_SIMULATOR)
193     , d_ptr(new QBatteryInfoPrivate(this))
194 #else
195     , d_ptr(new QBatteryInfoSimulator(this))
196 #endif // QT_SIMULATOR
197
198 {
199 }
200
201 /*!
202     Constructs a QBatteryInfo object with the given \a index and \a parent.
203 */
204 QBatteryInfo::QBatteryInfo(int batteryIndex, QObject *parent)
205     : QObject(parent)
206 #if !defined(QT_SIMULATOR)
207     , d_ptr(new QBatteryInfoPrivate(batteryIndex, this))
208 #else
209     , d_ptr(new QBatteryInfoSimulator(this))
210 #endif // QT_SIMULATOR
211
212 {
213 }
214
215 /*!
216     Destroys the object
217 */
218 QBatteryInfo::~QBatteryInfo()
219 {
220 }
221
222 /*!
223     \property QBatteryInfo::batteryCount
224     \brief The number of the batteries available.
225
226     Returns the number of batteries available, or -1 on error or the information is not available.
227 */
228 int QBatteryInfo::batteryCount() const
229 {
230     return d_ptr->batteryCount();
231 }
232
233 /*!
234  * \brief Get the current battery index
235  * \return The current battery index
236  */
237 int QBatteryInfo::batteryIndex() const
238 {
239     return d_ptr->batteryIndex();
240 }
241
242 /*!
243  * \brief Set the battery index of this instance
244  * \param batteryIndex The new battery index
245  *
246  * Set the battery index of this instance to batteryIndex
247  */
248 void QBatteryInfo::setBatteryIndex(int batteryIndex)
249 {
250     d_ptr->setBatteryIndex(batteryIndex);
251 }
252
253 /*!
254  * Represents the validity of this instance. If false only batteryIndex() will return a valid
255  * value. All other methods will return default/invalid values.
256  */
257 bool QBatteryInfo::isValid() const
258 {
259     return d_ptr->isValid();
260 }
261
262 /*!
263     Returns the current flow of the given \a battery, measured in milliamperes (mA). A positive
264     returned value means discharging, and a negative value means charging. In case of error, or
265     the information if not available, 0 is returned.
266 */
267 int QBatteryInfo::currentFlow() const
268 {
269     return d_ptr->currentFlow();
270 }
271
272 /*!
273  * Returns the current battery level as a percentage. In case of error or the information
274  * is not available, -1 is returned.
275  */
276 int QBatteryInfo::level() const
277 {
278     return d_ptr->level();
279 }
280
281 /*!
282  * Returns the current cycle count of the battery. In case of error or the information
283  * is not available, -1 is returned.
284  */
285 int QBatteryInfo::cycleCount() const
286 {
287     return d_ptr->cycleCount();
288 }
289
290 /*!
291     Returns the maximum capacity of the given \a battery, measured in mAh.
292     If the battery is not found, or the information is not available, -1 is returned.
293 */
294 int QBatteryInfo::maximumCapacity() const
295 {
296     return d_ptr->maximumCapacity();
297 }
298
299 /*!
300     Returns the remaining level of the given \a battery, measured in mAh. If
301     the battery is not found, or the information is not available, -1 is returned.
302
303     To calculate capacity in percentage,
304     (remainingCapacity(0) / maximumCapacity(0)) * 100
305 */
306 int QBatteryInfo::remainingCapacity() const
307 {
308     return d_ptr->remainingCapacity();
309 }
310
311 /*!
312     Returns the remaining charging time needed for \a battery, measured in seconds. If the battery
313     is full or not charging, 0 is returned. If the battery is not found or the information is not
314     available, -1 is returned.
315 */
316 int QBatteryInfo::remainingChargingTime() const
317 {
318     return d_ptr->remainingChargingTime();
319 }
320
321 /*!
322     Returns the voltage of the given \a battery, measured in millivolts (mV). If the battery is not
323     found, or the information is not available, -1 is returned.
324 */
325 int QBatteryInfo::voltage() const
326 {
327     return d_ptr->voltage();
328 }
329
330 /*!
331     \property QBatteryInfo::chargerType
332     \brief The type of the charger.
333
334     Returns the type of the charger currently used.
335 */
336 QBatteryInfo::ChargerType QBatteryInfo::chargerType() const
337 {
338     return d_ptr->chargerType();
339 }
340
341 /*!
342     Returns the charging state of the given \a battery.
343 */
344 QBatteryInfo::ChargingState QBatteryInfo::chargingState() const
345 {
346     return d_ptr->chargingState();
347 }
348
349 /*!
350     Returns the level state of the given \a battery.
351 */
352 QBatteryInfo::LevelStatus QBatteryInfo::levelStatus() const
353 {
354     return d_ptr->levelStatus();
355 }
356
357 /*!
358   Returns the health of the battery
359 */
360 QBatteryInfo::Health QBatteryInfo::health() const
361 {
362     return d_ptr->health();
363 }
364
365 /*!
366  * Returns the current battery temperature in Celcius. In case of error or the information
367  * is not available, NaN is returned.
368  */
369 float QBatteryInfo::temperature() const
370 {
371     return d_ptr->temperature();
372 }
373
374 /*!
375     \internal
376
377     Returns the signal that corresponds to \a proxySignal in the
378     meta-object of the \a sourceObject.
379 */
380 QMetaMethod proxyToSourceSignal(const QMetaMethod &proxySignal, QObject *sourceObject)
381 {
382     if (!proxySignal.isValid())
383         return proxySignal;
384     Q_ASSERT(proxySignal.methodType() == QMetaMethod::Signal);
385     Q_ASSERT(sourceObject != 0);
386     const QMetaObject *sourceMeta = sourceObject->metaObject();
387     int sourceIndex = sourceMeta->indexOfSignal(proxySignal.methodSignature());
388     Q_ASSERT(sourceIndex != -1);
389     return sourceMeta->method(sourceIndex);
390 }
391
392 /*!
393     \internal
394 */
395 void QBatteryInfo::connectNotify(const QMetaMethod &signal)
396 {
397 #if defined(Q_OS_LINUX) || defined(Q_OS_WIN) || defined(QT_SIMULATOR) || defined(Q_OS_MAC)
398     QMetaMethod sourceSignal = proxyToSourceSignal(signal, d_ptr);
399     connect(d_ptr, sourceSignal, this, signal, Qt::UniqueConnection);
400 #else
401     Q_UNUSED(signal)
402 #endif
403 }
404
405 /*!
406     \internal
407 */
408 void QBatteryInfo::disconnectNotify(const QMetaMethod &signal)
409 {
410 #if defined(Q_OS_LINUX) || defined(Q_OS_WIN) || defined(QT_SIMULATOR) || defined(Q_OS_MAC)
411     // We can only disconnect with the private implementation, when there is no receivers for the signal.
412     if (isSignalConnected(signal))
413         return;
414
415     QMetaMethod sourceSignal = proxyToSourceSignal(signal, d_ptr);
416     disconnect(d_ptr, sourceSignal, this, signal);
417 #else
418     Q_UNUSED(signal)
419 #endif
420 }
421
422 QT_END_NAMESPACE