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 _BLE_CLIENT_
  32 #define _BLE_CLIENT_
  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 bond created with remote device.
 101  *
 102  * @param  result      [IN] The result of bond creation.
 103  * @param  device_info [IN] remote device information
 104  * @param  userData    [IN] The user data passed from the request function
 105  * @return  NONE
 106  */
 107 void CABtGattBondCreatedCb(int result, bt_device_info_s *device_info, void *user_data);
 108
 109 /**
 110  * @brief  This is the callback which will be called when we get the primary services repeatedly.
 111  *
 112  * @param service  [IN] The attribute handle of service. Unique identifier for service.
 113  * @param index    [IN] The current index of the service
 114  * @param count    [IN] Total number of services available in remote device
 115  * @param userData [IN] user data
 116  *
 117  * @return  0 on failure and 1 on success.
 118  */
 119 bool CABleGattPrimaryServiceCb(bt_gatt_attribute_h service, int index, int count,
 120                                    void *userData);
 121
 122 /**
 123  * @brief  This is the callback which will be called whenever there is change in gatt connection
 124  *         with server(Connected/Disconnected)
 125  *
 126  * @param  result        [IN] The result of discovering
 127  * @param  connected     [IN] State of connection
 128  * @param  remoteAddress [IN] Mac address of the remote device in which we made connection.
 129  * @param  userData      [IN] The user data passed from the request function
 130  *
 131  * @return  NONE
 132  */
 133 void CABleGattConnectionStateChangedCb(int result, bool connected,
 134                 const char *remoteAddress,void *userData);
 135
 136 /**
 137  * @brief  This is the callback which will be called when the device discovery state changes.
 138  *
 139  * @param  result         [IN] The result of discovering
 140  * @param  discoveryState [IN] State of the discovery(FOUND/STARTED/ FINISHED)
 141  * @param  discoveryInfo  [IN] Remote Device information.
 142  * @param  userData       [IN] The user data passed from the request function
 143  *
 144  * @return  NONE
 145  */
 146 void CABtAdapterLeDeviceDiscoveryStateChangedCb(int result,
 147         bt_adapter_le_device_discovery_state_e discoveryState,
 148         bt_adapter_le_device_discovery_info_s *discoveryInfo,
 149         void *userData);
 150
 151 /**
 152  * @brief  Used to print device information(Util method)
 153  * @param discoveryInfo [IN] Device information structure.
 154  * @return  NONE
 155  */
 156 void CAPrintDiscoveryInformation(const bt_adapter_le_device_discovery_info_s *discoveryInfo);
 157
 158 /**
 159  * @brief This thread will be used to initialize the Gatt Client and start device discovery.
 160  *        1. Set scan parameters
 161  *        2. Setting neccessary callbacks for connection, characteristics changed and discovery
 162  *           and bond creation.
 163  *        3. Start device discovery
 164  *
 165  * @param data [IN] Currently it will be NULL(no parameter)
 166  *
 167  * @return NONE
 168  *
 169  */
 170 void CAStartBleGattClientThread(void *data);
 171
 172 /**
 173  * @brief  Used to initialize all required mutex variable for Gatt Client implementation.
 174  *
 175  * @return #CA_STATUS_OK or Appropriate error code
 176  * @retval #CA_STATUS_OK  Successful
 177  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 178  * @retval #CA_STATUS_FAILED Operation failed
 179  */
 180 CAResult_t CAInitGattClientMutexVariables();
 181
 182 /**
 183  * @brief  Used to terminate all required mutex variable for Gatt Client implementation.
 184  * @return NONE
 185  */
 186 void CATerminateGattClientMutexVariables();
 187
 188 /**
 189  * @brief  Used to clear NonOICDeviceList
 190  * @return NONE
 191  */
 192 void CAClearNonOICDeviceList();
 193
 194 /**
 195  * @brief  Used to set scan parameter of starting discovery.
 196  *
 197  * @return #CA_STATUS_OK or Appropriate error code
 198  * @retval #CA_STATUS_OK  Successful
 199  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 200  * @retval #CA_STATUS_FAILED Operation failed
 201  */
 202 CAResult_t CABleGattSetScanParameter();
 203
 204 /**
 205  * @brief  Used to register required callbacks to BLE platform(connection, discovery, bond and etc).
 206  *
 207  * @return #CA_STATUS_OK or Appropriate error code
 208  * @retval #CA_STATUS_OK  Successful
 209  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 210  * @retval #CA_STATUS_FAILED Operation failed
 211  */
 212 CAResult_t CABleGattSetCallbacks();
 213
 214 /**
 215  * @brief  Used to unset all the registerd callbacks to BLE platform
 216  * @return NONE
 217  */
 218 void CABleGattUnSetCallbacks();
 219
 220 /**
 221  * @brief  Used to watch all the changes happening in characteristics of the service.
 222  *
 223  * @param service [IN] The attribute handle of the service.
 224  *
 225  * @return #CA_STATUS_OK or Appropriate error code
 226  * @retval #CA_STATUS_OK  Successful
 227  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 228  * @retval #CA_STATUS_FAILED Operation failed
 229  */
 230 CAResult_t CABleGattWatchCharacteristicChanges(bt_gatt_attribute_h service);
 231
 232 /**
 233  * @brief  Used to unwatch characteristics changes using bt_gatt_unwatch_characteristic_changes
 234  * @return NONE
 235  */
 236 void CABleGattUnWatchCharacteristicChanges();
 237
 238 /**
 239  * @brief  Used to start LE discovery for BLE  devices
 240  *
 241  * @return #CA_STATUS_OK or Appropriate error code
 242  * @retval #CA_STATUS_OK  Successful
 243  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 244  * @retval #CA_STATUS_FAILED Operation failed
 245  */
 246 CAResult_t CABleGattStartDeviceDiscovery();
 247
 248 /**
 249  * @brief  Used to stop LE discovery for BLE  devices
 250  * @return NONE
 251  */
 252 void CABleGattStopDeviceDiscovery();
 253
 254 /**
 255  * @brief  This is the thread  which will be used for making gatt connection with remote devices
 256  * @param remoteAddress [IN] MAC address of remote device to connect
 257  * @return NONE
 258  */
 259 void CAGattConnectThread (void *remoteAddress);
 260
 261 /**
 262  * @brief  Used to do connection with remote device
 263  *
 264  * @param remoteAddress [IN] Remote address inwhich we wants to connect 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 CABleGattConnect(const char *remoteAddress);
 272
 273 /**
 274  * @brief  Used to do disconnection with remote device
 275  * @param remoteAddress [IN] Remote address inwhich we wants to disconnect with
 276  *
 277  * @return #CA_STATUS_OK or Appropriate error code
 278  * @retval #CA_STATUS_OK  Successful
 279  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 280  * @retval #CA_STATUS_FAILED Operation failed
 281  */
 282 CAResult_t CABleGattDisConnect(const char *remoteAddress);
 283
 284 /**
 285  * @brief  This is thread which will be spawned for discovering ble services. Once called discover
 286  *         api, then it will be terminated.
 287  * @param remoteAddress [IN] Mac address of the remote device in which we want to search services.
 288  * @return  NONE
 289  */
 290 void CADiscoverBLEServicesThread (void *remoteAddress);
 291
 292 /**
 293  * @brief Used to discover the services that is advertised by Gatt Server asynchrounously.
 294  *
 295  * @param remoteAddress [IN] MAC address of remote device in which we want to discover the services.
 296  *
 297  * @return #CA_STATUS_OK or Appropriate error code
 298  * @retval #CA_STATUS_OK  Successful
 299  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 300  * @retval #CA_STATUS_FAILED Operation failed
 301  */
 302 CAResult_t CABleGattDiscoverServices(const char *remoteAddress);
 303
 304 /**
 305  * @brief  This is the thread which will be used for finding characteristic of a service.
 306  *
 307  * @param  stServiceInfo [IN] Service Information which contains the remote address, service
 308  *                            handle and characteristic handle.
 309  * @return  NONE
 310  */
 311 void CADiscoverCharThread(void *stServiceInfo);
 312
 313 /**
 314  * @brief  Used to discover characteristics of service using  bt_gatt_discover_characteristics api.
 315  *
 316  * @param service       [IN]  The attribute handle for service.
 317  * @param remoteAddress [IN]  Remote address inwhich we wants to discover characteristics of
 318  *                            given service handle.
 319  * @return #CA_STATUS_OK or Appropriate error code
 320  * @retval #CA_STATUS_OK  Successful
 321  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 322  * @retval #CA_STATUS_FAILED Operation failed
 323  */
 324 CAResult_t CABleGattDiscoverCharacteristics(bt_gatt_attribute_h service,
 325                     const char *remoteAddress);
 326
 327 /**
 328  * @brief  This is the thread which will be used for finding descriptor of characteristic.
 329  *
 330  * @param  stServiceInfo [IN] Service Information which contains the remote address, service
 331  *                            handle and characteristic handle.
 332  * @return  NONE
 333  */
 334 void CADiscoverDescriptorThread(void *stServiceInfo);
 335
 336 /**
 337  * @brief  This is thread which will be used for calling CASetCharacteristicDescriptorValue api.
 338  *
 339  * @param service       [IN]  The attribute handle for characteristics.
 340  * @param remoteAddress [IN]  Remote address inwhich we wants to discover descriptor of given
 341  *                            char handle.
 342  * @return #CA_STATUS_OK or Appropriate error code
 343  * @retval #CA_STATUS_OK  Successful
 344  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 345  * @retval #CA_STATUS_FAILED Operation failed
 346  */
 347 CAResult_t CABleGattDiscoverDescriptor(bt_gatt_attribute_h service,
 348                 const char *remoteAddress);
 349
 350 /**
 351  * @brief  This is thread which will be used for calling CASetCharacteristicDescriptorValue api.
 352  *
 353  * @param  stServiceInfo [IN] Service Information which contains the remote address, service
 354  *                            handle and characteristic handle.
 355  * @return NONE
 356  */
 357 void CASetCharacteristicDescriptorValueThread(void *stServiceInfo);
 358
 359 /**
 360  * @brief  Used to set characteristic descriptor value using
 361  *         bt_gatt_set_characteristic_desc_value_request api.
 362  * @param  stGattCharDescriptorInfo [IN] Structure which contains char handle and descriptor handle.
 363  *
 364  * @return #CA_STATUS_OK or Appropriate error code
 365  * @retval #CA_STATUS_OK  Successful
 366  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 367  * @retval #CA_STATUS_FAILED Operation failed
 368  */
 369 CAResult_t CASetCharacteristicDescriptorValue
 370             (stGattCharDescriptor_t *stGattCharDescriptorInfo);
 371
 372 /**
 373  * @brief  This is the thread  which will be used for creating bond with remote device.
 374  *
 375  * @param  stServiceInfo [IN] Service Information which contains the remote address and service
 376  *                            handle, characteristic handle.
 377  * @return  NONE
 378  */
 379 void CAGATTCreateBondThread(void *stServiceInfo);
 380
 381 /**
 382  * @brief  Used to make LE bond with remote device(pairng the device) using bt_device_create_bond
 383  *         api.
 384  * @param  remoteAddress [IN] MAC address of remote device with which we want to bond
 385  *
 386  * @return #CA_STATUS_OK or Appropriate error code
 387  * @retval #CA_STATUS_OK  Successful
 388  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 389  * @retval #CA_STATUS_FAILED Operation failed
 390  */
 391 CAResult_t CABleGATTCreateBond(const char *remoteAddress);
 392
 393 /**
 394  * @brief  Used to enqueue the message into sender queue using CAAdapterEnqueueMessage and make
 395  *         signal to the thread to process.
 396  *
 397  * @param  remoteEndpoint [IN] Remote device information
 398  * @param  data           [IN] Data to be sent to remote device
 399  * @param  dataLen        [IN] Length of data.
 400  *
 401  * @return #CA_STATUS_OK or Appropriate error code
 402  * @retval #CA_STATUS_OK  Successful
 403  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 404  * @retval #CA_STATUS_FAILED Operation failed
 405  */
 406 CAResult_t CABleClientSenderQueueEnqueueMessage
 407                             (const CARemoteEndpoint_t *remoteEndpoint,
 408                                                 const void *data, uint32_t dataLen);
 409
 410 /**
 411  * @brief  This is the thread which will be used for processing sender queue.
 412  *
 413  * @return  NONE
 414  */
 415 void CABleClientSenderQueueProcessor();
 416
 417 /**
 418  * @brief Synchronous function for reading characteristic value.
 419  *
 420  * @return #CA_STATUS_OK or Appropriate error code
 421  * @retval #CA_STATUS_OK  Successful
 422  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 423  * @retval #CA_STATUS_FAILED Operation failed
 424  */
 425 CAResult_t CALEReadDataFromLEClient();
 426
 427 #endif //#ifndef _BLE_CLIENT_
 428