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 | |
34 | namespace 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 | |