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

source code of solid/src/solid/devices/frontend/device.h