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

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