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