1/*
2 SPDX-FileCopyrightText: 2006 Kevin Ottens <ervin@kde.org>
3 SPDX-FileCopyrightText: 2012 Lukas Tinkl <ltinkl@redhat.com>
4 SPDX-FileCopyrightText: 2014 Kai Uwe Broulik <kde@privat.broulik.de>
5
6 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
7*/
8
9#ifndef SOLID_IFACES_BATTERY_H
10#define SOLID_IFACES_BATTERY_H
11
12#include <solid/battery.h>
13#include <solid/devices/ifaces/deviceinterface.h>
14
15namespace Solid
16{
17namespace Ifaces
18{
19/**
20 * This device interface is available on batteries.
21 */
22class Battery : virtual public DeviceInterface
23{
24public:
25 /**
26 * Destroys a Battery object.
27 */
28 ~Battery() override;
29
30 /**
31 * Indicates if this battery is currently present in its bay.
32 *
33 * @return true if the battery is present, false otherwise
34 */
35 virtual bool isPresent() const = 0;
36
37 /**
38 * Retrieves the type of device holding this battery.
39 *
40 * @return the type of device holding this battery
41 * @see Solid::Battery::BatteryType
42 */
43 virtual Solid::Battery::BatteryType type() const = 0;
44
45 /**
46 * Retrieves the current charge level of the battery normalised
47 * to percent.
48 *
49 * @return the current charge level normalised to percent
50 */
51 virtual int chargePercent() const = 0;
52
53 /**
54 * Retrieves the battery capacity normalised to percent,
55 * meaning how much energy can it hold compared to what it is designed to.
56 * The capacity of the battery will reduce with age.
57 * A capacity value less than 75% is usually a sign that you should renew your battery.
58 *
59 * @since 4.11
60 * @return the battery capacity normalised to percent
61 */
62 virtual int capacity() const = 0;
63
64 /**
65 * Retrieves the number of charge cycles this battery has experienced so far,
66 * or -1 if this information is unavailable.
67 *
68 * @since 6.9
69 * @return the number of charge cycles
70 */
71 virtual int cycleCount() const = 0;
72
73 /**
74 * Indicates if the battery is rechargeable.
75 *
76 * @return true if the battery is rechargeable, false otherwise (one time usage)
77 */
78 virtual bool isRechargeable() const = 0;
79
80 /**
81 * Indicates if the battery is powering the machine.
82 *
83 * @return true if the battery is powersupply, false otherwise
84 */
85 virtual bool isPowerSupply() const = 0;
86
87 /**
88 * Retrieves the current charge state of the battery. It can be in a stable
89 * state (no charge), charging or discharging.
90 *
91 * @return the current battery charge state
92 * @see Solid::Battery::ChargeState
93 */
94 virtual Solid::Battery::ChargeState chargeState() const = 0;
95
96 /**
97 * Time (in seconds) until the battery is empty.
98 *
99 * @return time until the battery is empty
100 * @since 5.0
101 */
102 virtual qlonglong timeToEmpty() const = 0;
103
104 /**
105 * Time (in seconds) until the battery is full.
106 *
107 * @return time until the battery is full
108 * @since 5.0
109 */
110 virtual qlonglong timeToFull() const = 0;
111
112 /**
113 * Retrieves the technology used to manufacture the battery.
114 *
115 * @return the battery technology
116 * @see Solid::Battery::Technology
117 */
118 virtual Solid::Battery::Technology technology() const = 0;
119
120 /**
121 * Amount of energy (measured in Wh) currently available in the power source.
122 *
123 * @return amount of battery energy in Wh
124 */
125 virtual double energy() const = 0;
126
127 /**
128 * Amount of energy (measured in Wh) the battery has when it is full.
129 *
130 * @return amount of battery energy when full in Wh
131 * @since 5.7
132 */
133 virtual double energyFull() const = 0;
134
135 /**
136 * Amount of energy (measured in Wh) the battery should have by design hen it is full.
137 *
138 * @return amount of battery energy when full by design in Wh
139 * @since 5.7
140 */
141 virtual double energyFullDesign() const = 0;
142
143 /**
144 * Amount of energy being drained from the source, measured in W.
145 * If positive, the source is being discharged, if negative it's being charged.
146 *
147 * @return battery rate in Watts
148 *
149 */
150 virtual double energyRate() const = 0;
151
152 /**
153 * Voltage in the Cell or being recorded by the meter.
154 *
155 * @return voltage in Volts
156 */
157 virtual double voltage() const = 0;
158
159 /**
160 * The temperature of the battery in degrees Celsius.
161 *
162 * @return the battery temperature in degrees Celsius
163 * @since 5.0
164 */
165 virtual double temperature() const = 0;
166
167 /**
168 * The serial number of the battery
169 *
170 * @return the serial number of the battery
171 * @since 5.0
172 */
173 virtual QString serial() const = 0;
174
175 /**
176 * Retrieves the current estimated remaining time of the system batteries
177 *
178 * @return the current global estimated remaining time in seconds
179 * @since 5.8
180 */
181 virtual qlonglong remainingTime() const = 0;
182
183protected:
184 // Q_SIGNALS:
185 /**
186 * This signal is emitted if the battery gets plugged in/out of the
187 * battery bay.
188 *
189 * @param newState the new plugging state of the battery, type is boolean
190 * @param udi the UDI of the battery with thew new plugging state
191 */
192 virtual void presentStateChanged(bool newState, const QString &udi) = 0;
193
194 /**
195 * This signal is emitted when the charge percent value of this
196 * battery has changed.
197 *
198 * @param value the new charge percent value of the battery
199 * @param udi the UDI of the battery with the new charge percent
200 */
201 virtual void chargePercentChanged(int value, const QString &udi) = 0;
202
203 /**
204 * This signal is emitted when the capacity of this battery has changed.
205 *
206 * @param value the new capacity of the battery
207 * @param udi the UDI of the battery with the new capacity
208 * @since 4.11
209 */
210 virtual void capacityChanged(int value, const QString &udi) = 0;
211
212 /**
213 * This signal is emitted when the number of charge cycles of the
214 * battery has changed.
215 *
216 * @param value the new number of charge cycles of the battery
217 * @param udi the UDI of the battery with the new number of charge cycles
218 * @since 6.9
219 */
220 virtual void cycleCountChanged(int value, const QString &udi) = 0;
221
222 /**
223 * This signal is emitted when the power supply state of the battery
224 * changes.
225 *
226 * @param newState the new power supply state, type is boolean
227 * @param udi the UDI of the battery with the new power supply state
228 * @since 4.11
229 */
230 virtual void powerSupplyStateChanged(bool newState, const QString &udi) = 0;
231
232 /**
233 * This signal is emitted when the charge state of this battery
234 * has changed.
235 *
236 * @param newState the new charge state of the battery, it's one of
237 * the type Solid::Battery::ChargeState
238 * @see Solid::Battery::ChargeState
239 * @param udi the UDI of the battery with the new charge state
240 */
241 virtual void chargeStateChanged(int newState, const QString &udi = QString()) = 0;
242
243 /**
244 * This signal is emitted when the time until the battery is empty
245 * has changed.
246 *
247 * @param time the new remaining time
248 * @param udi the UDI of the battery with the new remaining time
249 * @since 5.0
250 */
251 virtual void timeToEmptyChanged(qlonglong time, const QString &udi) = 0;
252
253 /**
254 * This signal is emitted when the time until the battery is full
255 * has changed.
256 *
257 * @param time the new remaining time
258 * @param udi the UDI of the battery with the new remaining time
259 * @since 5.0
260 */
261 virtual void timeToFullChanged(qlonglong time, const QString &udi) = 0;
262
263 /**
264 * This signal is emitted when the energy value of this
265 * battery has changed.
266 *
267 * @param energy the new energy value of the battery
268 * @param udi the UDI of the battery with the new energy value
269 */
270 virtual void energyChanged(double energy, const QString &udi) = 0;
271
272 /**
273 * This signal is emitted when the energy full value of this
274 * battery has changed.
275 *
276 * @param energy the new energy full value of the battery
277 * @param udi the UDI of the battery with the new energy full value
278 */
279 virtual void energyFullChanged(double energy, const QString &udi) = 0;
280
281 /**
282 * This signal is emitted when the energy full design value of this
283 * battery has changed.
284 *
285 * @param energy the new energy full design value of the battery
286 * @param udi the UDI of the battery with the new energy full design value
287 */
288 virtual void energyFullDesignChanged(double energy, const QString &udi) = 0;
289
290 /**
291 * This signal is emitted when the energy rate value of this
292 * battery has changed.
293 *
294 * If positive, the source is being discharged, if negative it's being charged.
295 *
296 * @param energyRate the new energy rate value of the battery
297 * @param udi the UDI of the battery with the new charge percent
298 */
299 virtual void energyRateChanged(double energyRate, const QString &udi) = 0;
300
301 /**
302 * This signal is emitted when the voltage in the cell has changed.
303 *
304 * @param voltage the new voltage of the cell
305 * @param udi the UDI of the battery with the new voltage
306 * @since 5.0
307 */
308 virtual void voltageChanged(double voltage, const QString &udi) = 0;
309
310 /**
311 * This signal is emitted when the battery temperature has changed.
312 *
313 * @param temperature the new temperature of the battery in degrees Celsius
314 * @param udi the UDI of the battery with the new temperature
315 * @since 5.0
316 */
317 virtual void temperatureChanged(double temperature, const QString &udi) = 0;
318
319 /**
320 * This signal is emitted when the estimated battery remaining time changes.
321 *
322 * @param time the new remaining time
323 * @param udi the UDI of the battery with the new remaining time
324 * @since 5.8
325 */
326 virtual void remainingTimeChanged(qlonglong time, const QString &udi) = 0;
327};
328}
329}
330
331Q_DECLARE_INTERFACE(Solid::Ifaces::Battery, "org.kde.Solid.Ifaces.Battery/0.3")
332
333#endif
334

source code of solid/src/solid/devices/ifaces/battery.h