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 "caleadapter.h"
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #endif
  39
  40 /**
  41  * @enum CALETransferType_t
  42  * @brief Provide info about different mode of data transfer
  43  *        This enum is used to differentiate between unicast and multicast data transfer.
  44  */
  45 typedef enum
  46 {
  47     LE_MULTICAST,    /**< When this enum is selected, data will be updated to all OIC servers. */
  48     LE_UNICAST       /**< When this enum is selected, data will be updated to desired OIC Server. */
  49 } CALETransferType_t;
  50
  51
  52 /**
  53  * @brief  Initialize the LE adapter layer. This will be invoked from the CA layer.
  54  *
  55  * @return #CA_STATUS_OK or Appropriate error code
  56  * @retval #CA_STATUS_OK  Successful
  57  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
  58  * @retval #CA_STATUS_FAILED Operation failed
  59  */
  60 CAResult_t CAInitializeLEAdapter();
  61
  62 /**
  63  * @brief  Used to get the current state of the LE adapter.
  64  *
  65  * @return #CA_STATUS_OK or Appropriate error code
  66  * @retval #CA_STATUS_OK  Successful
  67  * @retval #CA_ADAPTER_NOT_ENABLED  adapter not enabled
  68  * @retval #CA_STATUS_FAILED Operation failed
  69  */
  70 CAResult_t CAGetLEAdapterState();
  71
  72 /**
  73  * @brief  Used to initialize the network monitor layer of the LE adapter. Mutex variables required
  74  *         to operate in this layer and other paramters can be initialized in this function.
  75  *
  76  * @return #CA_STATUS_OK or Appropriate error code
  77  * @retval #CA_STATUS_OK  Successful
  78  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
  79  * @retval #CA_STATUS_FAILED Operation failed
  80  */
  81 CAResult_t CAInitializeLENetworkMonitor();
  82
  83 /**
  84  * @brief  Used to terminate the network monitor layer of the LE adapter. The variables intialized
  85  *         in CAInitializeLEAdapterController() must be cleared in this function.
  86  * @return NONE
  87  */
  88 void CATerminateLENetworkMonitor();
  89
  90 /**
  91  * @brief  This function is used to set the callback for the Device state changes in the adapter.
  92  *
  93  * @param  callback  [IN] Callback to notify the Device state change to the CA Layer
  94  *
  95  * @return #CA_STATUS_OK or Appropriate error code
  96  * @retval #CA_STATUS_OK  Successful
  97  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
  98  * @retval #CA_STATUS_FAILED Operation failed
  99  */
 100 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
 101
 102 /**
 103  * @brief  Used to initilaze all the mutex variables required to operate the LE network monitor
 104  *         layer.
 105  * @return #CA_STATUS_OK or Appropriate error code
 106  * @retval #CA_STATUS_OK  Successful
 107  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 108  * @retval #CA_STATUS_FAILED Operation failed
 109  */
 110 CAResult_t CAInitLENetworkMonitorMutexVariables();
 111
 112 /**
 113  * @brief  Used to terminate all the mutex variables required to operate the LE network monitor
 114  *         layer.
 115  * @return NONE
 116  */
 117 void CATerminateLENetworkMonitorMutexVariables();
 118
 119 /**
 120  * @brief  Provides the BD address of the local adapter.
 121  * @param  local_address [OUT] pointer to the location where bd address needs to be stored.
 122  *
 123  * @return #CA_STATUS_OK or Appropriate error code
 124  * @retval #CA_STATUS_OK  Successful
 125  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 126  * @retval #CA_STATUS_FAILED Operation failed
 127  */
 128 CAResult_t CAGetLEAddress(char **local_address);
 129
 130 /**
 131  * @brief  Used to start Gatt Server thread for service creation and advertise ble service.
 132  *
 133  * @return #CA_STATUS_OK or Appropriate error code
 134  * @retval #CA_STATUS_OK  Successful
 135  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 136  * @retval #CA_STATUS_FAILED Operation failed
 137  */
 138 CAResult_t CAStartLEGattServer();
 139
 140 /**
 141  * @brief  Used to stop BLE Gatt Service.
 142  *
 143  * @return #CA_STATUS_OK or Appropriate error code
 144  * @retval #CA_STATUS_OK  Successful
 145  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 146  * @retval #CA_STATUS_FAILED Operation failed
 147  */
 148 CAResult_t CAStopLEGattServer();
 149
 150 /**
 151  * @brief  Used to stop Gatt Server thread and remove service registration, stop advertising.
 152  * @return NONE
 153  */
 154 void CATerminateLEGattServer();
 155
 156 /**
 157  * @brief  Used to store upper layer callback locally which will be used to send the data to
 158  *         application
 159  * @param  callback [IN] Callback function to pass the data to CA layer.
 160  * @return NONE
 161  */
 162 void CASetLEReqRespServerCallback(CABLEServerDataReceivedCallback callback);
 163
 164 /**
 165  * @brief  Used to update characteristics(Read/Write) value that we want to send to particular
 166  *         client.
 167  *
 168  * @param  address     [IN] BD address of Gatt client
 169  * @param  charValue     [IN] Data that we want to send to client(unicast)
 170  * @param  charValueLen  [IN] Length of the data.
 171  *
 172  * @return #CA_STATUS_OK or Appropriate error code
 173  * @retval #CA_STATUS_OK  Successful
 174  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 175  * @retval #CA_STATUS_FAILED Operation failed
 176  */
 177 CAResult_t CAUpdateCharacteristicsToGattClient(const char* address, const char *charValue,
 178                                                const uint32_t charValueLen);
 179
 180 /**
 181  * @brief  Used to update characteristics(Read/Write) value that we want to multicast to all clients
 182  *
 183  * @param  charValue     [IN] Data that we want to send to clients(multicast)
 184  * @param  charValueLen  [IN] Length of the data.
 185  *
 186  * @return #CA_STATUS_OK or Appropriate error code
 187  * @retval #CA_STATUS_OK  Successful
 188  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 189  * @retval #CA_STATUS_FAILED Operation failed
 190  */
 191 CAResult_t CAUpdateCharacteristicsToAllGattClients(const char *charValue,
 192                                                    uint32_t charValueLen);
 193
 194 /**
 195  * @brief  Used to start CAStartBleGattClientThread for initializing Gatt Client
 196  *
 197  * @return #CA_STATUS_OK or Appropriate error code
 198  * @retval #CA_STATUS_OK  Successful
 199  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 200  * @retval #CA_STATUS_FAILED Operation failed
 201  */
 202 CAResult_t CAStartLEGattClient();
 203
 204 /**
 205  * @brief  Used to stop Gatt Client gracefully in turn it will call CATerminateBLEGattClient
 206  *         function.
 207  * @return #CA_STATUS_OK or Appropriate error code
 208  * @retval #CA_STATUS_OK  Successful
 209  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 210  * @retval #CA_STATUS_FAILED Operation failed
 211  */
 212 void CAStopLEGattClient();
 213
 214 /**
 215  * @brief  Used to unset all the callbacks and stop service discovery
 216  * @return NONE
 217  */
 218 void CATerminateLEGattClient();
 219
 220 /**
 221  * @brief API to read the data from characteristics and invoke notifyCallback.
 222  * @return - NONE
 223  */
 224 void CACheckLEData();
 225
 226 /**
 227  * @brief  Sets the value of characteristic and update the value to GATTServer(unicast).
 228  *
 229  * @param  remoteAddress [IN] The address of the remote device
 230  * @param  data          [IN] The value of characteristic (byte array)
 231  * @param  dataLen       [IN] The length of value
 232  * @param  type          [IN] Type of the transfer(#CALETransferType_t)
 233  * @param  position      [IN] The unique index of each ble server. Used for multicast feature.
 234  *
 235  * @return #CA_STATUS_OK or Appropriate error code
 236  * @retval #CA_STATUS_OK  Successful
 237  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 238  * @retval #CA_STATUS_FAILED Operation failed
 239  */
 240 CAResult_t  CAUpdateCharacteristicsToGattServer(const char *remoteAddress, const char  *data,
 241                                                 const uint32_t dataLen, CALETransferType_t type,
 242                                                 const int32_t position);
 243
 244 /**
 245  * @brief  Sets the value of characteristic and update the value to all registered
 246  *         GATTServer -> Multicast
 247  * @param  data     [IN] The value of characteristic (byte array)
 248  * @param  dataLen  [IN] The length of value
 249  *
 250  * @return #CA_STATUS_OK or Appropriate error code
 251  * @retval #CA_STATUS_OK  Successful
 252  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 253  * @retval #CA_STATUS_FAILED Operation failed
 254  */
 255 CAResult_t  CAUpdateCharacteristicsToAllGattServers(const char  *data, uint32_t dataLen);
 256
 257 /**
 258  * @brief  Used to store upper layer callback locally which will be used to send the data to
 259  *         application
 260  * @param  callback  [IN] Callback function to pass the data to CA layer.
 261  *
 262  * @return  void
 263  */
 264 void CASetLEReqRespClientCallback(CABLEClientDataReceivedCallback callback);
 265
 266 /**
 267  * @brief  Used to Set the gThreadPool handle which is required for spawning new thread.
 268  *
 269  * @param handle [IN] Thread pool handle which is given by above layer for using thread
 270  *                    creation task.
 271  * @return #CA_STATUS_OK or Appropriate error code
 272  * @retval #CA_STATUS_OK  Successful
 273  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 274  * @retval #CA_STATUS_FAILED Operation failed
 275  */
 276 void CASetLEServerThreadPoolHandle(ca_thread_pool_t handle);
 277
 278 /**
 279 * @brief  Used to Set the gThreadPool handle which is required for spawning new thread.
 280 * @param handle [IN] Thread pool handle which is given by above layer for using thread creation
 281 *                    task.
 282 * @return NONE
 283 */
 284 void CASetLEClientThreadPoolHandle(ca_thread_pool_t handle);
 285
 286 /**
 287  * @brief  Used to unset the callback of adapter connection state change.
 288  *
 289  * @return #CA_STATUS_OK or Appropriate error code
 290  * @retval #CA_STATUS_OK  Successful
 291  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 292  * @retval #CA_STATUS_FAILED Operation failed
 293  */
 294 CAResult_t CAUnSetLEAdapterStateChangedCb();
 295
 296 /**
 297  * @brief This will be used to notify errors in BLE adapter
 298  * @param  remoteAddress    [IN] Remote endpoint Address
 299  * @param  serviceUUID      [IN] Service UUID
 300  * @param  data             [IN] Data received
 301  * @param  dataLength       [IN] Length of the data received
 302  * @param  result           [IN] error code as per CAResult_t
 303  * @return NONE
 304  */
 305 typedef void (*CABLEErrorHandleCallback)(const char *remoteAddress, const void *data,
 306                                          uint32_t dataLength, CAResult_t result);
 307 /**
 308  * @brief  sets the error handle callback
 309  * @param  callback [IN] Callback function to update error to the adapter
 310  * @return NONE
 311  */
 312 void CASetBLEClientErrorHandleCallback(CABLEErrorHandleCallback callback);
 313
 314
 315 /**
 316  * @brief  sets the error handle callback
 317  * @param  callback [IN] Callback function to update error to the adapter
 318  * @return NONE
 319  */
 320 void CASetBLEServerErrorHandleCallback(CABLEErrorHandleCallback callback);
 321
 322 #ifdef __cplusplus
 323 }
 324 #endif
 325
 326 #endif /* CA_LE_INTERFACE_H_ */
 327