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 * @class BluezQt::Agent agent.h <BluezQt/Agent>
26 *
27 * Bluetooth agent.
28 *
29 * This class represents a Bluetooth agent.
30 *
31 * The agent is used in pairing process to do various actions.
32 *
33 * @note The return value of requests will be sent asynchronously with Request class.
34 * It is also possible to cancel/reject all requests.
35 */
36class BLUEZQT_EXPORT Agent : public QObject
37{
38 Q_OBJECT
39
40 Q_PROPERTY(Capability capability READ capability)
41
42public:
43 /**
44 * The input/output capabilities of Agent.
45 */
46 enum Capability {
47 DisplayOnly = 0,
48 DisplayYesNo = 1,
49 KeyboardOnly = 2,
50 NoInputNoOutput = 3,
51 };
52 Q_ENUM(Capability)
53
54 /**
55 * Creates a new Agent object.
56 *
57 * @param parent
58 */
59 explicit Agent(QObject *parent = nullptr);
60
61 /**
62 * D-Bus object path of the agent.
63 *
64 * The path where the agent will be registered.
65 *
66 * @note You must provide valid object path!
67 *
68 * @return object path of agent
69 */
70 virtual QDBusObjectPath objectPath() const = 0;
71
72 /**
73 * Input/output capability of the agent.
74 *
75 * By default, this method returns DisplayYesNo.
76 *
77 * @return capability of agent
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 * @param device device that invoked the action
91 * @param request request to be used for sending reply
92 */
93 virtual void requestPinCode(DevicePtr device, const Request<QString> &request);
94
95 /**
96 * Requests the agent to display a PIN code.
97 *
98 * This method gets called when the Bluetooth daemon
99 * needs to display a pincode for an authentication.
100 *
101 * When the PIN code needs no longer to be displayed,
102 * the cancel() method will be called.
103 *
104 * @param device device that invoked the action
105 * @param pinCode PIN code to be displayed
106 */
107 virtual void displayPinCode(DevicePtr device, const QString &pinCode);
108
109 /**
110 * Requests a passkey from the agent.
111 *
112 * This method gets called when the Bluetooth daemon
113 * needs to get the passkey for an authentication.
114 *
115 * The return value should be a numeric value between 0-999999.
116 *
117 * @param device device that invoked the action
118 * @param request request to be used for sending reply
119 */
120 virtual void requestPasskey(DevicePtr device, const Request<quint32> &request);
121
122 /**
123 * Requests the agent to display a passkey.
124 *
125 * This method gets called when the Bluetooth daemon
126 * needs to display a passkey for an authentication.
127 *
128 * When the passkey needs no longer to be displayed,
129 * the cancel() method will be called.
130 *
131 * @param device device that invoked the action
132 * @param passkey passkey to be displayed
133 * @param entered number of already typed keys on the remote side
134 */
135 virtual void displayPasskey(DevicePtr device, const QString &passkey, const QString &entered);
136
137 /**
138 * Requests the agent to confirm a passkey.
139 *
140 * This method gets called when the Bluetooth daemon
141 * needs to confirm a passkey for an authentication.
142 *
143 * @param device device that invoked the action
144 * @param passkey passkey to be confirmed
145 * @param request request to be used for sending reply
146 */
147 virtual void requestConfirmation(DevicePtr device, const QString &passkey, const Request<> &request);
148
149 /**
150 * Requests the agent to authorize an incoming pairing attempt.
151 *
152 * This method gets called to request the user to authorize
153 * an incoming pairing attempt which would in other circumstances
154 * trigger the just-works model.
155 *
156 * @param device device that invoked the action
157 * @param request request to be used for sending reply
158 */
159 virtual void requestAuthorization(DevicePtr device, const Request<> &request);
160
161 /**
162 * Requests the agent to authorize a connection/service request.
163 *
164 * This method gets called when the Bluetooth daemon
165 * needs to authorize a connection/service request.
166 *
167 * @param device device that invoked the action
168 * @param uuid UUID of service
169 * @param request request to be used for sending reply
170 */
171 virtual void authorizeService(DevicePtr device, const QString &uuid, const Request<> &request);
172
173 /**
174 * Indicate that the agent request failed before receiving reply.
175 *
176 * This method gets called to indicate that the agent
177 * request failed before a reply was returned.
178 *
179 * It cancels the previous request.
180 */
181 virtual void cancel();
182
183 /**
184 * Indicates that the agent was unregistered.
185 *
186 * This method gets called when the Bluetooth daemon
187 * unregisters the agent.
188 *
189 * An agent can use it to do cleanup tasks. There is no need
190 * to unregister the agent, because when this method gets called
191 * it has already been unregistered.
192 */
193 virtual void release();
194};
195
196} // namespace BluezQt
197
198#endif // BLUEZQT_AGENT_H
199

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