resource/csdk/connectivity/src/bt_le_adapter/tizen/cableclient.h

   1 /* ****************************************************************
   2 *
   3 * Copyright 2014 Samsung Electronics All Rights Reserved.
   4 *
   5 *
   6 *
   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
  10 *
  11 *      http://www.apache.org/licenses/LICENSE-2.0
  12 *
  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.
  18 *
  19 ******************************************************************/
  20
  21 /**
  22  * @file
  23  *
  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.
  29  */
  30
  31 #ifndef TZ_BLE_CLIENT_H_
  32 #define TZ_BLE_CLIENT_H_
  33
  34 #include <bluetooth.h>
  35 #include <bluetooth_type.h>
  36 #include <bluetooth_product.h>
  37
  38 #include "cacommon.h"
  39 #include "caadapterutils.h"
  40 #include "cableutil.h"
  41 #include "caadapterinterface.h"
  42 #include "logger.h"
  43 #include "cathreadpool.h"
  44 #include "caleinterface.h"
  45 #include "oic_malloc.h"
  46
  47
  48 /**
  49  * @brief  This is the callback which will be called after the characteristic value changes happen.
  50  *
  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
  55  * @return  NONE
  56  */
  57 void CABleGattCharacteristicChangedCb(bt_gatt_attribute_h characteristic,
  58                             unsigned char *value, int valueLen, void *userData);
  59 /**
  60  * @brief  This is the callback which will be called after the characteristics changed.
  61  *
  62  * @param  result   [IN] result of write value
  63  * @param  userData [IN] user context
  64  *
  65  * @return  NONE
  66  */
  67 void CABleGattCharacteristicWriteCb(int result, void *userData);
  68
  69 /**
  70  * @brief  This is the callback which will be called when descriptor of characteristics is found.
  71  *
  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
  78  * @return  NONE
  79  */
  80 void CABleGattDescriptorDiscoveredCb(int result, unsigned char format, int total,
  81                                      bt_gatt_attribute_h descriptor,
  82                                      bt_gatt_attribute_h characteristic, void *userData);
  83
  84 /**
  85  * @brief  This is the callback which will be called after the characteristics are discovered by
  86  *         bt_gatt_discover_characteristics()
  87  *
  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
  93  *
  94  * @return  0 on failure and 1 on success.
  95  */
  96 bool CABleGattCharacteristicsDiscoveredCb(int result, int inputIndex, int total,
  97                                           bt_gatt_attribute_h characteristic, void *userData);
  98
  99 /**
 100  * @brief  This is the callback which will be called when we get the primary services repeatedly.
 101  *
 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
 106  *
 107  * @return  0 on failure and 1 on success.
 108  */
 109 bool CABleGattPrimaryServiceCb(bt_gatt_attribute_h service, int index, int count,
 110                                    void *userData);
 111
 112 /**
 113  * @brief  This is the callback which will be called whenever there is change in gatt connection
 114  *         with server(Connected/Disconnected)
 115  *
 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
 120  *
 121  * @return  NONE
 122  */
 123 void CABleGattConnectionStateChangedCb(int result, bool connected,
 124                 const char *remoteAddress,void *userData);
 125
 126 /**
 127  * @brief  This is the callback which will be called when the device discovery state changes.
 128  *
 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
 133  *
 134  * @return  NONE
 135  */
 136 void CABtAdapterLeDeviceDiscoveryStateChangedCb(int result,
 137         bt_adapter_le_device_discovery_state_e discoveryState,
 138         bt_adapter_le_device_discovery_info_s *discoveryInfo,
 139         void *userData);
 140
 141 /**
 142  * @brief  Used to print device information(Util method)
 143  * @param discoveryInfo [IN] Device information structure.
 144  * @return  NONE
 145  */
 146 void CAPrintDiscoveryInformation(const bt_adapter_le_device_discovery_info_s *discoveryInfo);
 147
 148 /**
 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
 153  *
 154  * @param data [IN] Currently it will be NULL(no parameter)
 155  *
 156  * @return NONE
 157  *
 158  */
 159 void CAStartBleGattClientThread(void *data);
 160
 161 /**
 162  * @brief  Used to initialize all required mutex variable for Gatt Client implementation.
 163  *
 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
 168  */
 169 CAResult_t CAInitGattClientMutexVariables();
 170
 171 /**
 172  * @brief  Used to terminate all required mutex variable for Gatt Client implementation.
 173  * @return NONE
 174  */
 175 void CATerminateGattClientMutexVariables();
 176
 177 /**
 178  * @brief  Used to clear NonOICDeviceList
 179  * @return NONE
 180  */
 181 void CAClearNonOICDeviceList();
 182
 183 /**
 184  * @brief  Used to set scan parameter of starting discovery.
 185  *
 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
 190  */
 191 CAResult_t CABleGattSetScanParameter();
 192
 193 /**
 194  * @brief  Used to register required callbacks to BLE platform(connection, discovery, etc).
 195  *
 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
 200  */
 201 CAResult_t CABleGattSetCallbacks();
 202
 203 /**
 204  * @brief  Used to unset all the registerd callbacks to BLE platform
 205  * @return NONE
 206  */
 207 void CABleGattUnSetCallbacks();
 208
 209 /**
 210  * @brief  Used to watch all the changes happening in characteristics of the service.
 211  *
 212  * @param service [IN] The attribute handle of the service.
 213  *
 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
 218  */
 219 CAResult_t CABleGattWatchCharacteristicChanges(bt_gatt_attribute_h service);
 220
 221 /**
 222  * @brief  Used to unwatch characteristics changes using bt_gatt_unwatch_characteristic_changes
 223  * @return NONE
 224  */
 225 void CABleGattUnWatchCharacteristicChanges();
 226
 227 /**
 228  * @brief  Used to start LE discovery for BLE  devices
 229  *
 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
 234  */
 235 CAResult_t CABleGattStartDeviceDiscovery();
 236
 237 /**
 238  * @brief  Used to stop LE discovery for BLE  devices
 239  * @return NONE
 240  */
 241 void CABleGattStopDeviceDiscovery();
 242
 243 /**
 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
 246  * @return NONE
 247  */
 248 void CAGattConnectThread (void *remoteAddress);
 249
 250 /**
 251  * @brief  Used to do connection with remote device
 252  *
 253  * @param remoteAddress [IN] Remote address inwhich we wants to connect with
 254  *
 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
 259  */
 260 CAResult_t CABleGattConnect(const char *remoteAddress);
 261
 262 /**
 263  * @brief  Used to do disconnection with remote device
 264  * @param remoteAddress [IN] Remote address inwhich we wants to disconnect with
 265  *
 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
 270  */
 271 CAResult_t CABleGattDisConnect(const char *remoteAddress);
 272
 273 /**
 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.
 277  * @return  NONE
 278  */
 279 void CADiscoverBLEServicesThread (void *remoteAddress);
 280
 281 /**
 282  * @brief Used to discover the services that is advertised by Gatt Server asynchrounously.
 283  *
 284  * @param remoteAddress [IN] MAC address of remote device in which we want to discover the services.
 285  *
 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
 290  */
 291 CAResult_t CABleGattDiscoverServices(const char *remoteAddress);
 292
 293 /**
 294  * @brief  This is the thread which will be used for finding characteristic of a service.
 295  *
 296  * @param  stServiceInfo [IN] Service Information which contains the remote address, service
 297  *                            handle and characteristic handle.
 298  * @return  NONE
 299  */
 300 void CADiscoverCharThread(void *stServiceInfo);
 301
 302 /**
 303  * @brief  Used to discover characteristics of service using  bt_gatt_discover_characteristics api.
 304  *
 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
 312  */
 313 CAResult_t CABleGattDiscoverCharacteristics(bt_gatt_attribute_h service,
 314                     const char *remoteAddress);
 315
 316 /**
 317  * @brief  This is the thread which will be used for finding descriptor of characteristic.
 318  *
 319  * @param  stServiceInfo [IN] Service Information which contains the remote address, service
 320  *                            handle and characteristic handle.
 321  * @return  NONE
 322  */
 323 void CADiscoverDescriptorThread(void *stServiceInfo);
 324
 325 /**
 326  * @brief  This is thread which will be used for calling CASetCharacteristicDescriptorValue api.
 327  *
 328  * @param service       [IN]  The attribute handle for characteristics.
 329  * @param remoteAddress [IN]  Remote address inwhich we wants to discover descriptor of given
 330  *                            char handle.
 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
 335  */
 336 CAResult_t CABleGattDiscoverDescriptor(bt_gatt_attribute_h service,
 337                 const char *remoteAddress);
 338
 339 /**
 340  * @brief  This is thread which will be used for calling CASetCharacteristicDescriptorValue api.
 341  *
 342  * @param  stServiceInfo [IN] Service Information which contains the remote address, service
 343  *                            handle and characteristic handle.
 344  * @return NONE
 345  */
 346 void CASetCharacteristicDescriptorValueThread(void *stServiceInfo);
 347
 348 /**
 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.
 352  *
 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
 357  */
 358 CAResult_t CASetCharacteristicDescriptorValue
 359             (stGattCharDescriptor_t *stGattCharDescriptorInfo);
 360
 361 /**
 362  * @brief  Used to enqueue the message into sender queue using CAAdapterEnqueueMessage and make
 363  *         signal to the thread to process.
 364  *
 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.
 368  *
 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
 373  */
 374 CAResult_t CABleClientSenderQueueEnqueueMessage
 375                             (const CARemoteEndpoint_t *remoteEndpoint,
 376                                                 const void *data, uint32_t dataLen);
 377
 378 /**
 379  * @brief  This is the thread which will be used for processing sender queue.
 380  *
 381  * @return  NONE
 382  */
 383 void CABleClientSenderQueueProcessor();
 384
 385 /**
 386  * @brief Synchronous function for reading characteristic value.
 387  *
 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
 392  */
 393 CAResult_t CALEReadDataFromLEClient();
 394
 395 #endif /* TZ_BLE_CLIENT_H_ */
 396