resource/csdk/connectivity/inc/caleinterface.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  * This file provides APIs for BLE modules.
  23  */
  24
  25 #ifndef CA_LE_INTERFACE_H_
  26 #define CA_LE_INTERFACE_H_
  27
  28 #include <stdbool.h>
  29
  30 #include "cacommon.h"
  31 #include "cathreadpool.h"
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #endif
  37
  38 /**
  39  * Provide info about different mode of data transfer.
  40  *
  41  * This enum is used to differentiate between unicast and multicast
  42  * data transfer.
  43  */
  44 typedef enum
  45 {
  46     LE_MULTICAST,    /**< When this enum is selected, data will be updated to all OIC servers. */
  47     LE_UNICAST       /**< When this enum is selected, data will be updated to desired OIC Server. */
  48 } CALETransferType_t;
  49
  50 /**
  51  * This will be used to notify device status changes to the LE adapter layer.
  52  * @param[in]  adapter_state State of the adapter.
  53  */
  54 typedef void (*CALEDeviceStateChangedCallback)(CAAdapterState_t adapter_state);
  55
  56 /**
  57  * Notify the adapter layer that a packet was received from the GATT
  58  * peer.
  59  *
  60  * @param[in]  remoteAddress  Remote endpoint Address.
  61  * @param[in]  data           Data received.
  62  * @param[in]  dataLength     Length of the data received.
  63  * @param[in]  sentLength     Length of the data sent.
  64  *
  65  * @return ::CA_STATUS_OK or Appropriate error code.
  66  * @retval ::CA_STATUS_OK  Successful.
  67  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
  68  * @retval ::CA_STATUS_FAILED Operation failed.
  69  */
  70 typedef CAResult_t (*CABLEDataReceivedCallback)(const char *remoteAddress,
  71                                                 const void *data,
  72                                                 uint32_t dataLength,
  73                                                 uint32_t *sentLength);
  74
  75 /**
  76  * Initialize the LE adapter layer. This will be invoked from the CA
  77  * layer.
  78  *
  79  * @return ::CA_STATUS_OK or Appropriate error code
  80  * @retval ::CA_STATUS_OK  Successful
  81  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
  82  * @retval ::CA_STATUS_FAILED Operation failed
  83  */
  84 CAResult_t CAInitializeLEAdapter();
  85
  86 /**
  87  * Start the LE adapter layer.
  88  *
  89  * This function will be invoked from the CA layer when the LE
  90  * "network" is selected via @c CASelectNetwork().  It gives an
  91  * opportunity for LE adapter implementations to perform operations
  92  * before starting a GATT client or server.  Most LE adapter
  93  * implementations will simply implement this function as no-op.
  94  *
  95  * @return ::CA_STATUS_OK or Appropriate error code
  96  */
  97 CAResult_t CAStartLEAdapter();
  98
  99 /**
 100  * Used to get the current state of the LE adapter.
 101  *
 102  * @return ::CA_STATUS_OK or Appropriate error code
 103  * @retval ::CA_STATUS_OK  Successful
 104  * @retval ::CA_ADAPTER_NOT_ENABLED  adapter not enabled
 105  * @retval ::CA_STATUS_FAILED Operation failed
 106  */
 107 CAResult_t CAGetLEAdapterState();
 108
 109 /**
 110  * Initialize the network monitor layer of the LE adapter.  Mutex
 111  * variables required to operate in this layer and other parameters
 112  * can be initialized in this function.
 113  *
 114  * @return ::CA_STATUS_OK or Appropriate error code
 115  * @retval ::CA_STATUS_OK  Successful
 116  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 117  * @retval ::CA_STATUS_FAILED Operation failed
 118  */
 119 CAResult_t CAInitializeLENetworkMonitor();
 120
 121 /**
 122  * Terminate the network monitor layer of the LE adapter. The
 123  * variables initialized in @c CAInitializeLENetworkMonitor() must be
 124  * cleared in this function.
 125  */
 126 void CATerminateLENetworkMonitor();
 127
 128 /**
 129  * Set the callback for the device state changes in the adapter.
 130  *
 131  * @param[in] callback Callback to notify the Device state change to
 132  *            the CA Layer
 133  *
 134  * @return ::CA_STATUS_OK or Appropriate error code
 135  * @retval ::CA_STATUS_OK  Successful
 136  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 137  * @retval ::CA_STATUS_FAILED Operation failed
 138  */
 139 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
 140
 141 /**
 142  * Initialize all the mutex variables required to operate the LE
 143  * network monitor layer.
 144  *
 145  * @return ::CA_STATUS_OK or Appropriate error code
 146  * @retval ::CA_STATUS_OK  Successful
 147  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 148  * @retval ::CA_STATUS_FAILED Operation failed
 149  */
 150 CAResult_t CAInitLENetworkMonitorMutexVariables();
 151
 152 /**
 153  * Used to terminate all the mutex variables required to operate the LE
 154  * network monitor layer.
 155  */
 156 void CATerminateLENetworkMonitorMutexVariables();
 157
 158 /**
 159  * Provides the MAC address of the local Bluetooth adapter.
 160  *
 161  * @param[out] local_address Pointer to the location where bd address
 162  *                           needs to be stored.
 163  *
 164  * @return ::CA_STATUS_OK or Appropriate error code
 165  * @retval ::CA_STATUS_OK  Successful
 166  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 167  * @retval ::CA_STATUS_FAILED Operation failed
 168  */
 169 CAResult_t CAGetLEAddress(char **local_address);
 170
 171 /**
 172  * Start Gatt Server thread for service creation and advertise BLE
 173  * service.
 174  *
 175  * @return ::CA_STATUS_OK or Appropriate error code
 176  * @retval ::CA_STATUS_OK  Successful
 177  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 178  * @retval ::CA_STATUS_FAILED Operation failed
 179  */
 180 CAResult_t CAStartLEGattServer();
 181
 182 /**
 183  * Stop BLE Gatt Service.
 184  *
 185  * @return ::CA_STATUS_OK or Appropriate error code
 186  * @retval ::CA_STATUS_OK  Successful
 187  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 188  * @retval ::CA_STATUS_FAILED Operation failed
 189  */
 190 CAResult_t CAStopLEGattServer();
 191
 192 /**
 193  * Stop Gatt Server thread and remove service registration, stop
 194  * advertising.
 195  */
 196 void CATerminateLEGattServer();
 197
 198 /**
 199  * Used to store upper layer callback locally which will be used to
 200  * send the data to application.
 201  *
 202  * @param[in] callback Callback function to pass the data to CA layer.
 203  */
 204 void CASetLEReqRespServerCallback(CABLEDataReceivedCallback callback);
 205
 206 /**
 207  * Update characteristics(Read/Write) value that we want to send to
 208  * particular client.
 209  *
 210  * @param[in] address      BD address of Gatt client
 211  * @param[in] charValue    Data that we want to send to client(unicast)
 212  * @param[in] charValueLen Length of the data.
 213  *
 214  * @return ::CA_STATUS_OK or Appropriate error code
 215  * @retval ::CA_STATUS_OK  Successful
 216  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 217  * @retval ::CA_STATUS_FAILED Operation failed
 218  */
 219 CAResult_t CAUpdateCharacteristicsToGattClient(const char *address,
 220                                                const char *charValue,
 221                                                uint32_t charValueLen);
 222
 223 /**
 224  * Update characteristics(Read/Write) value that we want to multicast
 225  * to all clients.
 226  *
 227  * @param[in] charValue    Data that we want to send to clients(multicast)
 228  * @param[in] charValueLen Length of the data.
 229  *
 230  * @return ::CA_STATUS_OK or Appropriate error code
 231  * @retval ::CA_STATUS_OK  Successful
 232  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 233  * @retval ::CA_STATUS_FAILED Operation failed
 234  */
 235 CAResult_t CAUpdateCharacteristicsToAllGattClients(const char *charValue,
 236                                                    uint32_t charValueLen);
 237
 238 /**
 239  * Start @c CAStartBleGattClientThread for initializing Gatt Client.
 240  *
 241  * @return ::CA_STATUS_OK or Appropriate error code
 242  * @retval ::CA_STATUS_OK  Successful
 243  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 244  * @retval ::CA_STATUS_FAILED Operation failed
 245  */
 246 CAResult_t CAStartLEGattClient();
 247
 248 /**
 249  * Stop Gatt client gracefully.  In turn it will call the
 250  * @c CATerminateBLEGattClient function.
 251  *
 252  * @return ::CA_STATUS_OK or Appropriate error code
 253  * @retval ::CA_STATUS_OK  Successful
 254  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 255  * @retval ::CA_STATUS_FAILED Operation failed
 256  */
 257 void CAStopLEGattClient();
 258
 259 /**
 260  * Unset all the callbacks and stop service discovery
 261  */
 262 void CATerminateLEGattClient();
 263
 264 /**
 265  * Read the data from characteristics and invoke notify callback.
 266  */
 267 void CACheckLEData();
 268
 269 /**
 270  * Set the value of characteristic and update the value to
 271  * GATTServer (unicast).
 272  *
 273  * @param[in] remoteAddress The address of the remote device
 274  * @param[in] data          The value of characteristic (byte array)
 275  * @param[in] dataLen       The length of value
 276  * @param[in] type          Type of the transfer(::CALETransferType_t)
 277  * @param[in] position      The unique index of each ble server. Used
 278  *                          for multicast feature.
 279  *
 280  * @return ::CA_STATUS_OK or Appropriate error code
 281  * @retval ::CA_STATUS_OK  Successful
 282  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 283  * @retval ::CA_STATUS_FAILED Operation failed
 284  */
 285 CAResult_t  CAUpdateCharacteristicsToGattServer(const char *remoteAddress,
 286                                                 const char  *data,
 287                                                 uint32_t dataLen,
 288                                                 CALETransferType_t type,
 289                                                 int32_t position);
 290
 291 /**
 292  * Set the value of characteristic and update the value to all
 293  * registered GATTServer (multicast).
 294  *
 295  * @param[in]  data    The value of characteristic (byte array)
 296  * @param[in]  dataLen The length of value
 297  *
 298  * @return ::CA_STATUS_OK or Appropriate error code
 299  * @retval ::CA_STATUS_OK  Successful
 300  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 301  * @retval ::CA_STATUS_FAILED Operation failed
 302  */
 303 CAResult_t CAUpdateCharacteristicsToAllGattServers(const char *data,
 304                                                    uint32_t dataLen);
 305
 306 /**
 307  * Store upper layer callback locally which will be used to send the
 308  * data to application.
 309  *
 310  * @param[in] callback Callback function to pass the data to CA layer.
 311  */
 312 void CASetLEReqRespClientCallback(CABLEDataReceivedCallback callback);
 313
 314 /**
 315  * Set the server thread pool handle which is required for spawning
 316  * new thread.
 317  *
 318  * @param[in] handle Thread pool handle which is given by above layer
 319  *                   for using thread creation task.
 320  *
 321  * @return ::CA_STATUS_OK or Appropriate error code
 322  * @retval ::CA_STATUS_OK  Successful
 323  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 324  * @retval ::CA_STATUS_FAILED Operation failed
 325  */
 326 void CASetLEServerThreadPoolHandle(ca_thread_pool_t handle);
 327
 328 /**
 329 * Set the client thread pool handle which is required for spawning new
 330 * thread.
 331 *
 332 * @param[in] handle Thread pool handle which is given by above layer
 333 *                   for using thread creation task.
 334 */
 335 void CASetLEClientThreadPoolHandle(ca_thread_pool_t handle);
 336
 337 /**
 338  * Unset the callback of adapter connection state change.
 339  *
 340  * @return ::CA_STATUS_OK or Appropriate error code.
 341  * @retval ::CA_STATUS_OK  Successful.
 342  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 343  * @retval ::CA_STATUS_FAILED Operation failed.
 344  */
 345 CAResult_t CAUnSetLEAdapterStateChangedCb();
 346
 347 /**
 348  * This will be used to notify errors in BLE adapter.
 349  *
 350  * @param[in] remoteAddress Remote endpoint Address
 351  * @param[in] data          Data received
 352  * @param[in] dataLength    Length of the data received
 353  * @param[in] result        error code as per CAResult_t
 354  */
 355 typedef void (*CABLEErrorHandleCallback)(const char *remoteAddress,
 356                                          const void *data,
 357                                          uint32_t dataLength,
 358                                          CAResult_t result);
 359 /**
 360  * Set the client error handler callback.
 361  *
 362  * @param[in] callback Callback function to update error to the
 363  *                     adapter.
 364  */
 365 void CASetBLEClientErrorHandleCallback(CABLEErrorHandleCallback callback);
 366
 367
 368 /**
 369  * Set the server error handler callback.
 370  *
 371  * @param[in] callback Callback function to update error to the
 372  *                     adapter.
 373  */
 374 void CASetBLEServerErrorHandleCallback(CABLEErrorHandleCallback callback);
 375
 376 #ifdef __cplusplus
 377 }
 378 #endif
 379
 380 #endif /* CA_LE_INTERFACE_H_ */