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  * Used to get the current state of the LE adapter.
 103  *
 104  * @return ::CA_STATUS_OK or Appropriate error code
 105  * @retval ::CA_STATUS_OK  Successful
 106  * @retval ::CA_ADAPTER_NOT_ENABLED  adapter not enabled
 107  * @retval ::CA_STATUS_FAILED Operation failed
 108  */
 109 CAResult_t CAGetLEAdapterState();
 110
 111 /**
 112  * Initialize the network monitor layer of the LE adapter.  Mutex
 113  * variables required to operate in this layer and other parameters
 114  * can be initialized in this function.
 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 CAResult_t CAInitializeLENetworkMonitor();
 122
 123 /**
 124  * Terminate the network monitor layer of the LE adapter. The
 125  * variables initialized in @c CAInitializeLENetworkMonitor() must be
 126  * cleared in this function.
 127  */
 128 void CATerminateLENetworkMonitor();
 129
 130 /**
 131  * Set the callback for the device state changes in the adapter.
 132  *
 133  * @param[in] callback Callback to notify the Device state change to
 134  *            the CA Layer
 135  *
 136  * @return ::CA_STATUS_OK or Appropriate error code
 137  * @retval ::CA_STATUS_OK  Successful
 138  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 139  * @retval ::CA_STATUS_FAILED Operation failed
 140  */
 141 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
 142
 143 /**
 144  * Initialize all the mutex variables required to operate the LE
 145  * network monitor layer.
 146  *
 147  * @return ::CA_STATUS_OK or Appropriate error code
 148  * @retval ::CA_STATUS_OK  Successful
 149  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 150  * @retval ::CA_STATUS_FAILED Operation failed
 151  */
 152 CAResult_t CAInitLENetworkMonitorMutexVariables();
 153
 154 /**
 155  * Used to terminate all the mutex variables required to operate the LE
 156  * network monitor layer.
 157  */
 158 void CATerminateLENetworkMonitorMutexVariables();
 159
 160 /**
 161  * Provides the MAC address of the local Bluetooth adapter.
 162  *
 163  * @param[out] local_address Pointer to the location where bd address
 164  *                           needs to be stored.
 165  *
 166  * @return ::CA_STATUS_OK or Appropriate error code
 167  * @retval ::CA_STATUS_OK  Successful
 168  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 169  * @retval ::CA_STATUS_FAILED Operation failed
 170  */
 171 CAResult_t CAGetLEAddress(char **local_address);
 172
 173 /**
 174  * Start Gatt Server thread for service creation and advertise BLE
 175  * service.
 176  *
 177  * @return ::CA_STATUS_OK or Appropriate error code
 178  * @retval ::CA_STATUS_OK  Successful
 179  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 180  * @retval ::CA_STATUS_FAILED Operation failed
 181  */
 182 CAResult_t CAStartLEGattServer();
 183
 184 /**
 185  * Stop BLE Gatt Service.
 186  *
 187  * @return ::CA_STATUS_OK or Appropriate error code
 188  * @retval ::CA_STATUS_OK  Successful
 189  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 190  * @retval ::CA_STATUS_FAILED Operation failed
 191  */
 192 CAResult_t CAStopLEGattServer();
 193
 194 /**
 195  * Stop Gatt Server thread and remove service registration, stop
 196  * advertising.
 197  */
 198 void CATerminateLEGattServer();
 199
 200 /**
 201  * Used to store upper layer callback locally which will be used to
 202  * send the data to application.
 203  *
 204  * @param[in] callback Callback function to pass the data to CA layer.
 205  */
 206 void CASetLEReqRespServerCallback(CABLEDataReceivedCallback callback);
 207
 208 /**
 209  * Update characteristics(Read/Write) value that we want to send to
 210  * particular client.
 211  *
 212  * @param[in] address  BD address of Gatt client
 213  * @param[in] value    Data that we want to send to client(unicast)
 214  * @param[in] valueLen Length of the data.
 215  *
 216  * @return ::CA_STATUS_OK or Appropriate error code
 217  * @retval ::CA_STATUS_OK  Successful
 218  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 219  * @retval ::CA_STATUS_FAILED Operation failed
 220  */
 221 CAResult_t CAUpdateCharacteristicsToGattClient(const char *address,
 222                                                const uint8_t *value,
 223                                                uint32_t valueLen);
 224
 225 /**
 226  * Update characteristics(Read/Write) value that we want to multicast
 227  * to all clients.
 228  *
 229  * @param[in] value    Data that we want to send to clients(multicast)
 230  * @param[in] valueLen Length of the data.
 231  *
 232  * @return ::CA_STATUS_OK or Appropriate error code
 233  * @retval ::CA_STATUS_OK  Successful
 234  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 235  * @retval ::CA_STATUS_FAILED Operation failed
 236  */
 237 CAResult_t CAUpdateCharacteristicsToAllGattClients(const uint8_t *value,
 238                                                    uint32_t valueLen);
 239
 240 /**
 241  * Start @c CAStartBleGattClientThread for initializing Gatt Client.
 242  *
 243  * @return ::CA_STATUS_OK or Appropriate error code
 244  * @retval ::CA_STATUS_OK  Successful
 245  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 246  * @retval ::CA_STATUS_FAILED Operation failed
 247  */
 248 CAResult_t CAStartLEGattClient();
 249
 250 /**
 251  * Stop Gatt client gracefully.  In turn it will call the
 252  * @c CATerminateBLEGattClient function.
 253  *
 254  * @return ::CA_STATUS_OK or Appropriate error code
 255  * @retval ::CA_STATUS_OK  Successful
 256  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 257  * @retval ::CA_STATUS_FAILED Operation failed
 258  */
 259 void CAStopLEGattClient();
 260
 261 /**
 262  * Unset all the callbacks and stop service discovery
 263  */
 264 void CATerminateLEGattClient();
 265
 266 /**
 267  * Read the data from characteristics and invoke notify callback.
 268  */
 269 void CACheckLEData();
 270
 271 /**
 272  * Set the value of characteristic and update the value to
 273  * GATTServer (unicast).
 274  *
 275  * @param[in] remoteAddress The address of the remote device
 276  * @param[in] data          The value of characteristic (byte array)
 277  * @param[in] dataLen       The length of value
 278  * @param[in] type          Type of the transfer(::CALETransferType_t)
 279  * @param[in] position      The unique index of each ble server. Used
 280  *                          for multicast feature.
 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  CAUpdateCharacteristicsToGattServer(const char *remoteAddress,
 288                                                 const uint8_t *data,
 289                                                 uint32_t dataLen,
 290                                                 CALETransferType_t type,
 291                                                 int32_t position);
 292
 293 /**
 294  * Set the value of characteristic and update the value to all
 295  * registered GATTServer (multicast).
 296  *
 297  * @param[in]  data    The value of characteristic (byte array)
 298  * @param[in]  dataLen The length of value
 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 CAUpdateCharacteristicsToAllGattServers(const uint8_t *data,
 306                                                    uint32_t dataLen);
 307
 308 /**
 309  * Store upper layer callback locally which will be used to send the
 310  * data to application.
 311  *
 312  * @param[in] callback Callback function to pass the data to CA layer.
 313  */
 314 void CASetLEReqRespClientCallback(CABLEDataReceivedCallback callback);
 315
 316 /**
 317  * Set the server thread pool handle which is required for spawning
 318  * new thread.
 319  *
 320  * @param[in] handle Thread pool handle which is given by above layer
 321  *                   for using thread creation task.
 322  *
 323  * @return ::CA_STATUS_OK or Appropriate error code
 324  * @retval ::CA_STATUS_OK  Successful
 325  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 326  * @retval ::CA_STATUS_FAILED Operation failed
 327  */
 328 void CASetLEServerThreadPoolHandle(ca_thread_pool_t handle);
 329
 330 /**
 331 * Set the client thread pool handle which is required for spawning new
 332 * thread.
 333 *
 334 * @param[in] handle Thread pool handle which is given by above layer
 335 *                   for using thread creation task.
 336 */
 337 void CASetLEClientThreadPoolHandle(ca_thread_pool_t handle);
 338
 339 /**
 340  * Unset the callback of adapter connection state change.
 341  *
 342  * @return ::CA_STATUS_OK or Appropriate error code.
 343  * @retval ::CA_STATUS_OK  Successful.
 344  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 345  * @retval ::CA_STATUS_FAILED Operation failed.
 346  */
 347 CAResult_t CAUnSetLEAdapterStateChangedCb();
 348
 349 /**
 350  * This will be used to notify errors in BLE adapter.
 351  *
 352  * @param[in] remoteAddress Remote endpoint Address
 353  * @param[in] data          Data received
 354  * @param[in] dataLength    Length of the data received
 355  * @param[in] result        error code as per CAResult_t
 356  */
 357 typedef void (*CABLEErrorHandleCallback)(const char *remoteAddress,
 358                                          const uint8_t *data,
 359                                          uint32_t dataLength,
 360                                          CAResult_t result);
 361 /**
 362  * Set the client error handler callback.
 363  *
 364  * @param[in] callback Callback function to update error to the
 365  *                     adapter.
 366  */
 367 void CASetBLEClientErrorHandleCallback(CABLEErrorHandleCallback callback);
 368
 369
 370 /**
 371  * Set the server error handler callback.
 372  *
 373  * @param[in] callback Callback function to update error to the
 374  *                     adapter.
 375  */
 376 void CASetBLEServerErrorHandleCallback(CABLEErrorHandleCallback callback);
 377
 378 #ifdef __cplusplus
 379 }
 380 #endif
 381
 382 #endif /* CA_LE_INTERFACE_H_ */