1 | /* |
2 | Copyright 2005 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_IFACES_DEVICE_H |
22 | #define SOLID_IFACES_DEVICE_H |
23 | |
24 | #include <QtCore/QObject> |
25 | #include <QtCore/QVariant> |
26 | |
27 | #include <QtCore/QMap> |
28 | |
29 | #include <solid/deviceinterface.h> |
30 | #include <solid/device.h> |
31 | #include <solid/solidnamespace.h> |
32 | |
33 | namespace Solid |
34 | { |
35 | namespace Ifaces |
36 | { |
37 | /** |
38 | * This class specifies the interface a device will have to comply to in order to be used in the system. |
39 | * |
40 | * Backends will have to implement it to gather and modify data in the underlying system. |
41 | * Each device has a set of key/values pair describing its properties. It has also a list of interfaces |
42 | * describing what the device actually is (a cdrom drive, a portable media player, etc.) |
43 | * |
44 | * @author Kevin Ottens <ervin@kde.org> |
45 | */ |
46 | class Device : public QObject |
47 | { |
48 | Q_OBJECT |
49 | |
50 | public: |
51 | /** |
52 | * Constructs a Device |
53 | */ |
54 | Device(QObject *parent = 0); |
55 | /** |
56 | * Destruct the Device object |
57 | */ |
58 | virtual ~Device(); |
59 | |
60 | |
61 | /** |
62 | * Retrieves the Universal Device Identifier (UDI) of the Device. |
63 | * This identifier is unique for each device in the system. |
64 | * |
65 | * @returns the Universal Device Identifier of the current device |
66 | */ |
67 | virtual QString udi() const = 0; |
68 | |
69 | /** |
70 | * Retrieves the Universal Device Identifier (UDI) of the Device's |
71 | * parent. |
72 | * |
73 | * @returns the Universal Device Identifier of the parent device |
74 | */ |
75 | virtual QString parentUdi() const; |
76 | |
77 | |
78 | /** |
79 | * Retrieves the name of the device vendor. |
80 | * |
81 | * @return the vendor name |
82 | */ |
83 | virtual QString vendor() const = 0; |
84 | |
85 | /** |
86 | * Retrieves the name of the product corresponding to this device. |
87 | * |
88 | * @return the product name |
89 | */ |
90 | virtual QString product() const = 0; |
91 | |
92 | /** |
93 | * Retrieves the name of the icon representing this device. |
94 | * The naming follows the freedesktop.org specification. |
95 | * |
96 | * @return the icon name |
97 | */ |
98 | virtual QString icon() const = 0; |
99 | |
100 | /** |
101 | * Retrieves the name of the emblems representing the state of this device. |
102 | * The naming follows the freedesktop.org specification. |
103 | * |
104 | * @return the emblem names |
105 | */ |
106 | virtual QStringList emblems() const = 0; |
107 | |
108 | /** |
109 | * Retrieves the description of device. |
110 | * |
111 | * @return the description |
112 | */ |
113 | virtual QString description() const = 0; |
114 | |
115 | /** |
116 | * Tests if a property exist. |
117 | * |
118 | * @param type the device interface type |
119 | * @returns true if the device interface is provided by this device, false otherwise |
120 | */ |
121 | virtual bool queryDeviceInterface(const Solid::DeviceInterface::Type &type) const = 0; |
122 | |
123 | /** |
124 | * Create a specialized interface to interact with the device corresponding to |
125 | * a particular device interface. |
126 | * |
127 | * @param type the device interface type |
128 | * @returns a pointer to the device interface if supported by the device, 0 otherwise |
129 | */ |
130 | virtual QObject *createDeviceInterface(const Solid::DeviceInterface::Type &type) = 0; |
131 | |
132 | /** |
133 | * Register an action for the given device. Each time the same device in another process |
134 | * broadcast the begin or the end of such action, the corresponding slots will be called |
135 | * in the current process. |
136 | * |
137 | * @param actionName name of the action to register |
138 | * @param dest the object receiving the messages when the action begins and ends |
139 | * @param requestSlot the slot processing the message when the action begins |
140 | * @param doneSlot the slot processing the message when the action ends |
141 | */ |
142 | void registerAction(const QString &actionName, QObject *dest, const char *requestSlot, const char *doneSlot) const; |
143 | |
144 | /** |
145 | * Allows to broadcat that an action just got requested on a device to all |
146 | * the corresponding devices in other processes. |
147 | * |
148 | * @param actionName name of the action which just completed |
149 | */ |
150 | void broadcastActionRequested(const QString &actionName) const; |
151 | |
152 | /** |
153 | * Allows to broadcast that an action just completed in a device to all |
154 | * the corresponding devices in other processes. |
155 | * |
156 | * @param actionName name of the action which just completed |
157 | * @param error error code if the action failed |
158 | * @param errorString message describing a potential error |
159 | */ |
160 | void broadcastActionDone(const QString &actionName, |
161 | int error = Solid::NoError, |
162 | const QString &errorString = QString()) const; |
163 | |
164 | private: |
165 | QString deviceDBusPath() const; |
166 | }; |
167 | } |
168 | } |
169 | |
170 | #endif |
171 | |