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 #include "uarraylist.h"
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #endif
  40
  41 /**
  42  * Provide info about different mode of data transfer.
  43  *
  44  * This enum is used to differentiate between unicast and multicast
  45  * data transfer.
  46  */
  47 typedef enum
  48 {
  49     LE_MULTICAST,    /**< When this enum is selected, data will be updated to all OIC servers. */
  50     LE_UNICAST       /**< When this enum is selected, data will be updated to desired OIC Server. */
  51 } CALETransferType_t;
  52
  53 /**
  54  * Stores the information of the Data to be sent from the queues.
  55  *
  56  * This structure will be pushed to the sender/receiver queue for
  57  * processing.
  58  */
  59 typedef struct
  60 {
  61     /// Remote endpoint contains the information of remote device.
  62     CAEndpoint_t *remoteEndpoint;
  63
  64     /// Data to be transmitted over LE transport.
  65     uint8_t *data;
  66
  67     /// Length of the data being transmitted.
  68     uint32_t dataLen;
  69
  70     /// Sender information list
  71     u_arraylist_t * senderInfo;
  72 } CALEData_t;
  73
  74 /**
  75  * The MTU supported for BLE adapter
  76  */
  77 #ifdef __APPLE__
  78 #define CA_DEFAULT_BLE_MTU_SIZE  152
  79 #else
  80 #define CA_DEFAULT_BLE_MTU_SIZE  20
  81 #endif
  82 /**
  83  * The MTU supported for BLE spec
  84  */
  85 #define CA_SUPPORTED_BLE_MTU_SIZE  517
  86
  87 /**
  88  * The Header of the MTU supported for BLE spec
  89  */
  90 #define CA_BLE_MTU_HEADER_SIZE  5
  91
  92 /**
  93  * This will be used to notify device status changes to the LE adapter layer.
  94  * @param[in]  adapter_state State of the adapter.
  95  */
  96 typedef void (*CALEDeviceStateChangedCallback)(CAAdapterState_t adapter_state);
  97
  98 /**
  99  * This will be used to notify device connection state changes to the LE adapter layer.
 100  * @param[in]   adapter        Transport type information.
 101  * @param[in]   remoteAddress  Endpoint object from which the connection status is changed.
 102  * @param[in]   connected      State of connection.
 103  */
 104 typedef void (*CALEConnectionStateChangedCallback)(CATransportAdapter_t adapter,
 105                                                    const char *remoteAddress, bool connected);
 106
 107 /**
 108  * Notify the adapter layer that a packet was received from the GATT
 109  * peer.
 110  *
 111  * @param[in]  remoteAddress  Remote endpoint Address.
 112  * @param[in]  data           Data received.
 113  * @param[in]  dataLength     Length of the data received.
 114  * @param[in]  sentLength     Length of the data sent.
 115  *
 116  * @return ::CA_STATUS_OK or Appropriate error code.
 117  * @retval ::CA_STATUS_OK  Successful.
 118  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 119  * @retval ::CA_STATUS_FAILED Operation failed.
 120  */
 121 typedef CAResult_t (*CABLEDataReceivedCallback)(const char *remoteAddress,
 122                                                 const uint8_t *data,
 123                                                 uint32_t dataLength,
 124                                                 uint32_t *sentLength);
 125
 126 /**
 127  * Initialize the LE adapter layer. This will be invoked from the CA
 128  * layer.
 129  *
 130  * @param[in] threadPool Thread pool handle
 131  * @return ::CA_STATUS_OK or Appropriate error code
 132  * @retval ::CA_STATUS_OK  Successful
 133  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 134  * @retval ::CA_STATUS_FAILED Operation failed
 135  */
 136 CAResult_t CAInitializeLEAdapter();
 137
 138 /**
 139  * Start the LE adapter layer.
 140  *
 141  * This function will be invoked from the CA layer when the LE
 142  * "network" is selected via @c CASelectNetwork().  It gives an
 143  * opportunity for LE adapter implementations to perform operations
 144  * before starting a GATT client or server.  Most LE adapter
 145  * implementations will simply implement this function as no-op.
 146  *
 147  * @return ::CA_STATUS_OK or Appropriate error code
 148  */
 149 CAResult_t CAStartLEAdapter();
 150
 151 /**
 152  * Stop the LE adapter layer.
 153  *
 154  * This function will be invoked from the CA layer when the LE
 155  * "network" is unselected via @c CAUnselectNetwork().  It gives an
 156  * opportunity for LE adapter implementations to perform operations
 157  * after stopping a GATT client or server.  Most LE adapter
 158  * implementations will simply implement this function as no-op.
 159  *
 160  * @return ::CA_STATUS_OK or Appropriate error code
 161  */
 162 CAResult_t CAStopLEAdapter();
 163
 164 /**
 165  * Used to get the current state of the LE adapter.
 166  *
 167  * @return ::CA_STATUS_OK or Appropriate error code
 168  * @retval ::CA_STATUS_OK  Successful
 169  * @retval ::CA_ADAPTER_NOT_ENABLED  adapter not enabled
 170  * @retval ::CA_STATUS_FAILED Operation failed
 171  */
 172 CAResult_t CAGetLEAdapterState();
 173
 174 /**
 175  * Initialize the network monitor layer of the LE adapter.  Mutex
 176  * variables required to operate in this layer and other parameters
 177  * can be initialized in this function.
 178  *
 179  * @return ::CA_STATUS_OK or Appropriate error code
 180  * @retval ::CA_STATUS_OK  Successful
 181  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 182  * @retval ::CA_STATUS_FAILED Operation failed
 183  */
 184 CAResult_t CAInitializeLENetworkMonitor();
 185
 186 /**
 187  * Terminate the network monitor layer of the LE adapter. The
 188  * variables initialized in @c CAInitializeLENetworkMonitor() must be
 189  * cleared in this function.
 190  */
 191 void CATerminateLENetworkMonitor();
 192
 193 /**
 194  * Set the callback for the device state changes in the adapter.
 195  *
 196  * @param[in] callback Callback to notify the Device state change to
 197  *            the CA Layer
 198  *
 199  * @return ::CA_STATUS_OK or Appropriate error code
 200  * @retval ::CA_STATUS_OK  Successful
 201  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 202  * @retval ::CA_STATUS_FAILED Operation failed
 203  */
 204 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
 205
 206 /**
 207  * Set the callback for the device connection state changes.
 208  *
 209  * @param[in] callback Callback to notify the Device connection state change to
 210  *            the CA Layer
 211  *
 212  * @return ::CA_STATUS_OK or Appropriate error code
 213  * @retval ::CA_STATUS_OK  Successful
 214  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 215  * @retval ::CA_STATUS_FAILED Operation failed
 216  */
 217 CAResult_t CASetLENWConnectionStateChangedCb(CALEConnectionStateChangedCallback callback);
 218
 219 /**
 220  * Provides the MAC address of the local Bluetooth adapter.
 221  *
 222  * @param[out] local_address Pointer to the location where bd address
 223  *                           needs to be stored.
 224  *
 225  * @return ::CA_STATUS_OK or Appropriate error code
 226  * @retval ::CA_STATUS_OK  Successful
 227  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 228  * @retval ::CA_STATUS_FAILED Operation failed
 229  */
 230 CAResult_t CAGetLEAddress(char **local_address);
 231
 232 /**
 233  * Start Gatt Server thread for service creation and advertise BLE
 234  * service.
 235  *
 236  * @return ::CA_STATUS_OK or Appropriate error code
 237  * @retval ::CA_STATUS_OK  Successful
 238  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 239  * @retval ::CA_STATUS_FAILED Operation failed
 240  */
 241 CAResult_t CAStartLEGattServer();
 242
 243 /**
 244  * Stop BLE Gatt Service.
 245  *
 246  * @return ::CA_STATUS_OK or Appropriate error code
 247  * @retval ::CA_STATUS_OK  Successful
 248  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 249  * @retval ::CA_STATUS_FAILED Operation failed
 250  */
 251 CAResult_t CAStopLEGattServer();
 252
 253 /**
 254  * initialize gatt server
 255  *
 256  * @return ::CA_STATUS_OK or Appropriate error code
 257  * @retval ::CA_STATUS_OK  Successful
 258  * @retval ::CA_STATUS_FAILED Operation failed
 259  */
 260 CAResult_t CAInitializeLEGattServer();
 261
 262 /**
 263  * Stop Gatt Server thread and remove service registration, stop
 264  * advertising.
 265  */
 266 void CATerminateLEGattServer();
 267
 268 /**
 269  * Used to store upper layer callback locally which will be used to
 270  * send the data to application.
 271  *
 272  * @param[in] callback Callback function to pass the data to CA layer.
 273  */
 274 void CASetLEReqRespServerCallback(CABLEDataReceivedCallback callback);
 275
 276 /**
 277  * Update characteristics(Read/Write) value that we want to send to
 278  * particular client.
 279  *
 280  * @param[in] address  BD address of Gatt client
 281  * @param[in] value    Data that we want to send to client(unicast)
 282  * @param[in] valueLen Length of the data.
 283  *
 284  * @return ::CA_STATUS_OK or Appropriate error code
 285  * @retval ::CA_STATUS_OK  Successful
 286  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 287  * @retval ::CA_STATUS_FAILED Operation failed
 288  */
 289 CAResult_t CAUpdateCharacteristicsToGattClient(const char *address,
 290                                                const uint8_t *value,
 291                                                uint32_t valueLen);
 292
 293 /**
 294  * Update characteristics(Read/Write) value that we want to multicast
 295  * to all clients.
 296  *
 297  * @param[in] value    Data that we want to send to clients(multicast)
 298  * @param[in] valueLen Length of the data.
 299  *
 300  * @return ::CA_STATUS_OK or Appropriate error code
 301  * @retval ::CA_STATUS_OK  Successful
 302  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 303  * @retval ::CA_STATUS_FAILED Operation failed
 304  */
 305 CAResult_t CAUpdateCharacteristicsToAllGattClients(const uint8_t *value,
 306                                                    uint32_t valueLen);
 307
 308 /**
 309  * Start @c CAStartBleGattClientThread for initializing Gatt Client.
 310  *
 311  * @return ::CA_STATUS_OK or Appropriate error code
 312  * @retval ::CA_STATUS_OK  Successful
 313  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 314  * @retval ::CA_STATUS_FAILED Operation failed
 315  */
 316 CAResult_t CAStartLEGattClient();
 317
 318 /**
 319  * Stop Gatt client gracefully.  In turn it will call the
 320  * @c CATerminateBLEGattClient function.
 321  *
 322  * @return ::CA_STATUS_OK or Appropriate error code
 323  * @retval ::CA_STATUS_OK  Successful
 324  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 325  * @retval ::CA_STATUS_FAILED Operation failed
 326  */
 327 void CAStopLEGattClient();
 328
 329 /**
 330  * initialize Client
 331  *
 332  * @return ::CA_STATUS_OK or Appropriate error code
 333  * @retval ::CA_STATUS_OK  Successful
 334  * @retval ::CA_STATUS_FAILED Operation failed
 335  */
 336 CAResult_t CAInitializeLEGattClient();
 337
 338 /**
 339  * Unset all the callbacks and stop service discovery
 340  */
 341 void CATerminateLEGattClient();
 342
 343 /**
 344  * Read the data from characteristics and invoke notify callback.
 345  */
 346 void CACheckLEData();
 347
 348 /**
 349  * Set the value of characteristic and update the value to
 350  * GATTServer (unicast).
 351  *
 352  * @param[in] remoteAddress The address of the remote device
 353  * @param[in] data          The value of characteristic (byte array)
 354  * @param[in] dataLen       The length of value
 355  * @param[in] type          Type of the transfer(::CALETransferType_t)
 356  * @param[in] position      The unique index of each ble server. Used
 357  *                          for multicast feature.
 358  *
 359  * @return ::CA_STATUS_OK or Appropriate error code
 360  * @retval ::CA_STATUS_OK  Successful
 361  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 362  * @retval ::CA_STATUS_FAILED Operation failed
 363  */
 364 CAResult_t  CAUpdateCharacteristicsToGattServer(const char *remoteAddress,
 365                                                 const uint8_t *data,
 366                                                 uint32_t dataLen,
 367                                                 CALETransferType_t type,
 368                                                 int32_t position);
 369
 370 /**
 371  * Set the value of characteristic and update the value to all
 372  * registered GATTServer (multicast).
 373  *
 374  * @param[in]  data    The value of characteristic (byte array)
 375  * @param[in]  dataLen The length of value
 376  *
 377  * @return ::CA_STATUS_OK or Appropriate error code
 378  * @retval ::CA_STATUS_OK  Successful
 379  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 380  * @retval ::CA_STATUS_FAILED Operation failed
 381  */
 382 CAResult_t CAUpdateCharacteristicsToAllGattServers(const uint8_t *data,
 383                                                    uint32_t dataLen);
 384
 385 /**
 386  * Store upper layer callback locally which will be used to send the
 387  * data to application.
 388  *
 389  * @param[in] callback Callback function to pass the data to CA layer.
 390  */
 391 void CASetLEReqRespClientCallback(CABLEDataReceivedCallback callback);
 392
 393 /**
 394  * Set the server thread pool handle which is required for spawning
 395  * new thread.
 396  *
 397  * @param[in] handle Thread pool handle which is given by above layer
 398  *                   for using thread creation task.
 399  *
 400  * @return ::CA_STATUS_OK or Appropriate error code
 401  * @retval ::CA_STATUS_OK  Successful
 402  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 403  * @retval ::CA_STATUS_FAILED Operation failed
 404  */
 405 void CASetLEServerThreadPoolHandle(ca_thread_pool_t handle);
 406
 407 /**
 408 * Set the client thread pool handle which is required for spawning new
 409 * thread.
 410 *
 411 * @param[in] handle Thread pool handle which is given by above layer
 412 *                   for using thread creation task.
 413 */
 414 void CASetLEClientThreadPoolHandle(ca_thread_pool_t handle);
 415
 416 /**
 417  * Unset the callback of adapter state change.
 418  *
 419  * @return ::CA_STATUS_OK or Appropriate error code.
 420  * @retval ::CA_STATUS_OK  Successful.
 421  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 422  * @retval ::CA_STATUS_FAILED Operation failed.
 423  */
 424 CAResult_t CAUnSetLEAdapterStateChangedCb();
 425
 426 /**
 427  * Unset the callback of adapter connection state change.
 428  *
 429  * @return ::CA_STATUS_OK or Appropriate error code.
 430  * @retval ::CA_STATUS_OK  Successful.
 431  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 432  * @retval ::CA_STATUS_FAILED Operation failed.
 433  */
 434 CAResult_t CAUnSetLENWConnectionStateChangedCb();
 435
 436 /**
 437  * This will be used to notify errors in BLE adapter.
 438  *
 439  * @param[in] remoteAddress Remote endpoint Address
 440  * @param[in] data          Data received
 441  * @param[in] dataLength    Length of the data received
 442  * @param[in] result        error code as per CAResult_t
 443  */
 444 typedef void (*CABLEErrorHandleCallback)(const char *remoteAddress,
 445                                          const uint8_t *data,
 446                                          uint32_t dataLength,
 447                                          CAResult_t result);
 448 /**
 449  * Set the client error handler callback.
 450  *
 451  * @param[in] callback Callback function to update error to the
 452  *                     adapter.
 453  */
 454 void CASetBLEClientErrorHandleCallback(CABLEErrorHandleCallback callback);
 455
 456
 457 /**
 458  * Set the server error handler callback.
 459  *
 460  * @param[in] callback Callback function to update error to the
 461  *                     adapter.
 462  */
 463 void CASetBLEServerErrorHandleCallback(CABLEErrorHandleCallback callback);
 464
 465 /**
 466  * This is the callback which will be called whenever there is change in gatt connection
 467  * with Client(Connected/Disconnected).
 468  *
 469  * @param[in]  connected      State of connection.
 470  * @param[in]  remoteAddress  Mac address of the remote device in which we made connection.
 471  */
 472 void CALEGattServerConnectionStateChanged(bool connected, const char *remoteAddress);
 473
 474 /**
 475  * This is the callback which will be called whenever there is change in gatt connection
 476  * with server(Connected/Disconnected)
 477  *
 478  * @param[in]  connected     State of connection
 479  * @param[in]  remoteAddress Mac address of the remote device in which we made connection.
 480  */
 481 void CALEGattConnectionStateChanged(bool connected, const char *remoteAddress);
 482
 483 #ifdef __cplusplus
 484 }
 485 #endif
 486
 487 #endif /* CA_LE_INTERFACE_H_ */