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
33namespace Solid
34{
35namespace 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