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