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