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