1 /* ****************************************************************
3 * Copyright 2014 Samsung Electronics All Rights Reserved.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
19 ******************************************************************/
24 * This file contains the functionalities of GATT Client. Functionalities
25 * like LE device discovery, connecting to the LE device with OIC service,
26 * registering to the service and there characteristics, registering to the
27 * change in the charateristics, setting the value of the characteristcs
28 * for the request and response will be done here.
31 #ifndef TZ_BLE_CLIENT_H_
32 #define TZ_BLE_CLIENT_H_
34 #include <bluetooth.h>
35 #include <bluetooth_type.h>
36 #include <bluetooth_product.h>
39 #include "caadapterutils.h"
40 #include "cableutil.h"
41 #include "caadapterinterface.h"
43 #include "cathreadpool.h"
44 #include "caleinterface.h"
45 #include "oic_malloc.h"
49 * @brief This is the callback which will be called after the characteristic value changes happen.
51 * @param characteristic [IN] The attribute handle of characteristic
52 * @param value [IN] Value of the characteristics of a service.
53 * @param valueLen [IN] length of data.
54 * @param userData [IN] The user data passed from the request function
57 void CABleGattCharacteristicChangedCb(bt_gatt_attribute_h characteristic,
58 unsigned char *value, int valueLen, void *userData);
60 * @brief This is the callback which will be called after the characteristics changed.
62 * @param result [IN] result of write value
63 * @param userData [IN] user context
67 void CABleGattCharacteristicWriteCb(int result, void *userData);
70 * @brief This is the callback which will be called when descriptor of characteristics is found.
72 * @param result [IN] The result of discovering
73 * @param format [IN] format of descriptor.
74 * @param total [IN] The total number of descriptor in a characteristic
75 * @param descriptor [IN] The attribute handle of descriptor
76 * @param characteristic [IN] The attribute handle of characteristic
77 * @param userData [IN] The user data passed from the request function
80 void CABleGattDescriptorDiscoveredCb(int result, unsigned char format, int total,
81 bt_gatt_attribute_h descriptor,
82 bt_gatt_attribute_h characteristic, void *userData);
85 * @brief This is the callback which will be called after the characteristics are discovered by
86 * bt_gatt_discover_characteristics()
88 * @param result [IN] The result of discovering
89 * @param inputIndex [IN] The index of characteristics in a service, starts from 0
90 * @param total [IN] The total number of characteristics in a service
91 * @param characteristic [IN] The attribute handle of characteristic
92 * @param userData [IN] The user data passed from the request function
94 * @return 0 on failure and 1 on success.
96 bool CABleGattCharacteristicsDiscoveredCb(int result, int inputIndex, int total,
97 bt_gatt_attribute_h characteristic, void *userData);
100 * @brief This is the callback which will be called when we get the primary services repeatedly.
102 * @param service [IN] The attribute handle of service. Unique identifier for service.
103 * @param index [IN] The current index of the service
104 * @param count [IN] Total number of services available in remote device
105 * @param userData [IN] user data
107 * @return 0 on failure and 1 on success.
109 bool CABleGattPrimaryServiceCb(bt_gatt_attribute_h service, int index, int count,
113 * @brief This is the callback which will be called whenever there is change in gatt connection
114 * with server(Connected/Disconnected)
116 * @param result [IN] The result of discovering
117 * @param connected [IN] State of connection
118 * @param remoteAddress [IN] Mac address of the remote device in which we made connection.
119 * @param userData [IN] The user data passed from the request function
123 void CABleGattConnectionStateChangedCb(int result, bool connected,
124 const char *remoteAddress,void *userData);
127 * @brief This is the callback which will be called when the device discovery state changes.
129 * @param result [IN] The result of discovering
130 * @param discoveryState [IN] State of the discovery(FOUND/STARTED/ FINISHED)
131 * @param discoveryInfo [IN] Remote Device information.
132 * @param userData [IN] The user data passed from the request function
136 void CABtAdapterLeDeviceDiscoveryStateChangedCb(int result,
137 bt_adapter_le_device_discovery_state_e discoveryState,
138 bt_adapter_le_device_discovery_info_s *discoveryInfo,
142 * @brief Used to print device information(Util method)
143 * @param discoveryInfo [IN] Device information structure.
146 void CAPrintDiscoveryInformation(const bt_adapter_le_device_discovery_info_s *discoveryInfo);
149 * @brief This thread will be used to initialize the Gatt Client and start device discovery.
150 * 1. Set scan parameters
151 * 2. Setting neccessary callbacks for connection, characteristics changed and discovery.
152 * 3. Start device discovery
154 * @param data [IN] Currently it will be NULL(no parameter)
159 void CAStartBleGattClientThread(void *data);
162 * @brief Used to initialize all required mutex variable for Gatt Client implementation.
164 * @return #CA_STATUS_OK or Appropriate error code
165 * @retval #CA_STATUS_OK Successful
166 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
167 * @retval #CA_STATUS_FAILED Operation failed
169 CAResult_t CAInitGattClientMutexVariables();
172 * @brief Used to terminate all required mutex variable for Gatt Client implementation.
175 void CATerminateGattClientMutexVariables();
178 * @brief Used to clear NonOICDeviceList
181 void CAClearNonOICDeviceList();
184 * @brief Used to set scan parameter of starting discovery.
186 * @return #CA_STATUS_OK or Appropriate error code
187 * @retval #CA_STATUS_OK Successful
188 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
189 * @retval #CA_STATUS_FAILED Operation failed
191 CAResult_t CABleGattSetScanParameter();
194 * @brief Used to register required callbacks to BLE platform(connection, discovery, etc).
196 * @return #CA_STATUS_OK or Appropriate error code
197 * @retval #CA_STATUS_OK Successful
198 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
199 * @retval #CA_STATUS_FAILED Operation failed
201 CAResult_t CABleGattSetCallbacks();
204 * @brief Used to unset all the registerd callbacks to BLE platform
207 void CABleGattUnSetCallbacks();
210 * @brief Used to watch all the changes happening in characteristics of the service.
212 * @param service [IN] The attribute handle of the service.
214 * @return #CA_STATUS_OK or Appropriate error code
215 * @retval #CA_STATUS_OK Successful
216 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
217 * @retval #CA_STATUS_FAILED Operation failed
219 CAResult_t CABleGattWatchCharacteristicChanges(bt_gatt_attribute_h service);
222 * @brief Used to unwatch characteristics changes using bt_gatt_unwatch_characteristic_changes
225 void CABleGattUnWatchCharacteristicChanges();
228 * @brief Used to start LE discovery for BLE devices
230 * @return #CA_STATUS_OK or Appropriate error code
231 * @retval #CA_STATUS_OK Successful
232 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
233 * @retval #CA_STATUS_FAILED Operation failed
235 CAResult_t CABleGattStartDeviceDiscovery();
238 * @brief Used to stop LE discovery for BLE devices
241 void CABleGattStopDeviceDiscovery();
244 * @brief This is the thread which will be used for making gatt connection with remote devices
245 * @param remoteAddress [IN] MAC address of remote device to connect
248 void CAGattConnectThread (void *remoteAddress);
251 * @brief Used to do connection with remote device
253 * @param remoteAddress [IN] Remote address inwhich we wants to connect with
255 * @return #CA_STATUS_OK or Appropriate error code
256 * @retval #CA_STATUS_OK Successful
257 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
258 * @retval #CA_STATUS_FAILED Operation failed
260 CAResult_t CABleGattConnect(const char *remoteAddress);
263 * @brief Used to do disconnection with remote device
264 * @param remoteAddress [IN] Remote address inwhich we wants to disconnect with
266 * @return #CA_STATUS_OK or Appropriate error code
267 * @retval #CA_STATUS_OK Successful
268 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
269 * @retval #CA_STATUS_FAILED Operation failed
271 CAResult_t CABleGattDisConnect(const char *remoteAddress);
274 * @brief This is thread which will be spawned for discovering ble services. Once called discover
275 * api, then it will be terminated.
276 * @param remoteAddress [IN] Mac address of the remote device in which we want to search services.
279 void CADiscoverBLEServicesThread (void *remoteAddress);
282 * @brief Used to discover the services that is advertised by Gatt Server asynchrounously.
284 * @param remoteAddress [IN] MAC address of remote device in which we want to discover the services.
286 * @return #CA_STATUS_OK or Appropriate error code
287 * @retval #CA_STATUS_OK Successful
288 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
289 * @retval #CA_STATUS_FAILED Operation failed
291 CAResult_t CABleGattDiscoverServices(const char *remoteAddress);
294 * @brief This is the thread which will be used for finding characteristic of a service.
296 * @param stServiceInfo [IN] Service Information which contains the remote address, service
297 * handle and characteristic handle.
300 void CADiscoverCharThread(void *stServiceInfo);
303 * @brief Used to discover characteristics of service using bt_gatt_discover_characteristics api.
305 * @param service [IN] The attribute handle for service.
306 * @param remoteAddress [IN] Remote address inwhich we wants to discover characteristics of
307 * given service handle.
308 * @return #CA_STATUS_OK or Appropriate error code
309 * @retval #CA_STATUS_OK Successful
310 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
311 * @retval #CA_STATUS_FAILED Operation failed
313 CAResult_t CABleGattDiscoverCharacteristics(bt_gatt_attribute_h service,
314 const char *remoteAddress);
317 * @brief This is the thread which will be used for finding descriptor of characteristic.
319 * @param stServiceInfo [IN] Service Information which contains the remote address, service
320 * handle and characteristic handle.
323 void CADiscoverDescriptorThread(void *stServiceInfo);
326 * @brief This is thread which will be used for calling CASetCharacteristicDescriptorValue api.
328 * @param service [IN] The attribute handle for characteristics.
329 * @param remoteAddress [IN] Remote address inwhich we wants to discover descriptor of given
331 * @return #CA_STATUS_OK or Appropriate error code
332 * @retval #CA_STATUS_OK Successful
333 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
334 * @retval #CA_STATUS_FAILED Operation failed
336 CAResult_t CABleGattDiscoverDescriptor(bt_gatt_attribute_h service,
337 const char *remoteAddress);
340 * @brief This is thread which will be used for calling CASetCharacteristicDescriptorValue api.
342 * @param stServiceInfo [IN] Service Information which contains the remote address, service
343 * handle and characteristic handle.
346 void CASetCharacteristicDescriptorValueThread(void *stServiceInfo);
349 * @brief Used to set characteristic descriptor value using
350 * bt_gatt_set_characteristic_desc_value_request api.
351 * @param stGattCharDescriptorInfo [IN] Structure which contains char handle and descriptor handle.
353 * @return #CA_STATUS_OK or Appropriate error code
354 * @retval #CA_STATUS_OK Successful
355 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
356 * @retval #CA_STATUS_FAILED Operation failed
358 CAResult_t CASetCharacteristicDescriptorValue
359 (stGattCharDescriptor_t *stGattCharDescriptorInfo);
362 * @brief Used to enqueue the message into sender queue using CAAdapterEnqueueMessage and make
363 * signal to the thread to process.
365 * @param remoteEndpoint [IN] Remote device information
366 * @param data [IN] Data to be sent to remote device
367 * @param dataLen [IN] Length of data.
369 * @return #CA_STATUS_OK or Appropriate error code
370 * @retval #CA_STATUS_OK Successful
371 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
372 * @retval #CA_STATUS_FAILED Operation failed
374 CAResult_t CABleClientSenderQueueEnqueueMessage
375 (const CAEndpoint_t *remoteEndpoint,
376 const void *data, uint32_t dataLen);
379 * @brief This is the thread which will be used for processing sender queue.
383 void CABleClientSenderQueueProcessor();
386 * @brief Synchronous function for reading characteristic value.
388 * @return #CA_STATUS_OK or Appropriate error code
389 * @retval #CA_STATUS_OK Successful
390 * @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
391 * @retval #CA_STATUS_FAILED Operation failed
393 CAResult_t CALEReadDataFromLEClient();
395 #endif /* TZ_BLE_CLIENT_H_ */