1 /*
2  * Copyright (C) 2021 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 /**
17  * @addtogroup Bluetooth
18  * @{
19  *
20  * @brief Defines a bluetooth system that provides basic bluetooth connection and profile functions,
21  *        including A2DP, AVRCP, BLE, GATT, HFP, MAP, PBAP, and SPP, etc.
22  *
23  * @since 6
24  *
25  */
26 
27 /**
28  * @file bluetooth_gatt_client.h
29  *
30  * @brief Bluetooth gatt client interface.
31  *
32  * @since 6
33  *
34  */
35 
36 #ifndef BLUETOOTH_GATT_CLIENT_H
37 #define BLUETOOTH_GATT_CLIENT_H
38 
39 #include "bluetooth_def.h"
40 #include "bluetooth_gatt_service.h"
41 #include "bluetooth_remote_device.h"
42 #include <memory>
43 
44 namespace OHOS {
45 namespace Bluetooth {
46 
47 /**
48  * @brief Class for GattClientCallback functions.
49  *
50  * @since 6
51  *
52  */
53 class GattClientCallback {
54 public:
55     /**
56      * @brief The function to OnConnectionStateChanged.
57      *
58      * @param connectionState callback of gattClientCallback.
59      * @param ret ret of GattClientCallback.
60      * @since 6
61      *
62      */
63     virtual void OnConnectionStateChanged(int connectionState, int ret) = 0;
64 
65     /**
66      * @brief The function to OnCharacteristicChanged.
67      *
68      * @param characteristic Characteristic object to changed.
69      * @since 6
70      *
71      */
OnCharacteristicChanged(const GattCharacteristic & characteristic)72     virtual void OnCharacteristicChanged(const GattCharacteristic &characteristic)
73     {}
74 
75     /**
76      * @brief The function to OnCharacteristicReadResult.
77      *
78      * @param characteristic Characteristic object.
79      * @param ret ret of GattClientCallback.
80      * @since 6
81      *
82      */
OnCharacteristicReadResult(const GattCharacteristic & characteristic,int ret)83     virtual void OnCharacteristicReadResult(const GattCharacteristic &characteristic, int ret)
84     {}
85 
OnReadRemoteRssiValueResult(int rssi,int status)86     virtual void OnReadRemoteRssiValueResult(int rssi, int status)
87     {}
88     /**
89      * @brief The function to OnCharacteristicWriteResult.
90      *
91      * @param characteristic Characteristic object.
92      * @param ret ret of GattClientCallback.
93      * @since 6
94      *
95      */
OnCharacteristicWriteResult(const GattCharacteristic & characteristic,int ret)96     virtual void OnCharacteristicWriteResult(const GattCharacteristic &characteristic, int ret)
97     {}
98 
99     /**
100      * @brief The function to OnDescriptorReadResult.
101      *
102      * @param descriptor descriptor object.
103      * @param ret ret of GattClientCallback.
104      * @since 6
105      *
106      */
OnDescriptorReadResult(const GattDescriptor & descriptor,int ret)107     virtual void OnDescriptorReadResult(const GattDescriptor &descriptor, int ret)
108     {}
109 
110     /**
111      * @brief The function to OnDescriptorWriteResult.
112      *
113      * @param descriptor descriptor object.
114      * @param ret ret of GattClientCallback.
115      * @since 6
116      *
117      */
OnDescriptorWriteResult(const GattDescriptor & descriptor,int ret)118     virtual void OnDescriptorWriteResult(const GattDescriptor &descriptor, int ret)
119     {}
120 
121     /**
122      * @brief The function to OnMtuUpdate.
123      *
124      * @param mtu mtu to update.
125      * @param ret ret of GattClientCallback.
126      * @since 6
127      *
128      */
OnMtuUpdate(int mtu,int ret)129     virtual void OnMtuUpdate(int mtu, int ret)
130     {}
131 
132     /**
133      * @brief The function to OnServicesDiscovered.
134      *
135      * @param status Status object.
136      * @since 6
137      *
138      */
OnServicesDiscovered(int status)139     virtual void OnServicesDiscovered(int status)
140     {}
141 
142     /**
143      * @brief The function to OnConnectionParameterChanged.
144      *
145      * @param interval interval object.
146      * @param latency latency object.
147      * @param timeout timeout object.
148      * @param status status object.
149      * @since 6
150      *
151      */
OnConnectionParameterChanged(int interval,int latency,int timeout,int status)152     virtual void OnConnectionParameterChanged(int interval, int latency, int timeout, int status)
153     {}
154 
155     /**
156      * @brief The function to OnSetNotifyCharacteristic.
157      *
158      * @param status status object.
159      * @since 6
160      *
161      */
OnSetNotifyCharacteristic(const GattCharacteristic & characteristic,int status)162     virtual void OnSetNotifyCharacteristic(const GattCharacteristic &characteristic, int status)
163     {}
164 
165     /**
166      * @brief A destructor of GattClientCallback.
167      *
168      * @since 6
169      *
170      */
~GattClientCallback()171     virtual ~GattClientCallback()
172     {}
173 };
174 
175 /**
176  * @brief Class for GattClient functions.
177  *
178  * @since 6
179  *
180  */
181 class BLUETOOTH_API GattClient : public std::enable_shared_from_this<GattClient> {
182 public:
183 
184     /**
185      * @brief init gattClient.
186      *
187      * @return init   api init result.
188      * @since 6
189      *
190      */
191     bool Init();
192 
193     /**
194      * @brief The function to Connect.
195      *
196      * @param callback callback of gattClientCallback.
197      * @param isAutoConnect isAutoConnect of GattClient.
198      * @param transport transport of GattClient.
199      * @return int   api accept status.
200      * @since 6
201      *
202      */
203     int Connect(std::weak_ptr<GattClientCallback> callback, bool isAutoConnect, int transport);
204 
205     /**
206      * @brief The function to request connection priority.
207      *
208      * @param connPriority connPriority of GattClient.
209      * @return int   api accept status.
210      * @since 6
211      *
212      */
213     int RequestConnectionPriority(int connPriority);
214 
215     /**
216      * @brief The function to request fastest connection.
217      *
218      * @return int   api accept status.
219      */
220     int RequestFastestConn();
221 
222     /**
223      * @brief The function to disconnect.
224      *
225      * @return int   api accept status.
226      * @since 6
227      *
228      */
229     int Disconnect();
230 
231     /**
232      * @brief The function to close.
233      *
234      * @return int.
235      * @since 6
236      *
237      */
238     int Close();
239 
240     /**
241      * @brief The function to discover services.
242      *
243      * @return int    api accept status.
244      * @since 6
245      *
246      */
247     int DiscoverServices();
248 
249     /**
250      * @brief The function to get service.
251      *
252      * @param uuid uuid of GattClient.
253      * @return service.
254      * @since 6
255      *
256      */
257     std::optional<std::reference_wrapper<GattService>> GetService(const UUID &uuid);
258 
259     /**
260      * @brief The function to get service.
261      *
262      * @return list of services.
263      * @since 6
264      *
265      */
266     std::vector<GattService> &GetService();
267 
268     /**
269      * @brief The function to read characteristic.
270      *
271      * @param characteristic Characteristic object.
272      * @return int read characteristic.
273      * @since 6
274      *
275      */
276     int ReadCharacteristic(GattCharacteristic &characteristic);
277 
278     /**
279      * @brief The function to read descriptor.
280      *
281      * @param descriptor descriptor object.
282      * @return int read descriptor.
283      * @since 6
284      *
285      */
286     int ReadDescriptor(GattDescriptor &descriptor);
287 
288     /**
289      * @brief The function to RequestBleMtuSize.
290      *
291      * @param mtu mtu of GattClient.
292      * @return int request ble mtu size.
293      * @since 6
294      *
295      */
296     int RequestBleMtuSize(int mtu);
297 
298     /**
299      * @brief The function to SetNotifyCharacteristic.
300      *
301      * @param characteristic characteristic object.
302      * @param enable enable of GattClient.
303      * @return result of #GATT_STATUS.
304      * @since 6
305      *
306      */
307     int SetNotifyCharacteristic(GattCharacteristic &characteristic, bool enable);
308 
309     /**
310      * @brief The function to SetNotifyCharacteristic version 2, this funtion will not trigger onDespritor callback.
311      *
312      * @param characteristic characteristic object.
313      * @param enable enable of GattClient.
314      * @return result of #GATT_STATUS.
315      * @since 13
316      *
317      */
318     int SetNotifyCharacteristicV2(GattCharacteristic &characteristic, bool enable);
319 
320     /**
321      * @brief The function to SetIndicateCharacteristic.
322      *
323      * @param characteristic characteristic object.
324      * @param enable enable of GattClient.
325      * @return result of #GATT_STATUS.
326      * @since 6
327      *
328      */
329     int SetIndicateCharacteristic(GattCharacteristic &characteristic, bool enable);
330 
331     /**
332      * @brief The function to write characteristic.
333      *
334      * @param characteristic characteristic object.
335      * @return int write characteristic.
336      * @since 6
337      *
338      */
339     int WriteCharacteristic(GattCharacteristic &characteristic);
340 
341     /**
342      * @brief The function to write characteristic.
343      *
344      * @param characteristic characteristic object.
345      * @param value characteristic value.
346      * @return int write characteristic.
347      * @since 6
348      *
349      */
350     int WriteCharacteristic(GattCharacteristic &characteristic, std::vector<uint8_t> value);
351 
352     /**
353      * @brief The function to write characteristic.
354      *
355      * @param descriptor descriptor object.
356      * @return int write descriptor.
357      * @since 6
358      *
359      */
360     int WriteDescriptor(GattDescriptor &descriptor);
361 
362     int ReadRemoteRssiValue();
363     /**
364      * @brief A constructor of GattClient.
365      *
366      * @param device Remote device object.
367      * @since 6
368      *
369      */
370     explicit GattClient(const BluetoothRemoteDevice &device);
371 
372     /**
373      * @brief A destructor of GattClient.
374      *
375      * @since 6
376      *
377      */
378     ~GattClient();
379 
380     BLUETOOTH_DISALLOW_COPY_AND_ASSIGN(GattClient);
381 
382 private:
383     BLUETOOTH_DECLARE_IMPL();
384 
385     int SetNotifyCharacteristicInner(GattCharacteristic &characteristic, bool enable,
386         const std::vector<uint8_t> &descriptorValue);
387 };
388 } // namespace Bluetooth
389 } // namespace OHOS
390 #endif  // BLUETOOTH_GATT_CLIENT_H
391