Solid

ifaces/battery.h
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 * Indicates if the battery is rechargeable.
66 *
67 * @return true if the battery is rechargeable, false otherwise (one time usage)
68 */
69 virtual bool isRechargeable() const = 0;
70
71 /**
72 * Indicates if the battery is powering the machine.
73 *
74 * @return true if the battery is powersupply, false otherwise
75 */
76 virtual bool isPowerSupply() const = 0;
77
78 /**
79 * Retrieves the current charge state of the battery. It can be in a stable
80 * state (no charge), charging or discharging.
81 *
82 * @return the current battery charge state
83 * @see Solid::Battery::ChargeState
84 */
86
87 /**
88 * Time (in seconds) until the battery is empty.
89 *
90 * @return time until the battery is empty
91 * @since 5.0
92 */
93 virtual qlonglong timeToEmpty() const = 0;
94
95 /**
96 * Time (in seconds) until the battery is full.
97 *
98 * @return time until the battery is full
99 * @since 5.0
100 */
101 virtual qlonglong timeToFull() const = 0;
102
103 /**
104 * Retrieves the technology used to manufacture the battery.
105 *
106 * @return the battery technology
107 * @see Solid::Battery::Technology
108 */
110
111 /**
112 * Amount of energy (measured in Wh) currently available in the power source.
113 *
114 * @return amount of battery energy in Wh
115 */
116 virtual double energy() const = 0;
117
118 /**
119 * Amount of energy (measured in Wh) the battery has when it is full.
120 *
121 * @return amount of battery energy when full in Wh
122 * @since 5.7
123 */
124 virtual double energyFull() const = 0;
125
126 /**
127 * Amount of energy (measured in Wh) the battery should have by design hen it is full.
128 *
129 * @return amount of battery energy when full by design in Wh
130 * @since 5.7
131 */
132 virtual double energyFullDesign() const = 0;
133
134 /**
135 * Amount of energy being drained from the source, measured in W.
136 * If positive, the source is being discharged, if negative it's being charged.
137 *
138 * @return battery rate in Watts
139 *
140 */
141 virtual double energyRate() const = 0;
142
143 /**
144 * Voltage in the Cell or being recorded by the meter.
145 *
146 * @return voltage in Volts
147 */
148 virtual double voltage() const = 0;
149
150 /**
151 * The temperature of the battery in degrees Celsius.
152 *
153 * @return the battery temperature in degrees Celsius
154 * @since 5.0
155 */
156 virtual double temperature() const = 0;
157
158 /**
159 * The serial number of the battery
160 *
161 * @return the serial number of the battery
162 * @since 5.0
163 */
164 virtual QString serial() const = 0;
165
166 /**
167 * Retrieves the current estimated remaining time of the system batteries
168 *
169 * @return the current global estimated remaining time in seconds
170 * @since 5.8
171 */
172 virtual qlonglong remainingTime() const = 0;
173
174protected:
175 // Q_SIGNALS:
176 /**
177 * This signal is emitted if the battery gets plugged in/out of the
178 * battery bay.
179 *
180 * @param newState the new plugging state of the battery, type is boolean
181 * @param udi the UDI of the battery with thew new plugging state
182 */
183 virtual void presentStateChanged(bool newState, const QString &udi) = 0;
184
185 /**
186 * This signal is emitted when the charge percent value of this
187 * battery has changed.
188 *
189 * @param value the new charge percent value of the battery
190 * @param udi the UDI of the battery with the new charge percent
191 */
192 virtual void chargePercentChanged(int value, const QString &udi) = 0;
193
194 /**
195 * This signal is emitted when the capacity of this battery has changed.
196 *
197 * @param value the new capacity of the battery
198 * @param udi the UDI of the battery with the new capacity
199 * @since 4.11
200 */
201 virtual void capacityChanged(int value, const QString &udi) = 0;
202
203 /**
204 * This signal is emitted when the power supply state of the battery
205 * changes.
206 *
207 * @param newState the new power supply state, type is boolean
208 * @param udi the UDI of the battery with the new power supply state
209 * @since 4.11
210 */
211 virtual void powerSupplyStateChanged(bool newState, const QString &udi) = 0;
212
213 /**
214 * This signal is emitted when the charge state of this battery
215 * has changed.
216 *
217 * @param newState the new charge state of the battery, it's one of
218 * the type Solid::Battery::ChargeState
219 * @see Solid::Battery::ChargeState
220 * @param udi the UDI of the battery with the new charge state
221 */
222 virtual void chargeStateChanged(int newState, const QString &udi = QString()) = 0;
223
224 /**
225 * This signal is emitted when the time until the battery is empty
226 * has changed.
227 *
228 * @param time the new remaining time
229 * @param udi the UDI of the battery with the new remaining time
230 * @since 5.0
231 */
232 virtual void timeToEmptyChanged(qlonglong time, const QString &udi) = 0;
233
234 /**
235 * This signal is emitted when the time until the battery is full
236 * has changed.
237 *
238 * @param time the new remaining time
239 * @param udi the UDI of the battery with the new remaining time
240 * @since 5.0
241 */
242 virtual void timeToFullChanged(qlonglong time, const QString &udi) = 0;
243
244 /**
245 * This signal is emitted when the energy value of this
246 * battery has changed.
247 *
248 * @param energy the new energy value of the battery
249 * @param udi the UDI of the battery with the new energy value
250 */
251 virtual void energyChanged(double energy, const QString &udi) = 0;
252
253 /**
254 * This signal is emitted when the energy full value of this
255 * battery has changed.
256 *
257 * @param energy the new energy full value of the battery
258 * @param udi the UDI of the battery with the new energy full value
259 */
260 virtual void energyFullChanged(double energy, const QString &udi) = 0;
261
262 /**
263 * This signal is emitted when the energy full design value of this
264 * battery has changed.
265 *
266 * @param energy the new energy full design value of the battery
267 * @param udi the UDI of the battery with the new energy full design value
268 */
269 virtual void energyFullDesignChanged(double energy, const QString &udi) = 0;
270
271 /**
272 * This signal is emitted when the energy rate value of this
273 * battery has changed.
274 *
275 * If positive, the source is being discharged, if negative it's being charged.
276 *
277 * @param energyRate the new energy rate value of the battery
278 * @param udi the UDI of the battery with the new charge percent
279 */
280 virtual void energyRateChanged(double energyRate, const QString &udi) = 0;
281
282 /**
283 * This signal is emitted when the voltage in the cell has changed.
284 *
285 * @param voltage the new voltage of the cell
286 * @param udi the UDI of the battery with the new voltage
287 * @since 5.0
288 */
289 virtual void voltageChanged(double voltage, const QString &udi) = 0;
290
291 /**
292 * This signal is emitted when the battery temperature has changed.
293 *
294 * @param temperature the new temperature of the battery in degrees Celsius
295 * @param udi the UDI of the battery with the new temperature
296 * @since 5.0
297 */
298 virtual void temperatureChanged(double temperature, const QString &udi) = 0;
299
300 /**
301 * This signal is emitted when the estimated battery remaining time changes.
302 *
303 * @param time the new remaining time
304 * @param udi the UDI of the battery with the new remaining time
305 * @since 5.8
306 */
307 virtual void remainingTimeChanged(qlonglong time, const QString &udi) = 0;
308};
309}
310}
311
312Q_DECLARE_INTERFACE(Solid::Ifaces::Battery, "org.kde.Solid.Ifaces.Battery/0.3")
313
314#endif
BatteryType
This enum type defines the type of the device holding the battery.
Technology
Technology used in the battery.
ChargeState
This enum type defines charge state of a battery.
This device interface is available on batteries.
virtual void capacityChanged(int value, const QString &udi)=0
This signal is emitted when the capacity of this battery has changed.
virtual Solid::Battery::Technology technology() const =0
Retrieves the technology used to manufacture the battery.
virtual QString serial() const =0
The serial number of the battery.
virtual void timeToFullChanged(qlonglong time, const QString &udi)=0
This signal is emitted when the time until the battery is full has changed.
virtual void energyFullDesignChanged(double energy, const QString &udi)=0
This signal is emitted when the energy full design value of this battery has changed.
virtual void voltageChanged(double voltage, const QString &udi)=0
This signal is emitted when the voltage in the cell has changed.
virtual double energyFull() const =0
Amount of energy (measured in Wh) the battery has when it is full.
virtual void energyFullChanged(double energy, const QString &udi)=0
This signal is emitted when the energy full value of this battery has changed.
virtual double energyFullDesign() const =0
Amount of energy (measured in Wh) the battery should have by design hen it is full.
virtual void chargeStateChanged(int newState, const QString &udi=QString())=0
This signal is emitted when the charge state of this battery has changed.
virtual void powerSupplyStateChanged(bool newState, const QString &udi)=0
This signal is emitted when the power supply state of the battery changes.
virtual void temperatureChanged(double temperature, const QString &udi)=0
This signal is emitted when the battery temperature has changed.
virtual int capacity() const =0
Retrieves the battery capacity normalised to percent, meaning how much energy can it hold compared to...
virtual void remainingTimeChanged(qlonglong time, const QString &udi)=0
This signal is emitted when the estimated battery remaining time changes.
virtual void chargePercentChanged(int value, const QString &udi)=0
This signal is emitted when the charge percent value of this battery has changed.
virtual int chargePercent() const =0
Retrieves the current charge level of the battery normalised to percent.
virtual qlonglong timeToFull() const =0
Time (in seconds) until the battery is full.
virtual void energyChanged(double energy, const QString &udi)=0
This signal is emitted when the energy value of this battery has changed.
virtual Solid::Battery::BatteryType type() const =0
Retrieves the type of device holding this battery.
virtual bool isRechargeable() const =0
Indicates if the battery is rechargeable.
virtual double energy() const =0
Amount of energy (measured in Wh) currently available in the power source.
virtual qlonglong timeToEmpty() const =0
Time (in seconds) until the battery is empty.
~Battery() override
Destroys a Battery object.
virtual double voltage() const =0
Voltage in the Cell or being recorded by the meter.
virtual bool isPowerSupply() const =0
Indicates if the battery is powering the machine.
virtual double temperature() const =0
The temperature of the battery in degrees Celsius.
virtual double energyRate() const =0
Amount of energy being drained from the source, measured in W.
virtual bool isPresent() const =0
Indicates if this battery is currently present in its bay.
virtual qlonglong remainingTime() const =0
Retrieves the current estimated remaining time of the system batteries.
virtual void energyRateChanged(double energyRate, const QString &udi)=0
This signal is emitted when the energy rate value of this battery has changed.
virtual void timeToEmptyChanged(qlonglong time, const QString &udi)=0
This signal is emitted when the time until the battery is empty has changed.
virtual void presentStateChanged(bool newState, const QString &udi)=0
This signal is emitted if the battery gets plugged in/out of the battery bay.
virtual Solid::Battery::ChargeState chargeState() const =0
Retrieves the current charge state of the battery.
Base interface of all the device interfaces.
The single responsibility of this class is to create arguments valid for logind Inhibit call.
Definition fakebattery.h:16
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:56:28 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.