BluezQt

agent.h
1 /*
2  * BluezQt - Asynchronous BlueZ wrapper library
3  *
4  * SPDX-FileCopyrightText: 2014-2015 David Rosca <[email protected]>
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 
18 class QDBusObjectPath;
19 
20 namespace BluezQt
21 {
22 class 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  */
36 class BLUEZQT_EXPORT Agent : public QObject
37 {
38  Q_OBJECT
39 
40  Q_PROPERTY(Capability capability READ capability)
41 
42 public:
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
virtual void release(quint64 objid)
Capability
The input/output capabilities of Agent.
Definition: agent.h:46
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Sep 25 2022 04:19:10 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.