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