1/*
2 * BluezQt - Asynchronous BlueZ wrapper library
3 *
4 * SPDX-FileCopyrightText: 2014-2015 David Rosca <nowrep@gmail.com>
5 *
6 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
7 */
8
9#ifndef BLUEZQT_AGENT_H
10#define BLUEZQT_AGENT_H
11
12#include <QObject>
13
14#include "bluezqt_export.h"
15#include "request.h"
16#include "types.h"
17
18class QDBusObjectPath;
19
20namespace BluezQt
21{
22class Device;
23
24/*!
25 * \inmodule BluezQt
26 * \class BluezQt::Agent
27 * \inheaderfile BluezQt/Agent
28 * \brief Bluetooth agent.
29 *
30 * This class represents a Bluetooth agent.
31 *
32 * The agent is used in pairing process to do various actions.
33 *
34 * \note The return value of requests will be sent asynchronously with Request class.
35 * It is also possible to cancel/reject all requests.
36 */
37class BLUEZQT_EXPORT Agent : public QObject
38{
39 Q_OBJECT
40
41 /*!
42 * \property BluezQt::Agent::capability
43 */
44 Q_PROPERTY(Capability capability READ capability)
45
46public:
47 /*!
48 * The input/output capabilities of Agent.
49 * \value DisplayOnly
50 * \value DisplayYesNo
51 * \value KeyboardOnly
52 * \value NoInputNoOutput
53 */
54 enum Capability {
55 DisplayOnly = 0,
56 DisplayYesNo = 1,
57 KeyboardOnly = 2,
58 NoInputNoOutput = 3,
59 };
60 Q_ENUM(Capability)
61
62 /*!
63 * Creates a new Agent object as a child of \a parent.
64 */
65 explicit Agent(QObject *parent = nullptr);
66
67 /*!
68 * Returns the D-Bus object path where the agent will be registered.
69 *
70 * \note You must provide valid object path!
71 */
72 virtual QDBusObjectPath objectPath() const = 0;
73
74 /*!
75 * Returns the input/output capability of the agent.
76 *
77 * By default, this method returns DisplayYesNo.
78 */
79 virtual Capability capability() const;
80
81 /*!
82 * Requests a PIN code from the agent.
83 *
84 * This method gets called when the Bluetooth daemon
85 * needs to get the PIN code for an authentication.
86 *
87 * The return value should be a string of 1-16 characters
88 * length. The string can be alphanumeric.
89 *
90 * \a device The device that invoked the action.
91 *
92 * \a request The request to be used for sending reply.
93 */
94 virtual void requestPinCode(DevicePtr device, const Request<QString> &request);
95
96 /*!
97 * Requests the agent to display a PIN code.
98 *
99 * This method gets called when the Bluetooth daemon
100 * needs to display a pincode for an authentication.
101 *
102 * When the PIN code needs no longer to be displayed,
103 * the cancel() method will be called.
104 *
105 * \a device The device that invoked the action.
106 *
107 * \a pinCode The PIN code to be displayed.
108 */
109 virtual void displayPinCode(DevicePtr device, const QString &pinCode);
110
111 /*!
112 * Requests a passkey from the agent.
113 *
114 * This method gets called when the Bluetooth daemon
115 * needs to get the passkey for an authentication.
116 *
117 * The return value should be a numeric value between 0-999999.
118 *
119 * \a device The device that invoked the action.
120 *
121 * \a request The request to be used for sending a reply.
122 */
123 virtual void requestPasskey(DevicePtr device, const Request<quint32> &request);
124
125 /*!
126 * Requests the agent to display a passkey.
127 *
128 * This method gets called when the Bluetooth daemon
129 * needs to display a passkey for an authentication.
130 *
131 * When the passkey needs no longer to be displayed,
132 * the cancel() method will be called.
133 *
134 * \a device The device that invoked the action.
135 *
136 * \a passkey The passkey to be displayed.
137 *
138 * \a entered The number of already typed keys on the remote side.
139 */
140 virtual void displayPasskey(DevicePtr device, const QString &passkey, const QString &entered);
141
142 /*!
143 * Requests the agent to confirm a passkey.
144 *
145 * This method gets called when the Bluetooth daemon
146 * needs to confirm a passkey for an authentication.
147 *
148 * \a device The device that invoked the action.
149 *
150 * \a passkey The passkey to be confirmed.
151 *
152 * \a request The request to be used for sending reply.
153 */
154 virtual void requestConfirmation(DevicePtr device, const QString &passkey, const Request<> &request);
155
156 /*!
157 * Requests the agent to authorize an incoming pairing attempt.
158 *
159 * This method gets called to request the user to authorize
160 * an incoming pairing attempt which would in other circumstances
161 * trigger the just-works model.
162 *
163 * \a device The device that invoked the action.
164 *
165 * \a request The request to be used for sending reply.
166 */
167 virtual void requestAuthorization(DevicePtr device, const Request<> &request);
168
169 /*!
170 * Requests the agent to authorize a connection/service request.
171 *
172 * This method gets called when the Bluetooth daemon
173 * needs to authorize a connection/service request.
174 *
175 * \a device The device that invoked the action.
176 *
177 * \a uuid The UUID of the service.
178 *
179 * \a request The request to be used for sending a reply.
180 */
181 virtual void authorizeService(DevicePtr device, const QString &uuid, const Request<> &request);
182
183 /*!
184 * Indicate that the agent request failed before receiving reply.
185 *
186 * This method gets called to indicate that the agent
187 * request failed before a reply was returned.
188 *
189 * It cancels the previous request.
190 */
191 virtual void cancel();
192
193 /*!
194 * Indicates that the agent was unregistered.
195 *
196 * This method gets called when the Bluetooth daemon
197 * unregisters the agent.
198 *
199 * An agent can use it to do cleanup tasks. There is no need
200 * to unregister the agent, because when this method gets called
201 * it has already been unregistered.
202 */
203 virtual void release();
204};
205
206} // namespace BluezQt
207
208#endif // BLUEZQT_AGENT_H
209

source code of bluez-qt/src/agent.h