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
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39 /**
  40  * @ENUM TRANSFER_TYPE
  41  * @brief Provide info about different mode of data transfer
  42  *
  43  * This enum is used to differentiate between unicast and multicast data transfer.
  44  */
  45 typedef enum
  46 {
  47     MULTICAST,    /**< When this enum is selected, data will be updated to all OIC servers. */
  48     UNICAST    /**< When this enum is selected, data will be updated to desired OIC Server. */
  49 } TRANSFER_TYPE;
  50
  51 /**
  52 * @fn  CAStartBleGattServer
  53 * @brief  Used to start Gatt Server thread for service creation and advertise ble service.
  54 *
  55 * @return  0 on success otherwise a positive error value.
  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 CAStartBleGattServer();
  61
  62 /**
  63 * @fn  CAStopBleGattServer
  64 * @brief  Used to terminate BLE Gatt Service.
  65 *
  66 * @return  0 on success otherwise a positive error value.
  67 * @retval  CA_STATUS_OK  Successful
  68 * @retval  CA_STATUS_INVALID_PARAM  Invalid input argumets
  69 * @retval  CA_STATUS_FAILED Operation failed
  70 */
  71 CAResult_t CAStopBleGattServer();
  72
  73 /**
  74 * @fn  CASetBLEReqRespServerCallback
  75 * @brief  used to store upper layer callback locally which will be used to send the data
  76 * to application
  77 * @param[in]  CANetworkPacketReceivedCallback  -  upper layer callback function
  78 * to pass the data to CA layer.
  79 * @return  void
  80 */
  81 void CASetBLEReqRespServerCallback(CABLEServerDataReceivedCallback callback);
  82
  83 /**
  84 * @fn  CAUpdateCharacteristicsInGattServer
  85 * @brief  Used to update characteristics(Read/Write) value that we want to send to particular client.
  86 *              Both unicast and multicast will use the same api. In mulicast, we will be sending in loop to all clients.
  87 *
  88 * @param[in]  charValue  - data that we want to send to client(unicast)/clients(multicast)
  89 * @param[in]  charValueLen  - length of the data.
  90 *
  91 * @return  0 on success otherwise a positive error value.
  92 * @retval  CA_STATUS_OK  Successful
  93 * @retval  CA_STATUS_INVALID_PARAM  Invalid input argumets
  94 * @retval  CA_STATUS_FAILED Operation failed
  95 */
  96 CAResult_t CAUpdateCharacteristicsInGattServer(const char *charValue, const uint32_t charValueLen);
  97
  98 /**
  99 * @fn  CAStartBLEGattClient
 100 * @brief  Used to start CAStartBleGattClientThread for initializing Gatt Client
 101 *
 102 * @return  0 on success otherwise a positive error value.
 103 * @retval  CA_STATUS_OK  Successful
 104 * @retval  CA_STATUS_INVALID_PARAM  Invalid input argumets
 105 * @retval  CA_STATUS_FAILED Operation failed
 106 */
 107 CAResult_t CAStartBLEGattClient();
 108
 109 /**
 110 * @fn  CAStopBLEGattClient
 111 * @brief  Used to stop Gatt Client gracefully in turn it will call CATerminateBLEGattClient function.
 112 *
 113 * @return  0 on success otherwise a positive error value.
 114 * @retval  CA_STATUS_OK  Successful
 115 * @retval  CA_STATUS_INVALID_PARAM  Invalid input argumets
 116 * @retval  CA_STATUS_FAILED Operation failed
 117 */
 118 void CAStopBLEGattClient();
 119
 120 /**
 121 * @fn  CATerminateBLEGattClient
 122 * @brief  Used to unset all the callbacks and stop service discovery
 123 *
 124 * @return  void
 125 */
 126 void CATerminateBLEGattClient();
 127
 128 /**
 129 * @fn  CAUpdateCharacteristicsToGattServer
 130 * @brief  Sets the value of characteristic and update the value to GATTServer(unicast).
 131 *
 132 * @param[in]  remoteAddress  The address of the remote device
 133 * @param[in]  data  The value of characteristic (byte array)
 134 * @param[in]  dataLen  The length of value
 135 * @param[in]  TRANSFER_TYPE (UNICAST/MULTICAST)
 136 * @param[in]  position  The unique index of each ble server. Used for multicast feature.
 137 *
 138 * @return  0 on success otherwise a positive error value.
 139 * @retval  CA_STATUS_OK  Successful
 140 * @retval  CA_STATUS_INVALID_PARAM  Invalid input argumets
 141 * @retval  CA_STATUS_FAILED Operation failed
 142 */
 143 CAResult_t  CAUpdateCharacteristicsToGattServer(const char *remoteAddress, const char  *data,
 144         const int32_t dataLen, TRANSFER_TYPE type, const int32_t position);
 145
 146 /**
 147  * @fn  CAUpdateCharacteristicsToAllGattServers
 148  * @brief  Sets the value of characteristic and update the value to All registered GATTServer -> Multicast
 149  *
 150  * @param[in]  data  The value of characteristic (byte array)
 151  * @param[in]  dataLen  The length of value
 152  *
 153  * @return  0 on success otherwise a positive error value.
 154  * @retval  CA_STATUS_OK  Successful
 155  * @retval  CA_STATUS_INVALID_PARAM  Invalid input argumets
 156  * @retval  CA_STATUS_FAILED Operation failed
 157  */
 158 CAResult_t  CAUpdateCharacteristicsToAllGattServers(const char  *data, const int32_t dataLen);
 159
 160 /**
 161  * @fn  CASetBLEReqRespClientCallback
 162  * @brief  used to store upper layer callback locally which will be used to send the data to application
 163  *
 164  * @param[in]  CANetworkPacketReceivedCallback  -  upper layer callback function to pass the data to CA layer.
 165  *
 166  * @return  void
 167  */
 168 void CASetBLEReqRespClientCallback(CABLEClientDataReceivedCallback callback);
 169
 170 #ifdef __cplusplus
 171 }
 172 #endif
 173
 174 #endif //_CA_LE_INTERFACE_H_