Solid

frontend/device.h
1/*
2 SPDX-FileCopyrightText: 2005-2007 Kevin Ottens <ervin@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6
7#ifndef SOLID_DEVICE_H
8#define SOLID_DEVICE_H
9
10#include <QList>
11#include <QSharedData>
12
13#include <solid/solid_export.h>
14
15#include <solid/deviceinterface.h>
16
17namespace Solid
18{
19class DevicePrivate;
20
21/**
22 * @class Solid::Device device.h <Solid/Device>
23 *
24 * This class allows applications to deal with devices available in the
25 * underlying system.
26 *
27 * Device stores a reference to device data provided by the backend.
28 * Device objects are designed to be used by value. Copying these objects
29 * is quite cheap, so using pointers to the me is generally not needed.
30 *
31 * @author Kevin Ottens <ervin@kde.org>
32 */
33class SOLID_EXPORT Device
34{
35public:
36 /**
37 * Retrieves all the devices available in the underlying system.
38 *
39 * @return the list of the devices available
40 */
41 static QList<Device> allDevices();
42
43 /**
44 * Retrieves a list of devices of the system given matching the given
45 * constraints (parent and device interface type)
46 *
47 * @param type device interface type available on the devices we're looking for, or DeviceInterface::Unknown
48 * if there's no constraint on the device interfaces
49 * @param parentUdi UDI of the parent of the devices we're searching for, or QString()
50 * if there's no constraint on the parent
51 * @return the list of devices corresponding to the given constraints
52 * @see Solid::Predicate
53 */
54 static QList<Device> listFromType(const DeviceInterface::Type &type, const QString &parentUdi = QString());
55
56 /**
57 * Retrieves a list of devices of the system given matching the given
58 * constraints (parent and predicate)
59 *
60 * @param predicate Predicate that the devices we're searching for must verify
61 * @param parentUdi UDI of the parent of the devices we're searching for, or QString()
62 * if there's no constraint on the parent
63 * @return the list of devices corresponding to the given constraints
64 * @see Solid::Predicate
65 */
66 static QList<Device> listFromQuery(const Predicate &predicate, const QString &parentUdi = QString());
67
68 /**
69 * Convenience function see above.
70 *
71 * @param predicate
72 * @param parentUdi
73 * @return the list of devices
74 */
75 static QList<Device> listFromQuery(const QString &predicate, const QString &parentUdi = QString());
76
77 /**
78 * Returns the Device containing the filesystem for the given path
79 *
80 * @param canonical path to a filesystem entry, e.g. a file or directory
81 * @return @p Device containing the given @p path. For Devices implementing the
82 * StorageVolume interface only ones matching UsageType::FileSystem are
83 * returned, i.e. no backing encrypted volumes.
84 * @since 5.73
85 * @see QFileInfo::canonicalFilePath
86 */
87 static Device storageAccessFromPath(const QString &path);
88
89 /**
90 * Constructs a device for a given Universal Device Identifier (UDI).
91 *
92 * @param udi the udi of the device to create
93 */
94 explicit Device(const QString &udi = QString());
95
96 /**
97 * Constructs a copy of a device.
98 *
99 * @param device the device to copy
100 */
101 Device(const Device &device);
102
103 /**
104 * Destroys the device.
105 */
106 ~Device();
107
108 /**
109 * Assigns a device to this device and returns a reference to it.
110 *
111 * @param device the device to assign
112 * @return a reference to the device
113 */
114 Device &operator=(const Device &device);
115
116 /**
117 * Indicates if this device is valid.
118 * A device is considered valid if it's available in the system.
119 *
120 * @return true if this device is available, false otherwise
121 */
122 bool isValid() const;
123
124 /**
125 * Retrieves the Universal Device Identifier (UDI).
126 *
127 * \warning Don't use the UDI for anything except communication with Solid. Also don't store
128 * UDIs as there's no guarantee that the UDI stays the same when the hardware setup changed.
129 * The UDI is a unique identifier that is local to the computer in question and for the
130 * current boot session. The UDIs may change after a reboot.
131 * Similar hardware in other computers may have different values; different
132 * hardware could have the same UDI.
133 *
134 * @return the udi of the device
135 */
136 QString udi() const;
137
138 /**
139 * Retrieves the Universal Device Identifier (UDI)
140 * of the Device's parent.
141 *
142 * @return the udi of the device's parent
143 */
144 QString parentUdi() const;
145
146 /**
147 * Retrieves the parent of the Device.
148 *
149 * @return the device's parent
150 * @see parentUdi()
151 */
152 Device parent() const;
153
154 /**
155 * Retrieves the name of the device vendor.
156 *
157 * @return the vendor name
158 */
159 QString vendor() const;
160
161 /**
162 * Retrieves the name of the product corresponding to this device.
163 *
164 * @return the product name
165 */
166 QString product() const;
167
168 /**
169 * Retrieves the name of the icon representing this device.
170 * The naming follows the freedesktop.org specification.
171 *
172 * @return the icon name
173 */
174 QString icon() const;
175
176 /**
177 * Retrieves the names of the emblems representing the state of this device.
178 * The naming follows the freedesktop.org specification.
179 *
180 * @return the emblem names
181 * @since 4.4
182 */
183 QStringList emblems() const;
184
185 /**
186 * Retrieves the display Name to use for this device.
187 * Same as description when not defined.
188 *
189 * @return the display Name
190 * @since 5.71
191 */
192 QString displayName() const;
193
194 /**
195 * Retrieves the description of device.
196 *
197 * @return the description
198 * @since 4.4
199 */
200 QString description() const;
201
202 /**
203 * Tests if a device interface is available from the device.
204 *
205 * @param type the device interface type to query
206 * @return true if the device interface is available, false otherwise
207 */
208 bool isDeviceInterface(const DeviceInterface::Type &type) const;
209
210 /**
211 * Retrieves a specialized interface to interact with the device corresponding to
212 * a particular device interface.
213 *
214 * @param type the device interface type
215 * @returns a pointer to the device interface interface if it exists, 0 otherwise
216 */
217 DeviceInterface *asDeviceInterface(const DeviceInterface::Type &type);
218
219 /**
220 * Retrieves a specialized interface to interact with the device corresponding to
221 * a particular device interface.
222 *
223 * @param type the device interface type
224 * @returns a pointer to the device interface interface if it exists, 0 otherwise
225 */
226 const DeviceInterface *asDeviceInterface(const DeviceInterface::Type &type) const;
227
228 /**
229 * Retrieves a specialized interface to interact with the device corresponding
230 * to a given device interface.
231 *
232 * @returns a pointer to the device interface if it exists, 0 otherwise
233 */
234 template<class DevIface>
235 DevIface *as()
236 {
237 DeviceInterface::Type type = DevIface::deviceInterfaceType();
238 DeviceInterface *iface = asDeviceInterface(type);
239 return qobject_cast<DevIface *>(iface);
240 }
241
242 /**
243 * Retrieves a specialized interface to interact with the device corresponding
244 * to a given device interface.
245 *
246 * @returns a pointer to the device interface if it exists, 0 otherwise
247 */
248 template<class DevIface>
249 const DevIface *as() const
250 {
251 DeviceInterface::Type type = DevIface::deviceInterfaceType();
252 const DeviceInterface *iface = asDeviceInterface(type);
253 return qobject_cast<const DevIface *>(iface);
254 }
255
256 /**
257 * Tests if a device provides a given device interface.
258 *
259 * @returns true if the interface is available, false otherwise
260 */
261 template<class DevIface>
262 bool is() const
263 {
264 return isDeviceInterface(DevIface::deviceInterfaceType());
265 }
266
267private:
269 friend class DeviceManagerPrivate;
270};
271}
272
273Q_DECLARE_TYPEINFO(Solid::Device, Q_RELOCATABLE_TYPE);
274
275#endif
Base class of all the device interfaces.
Type
This enum type defines the type of device interface that a Device can have.
This class allows applications to deal with devices available in the underlying system.
bool is() const
Tests if a device provides a given device interface.
const DevIface * as() const
Retrieves a specialized interface to interact with the device corresponding to a given device interfa...
DevIface * as()
Retrieves a specialized interface to interact with the device corresponding to a given device interfa...
This class implements predicates for devices.
Definition predicate.h:67
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.