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 caleinterface.h
  23  * @brief This file provides APIs for BLE modules
  24  */
  25
  26 #ifndef _CA_LE_INTERFACE_H_
  27 #define _CA_LE_INTERFACE_H_
  28
  29 #include <stdbool.h>
  30
  31 #include "cacommon.h"
  32 #include "caleadapter.h"
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39 /**
  40  * @enum CALETransferType_t
  41  * @brief 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  * @brief  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 argumets
  57  * @retval #CA_STATUS_FAILED Operation failed
  58  */
  59 CAResult_t CAInitializeLEAdapter();
  60
  61 /**
  62  * @brief  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  * @brief  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 argumets
  78  * @retval #CA_STATUS_FAILED Operation failed
  79  */
  80 CAResult_t CAInitializeLENetworkMonitor();
  81
  82 /**
  83  * @brief  Used to terminate the network monitor layer of the LE adapter. The variables intialized
  84  *         in CAInitializeLEAdapterController() must be cleared in this function.
  85  * @return NONE
  86  */
  87 void CATerminateLENetworkMonitor();
  88
  89 /**
  90  * @brief  This function is used to set the callback for the Device state changes in the adapter.
  91  *
  92  * @param  callback  [IN] Callback to notify the Device state change to the CA Layer
  93  *
  94  * @return #CA_STATUS_OK or Appropriate error code
  95  * @retval #CA_STATUS_OK  Successful
  96  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
  97  * @retval #CA_STATUS_FAILED Operation failed
  98  */
  99 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
 100
 101 /**
 102  * @brief  Used to initilaze all the mutex variables required to operate the LE network monitor
 103  *         layer.
 104  * @return #CA_STATUS_OK or Appropriate error code
 105  * @retval #CA_STATUS_OK  Successful
 106  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 107  * @retval #CA_STATUS_FAILED Operation failed
 108  */
 109 CAResult_t CAInitLENetworkMonitorMutexVariables();
 110
 111 /**
 112  * @brief  Used to terminate all the mutex variables required to operate the LE network monitor
 113  *         layer.
 114  * @return NONE
 115  */
 116 void CATerminateLENetworkMonitorMutexVariables();
 117
 118 /**
 119  * @brief  Provides the BD address of the local adapter.
 120  * @param  local_address [IN] pointer to the location where bd address needs to be stored.
 121  *
 122  * @return NONE
 123  */
 124 void CAGetLEAddress(char **local_address);
 125
 126 /**
 127  * @brief  Used to start Gatt Server thread for service creation and advertise ble service.
 128  *
 129  * @return #CA_STATUS_OK or Appropriate error code
 130  * @retval #CA_STATUS_OK  Successful
 131  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 132  * @retval #CA_STATUS_FAILED Operation failed
 133  */
 134 CAResult_t CAStartBleGattServer();
 135
 136 /**
 137  * @brief  Used to stop BLE Gatt Service.
 138  *
 139  * @return #CA_STATUS_OK or Appropriate error code
 140  * @retval #CA_STATUS_OK  Successful
 141  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 142  * @retval #CA_STATUS_FAILED Operation failed
 143  */
 144 CAResult_t CAStopBleGattServer();
 145
 146 /**
 147  * @brief  Used to stop Gatt Server thread and remove service registration, stop advertising.
 148  * @return NONE
 149  */
 150 void CATerminateBleGattServer();
 151
 152 /**
 153  * @brief  Used to store upper layer callback locally which will be used to send the data to
 154  *         application
 155  * @param  callback [IN] Callback function to pass the data to CA layer.
 156  * @return NONE
 157  */
 158 void CASetBLEReqRespServerCallback(CABLEServerDataReceivedCallback callback);
 159
 160 /**
 161  * @brief  Used to update characteristics(Read/Write) value that we want to send to particular
 162  *         client. Both unicast and multicast will use the same api. In mulicast, we will be
 163  *         sending in loop to all clients.
 164  *
 165  * @param  charValue     [IN] Data that we want to send to client(unicast)/clients(multicast)
 166  * @param  charValueLen  [IN] Length of the data.
 167  *
 168  * @return #CA_STATUS_OK or Appropriate error code
 169  * @retval #CA_STATUS_OK  Successful
 170  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 171  * @retval #CA_STATUS_FAILED Operation failed
 172  */
 173 CAResult_t CAUpdateCharacteristicsInGattServer(const char *charValue, const uint32_t charValueLen);
 174
 175 /**
 176  * @brief  Used to start CAStartBleGattClientThread for initializing Gatt Client
 177  *
 178  * @return #CA_STATUS_OK or Appropriate error code
 179  * @retval #CA_STATUS_OK  Successful
 180  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 181  * @retval #CA_STATUS_FAILED Operation failed
 182  */
 183 CAResult_t CAStartBLEGattClient();
 184
 185 /**
 186  * @brief  Used to stop Gatt Client gracefully in turn it will call CATerminateBLEGattClient
 187  *         function.
 188  * @return #CA_STATUS_OK or Appropriate error code
 189  * @retval #CA_STATUS_OK  Successful
 190  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 191  * @retval #CA_STATUS_FAILED Operation failed
 192  */
 193 void CAStopBLEGattClient();
 194
 195 /**
 196  * @brief  Used to unset all the callbacks and stop service discovery
 197  * @return NONE
 198  */
 199 void CATerminateBLEGattClient();
 200
 201 /**
 202  * @brief  Sets the value of characteristic and update the value to GATTServer(unicast).
 203  *
 204  * @param  remoteAddress [IN] The address of the remote device
 205  * @param  data          [IN] The value of characteristic (byte array)
 206  * @param  dataLen       [IN] The length of value
 207  * @param  type          [IN] Type of the transfer(#CALETransferType_t)
 208  * @param  position      [IN] The unique index of each ble server. Used for multicast feature.
 209  *
 210  * @return #CA_STATUS_OK or Appropriate error code
 211  * @retval #CA_STATUS_OK  Successful
 212  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 213  * @retval #CA_STATUS_FAILED Operation failed
 214  */
 215 CAResult_t  CAUpdateCharacteristicsToGattServer(const char *remoteAddress, const char  *data,
 216                                                 const int32_t dataLen, CALETransferType_t type,
 217                                                 const int32_t position);
 218
 219 /**
 220  * @brief  Sets the value of characteristic and update the value to all registered
 221  *         GATTServer -> Multicast
 222  * @param  data     [IN] The value of characteristic (byte array)
 223  * @param  dataLen  [IN] The length of value
 224  *
 225  * @return #CA_STATUS_OK or Appropriate error code
 226  * @retval #CA_STATUS_OK  Successful
 227  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 228  * @retval #CA_STATUS_FAILED Operation failed
 229  */
 230 CAResult_t  CAUpdateCharacteristicsToAllGattServers(const char  *data, int32_t dataLen);
 231
 232 /**
 233  * @brief  Used to store upper layer callback locally which will be used to send the data to
 234  *         application
 235  * @param  callback  [IN] Callback function to pass the data to CA layer.
 236  *
 237  * @return  void
 238  */
 239 void CASetBLEReqRespClientCallback(CABLEClientDataReceivedCallback callback);
 240
 241 /**
 242  * @brief  Used to Set the gThreadPool handle which is required for spawning new thread.
 243  *
 244  * @param handle [IN] Thread pool handle which is given by above layer for using thread
 245  *                    creation task.
 246  * @return #CA_STATUS_OK or Appropriate error code
 247  * @retval #CA_STATUS_OK  Successful
 248  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 249  * @retval #CA_STATUS_FAILED Operation failed
 250  */
 251 void CASetBleServerThreadPoolHandle(u_thread_pool_t handle);
 252
 253 /**
 254 * @brief  Used to Set the gThreadPool handle which is required for spawning new thread.
 255 * @param handle [IN] Thread pool handle which is given by above layer for using thread creation
 256 *                    task.
 257 * @return NONE
 258 */
 259 void CASetBleClientThreadPoolHandle(u_thread_pool_t handle);
 260
 261 /**
 262  * @brief  Used to unset the callback of adapter connection state change.
 263  *
 264  * @return #CA_STATUS_OK or Appropriate error code
 265  * @retval #CA_STATUS_OK  Successful
 266  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 267  * @retval #CA_STATUS_FAILED Operation failed
 268  */
 269 CAResult_t CAUnSetLEAdapterStateChangedCb();
 270 #ifdef __cplusplus
 271 }
 272 #endif
 273
 274 #endif //_CA_LE_INTERFACE_H_
 275