1 /******************************************************************
3 * Copyright 2014 Samsung Electronics All Rights Reserved.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 ******************************************************************/
22 * @file caleinterface.h
23 * @brief This file provides APIs for BLE modules
26 #ifndef _CA_LE_INTERFACE_H_
27 #define _CA_LE_INTERFACE_H_
32 #include "caleadapter.h"
41 * @brief Provide info about different mode of data transfer
42 * This enum is used to differentiate between unicast and multicast data transfer.
46 MULTICAST, /**< When this enum is selected, data will be updated to all OIC servers. */
47 UNICAST /**< When this enum is selected, data will be updated to desired OIC Server. */
52 * @brief Initialize the LE adapter layer. This will be invoked from the CA layer.
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
59 CAResult_t CAInitializeLEAdapter();
62 * @brief Used to get the current state of the LE adapter.
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
69 CAResult_t CAGetLEAdapterState();
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.
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
80 CAResult_t CAInitializeLENwkMonitor();
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.
87 void CATerminateLENwkMonitor();
90 * @brief This function is used to set the callback for the Device state changes in the adapter.
92 * @param callback [IN] Callback to notify the Device state change to the CA Layer
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
99 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
102 * @brief Used to initilaze all the mutex variables required to operate the LE network monitor
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
109 CAResult_t CAInitLENwkMonitorMutexVaraibles();
112 * @brief Used to terminate all the mutex variables required to operate the LE network monitor
116 void CATerminateLENwkMonitorMutexVaraibles();
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.
124 void CAGetLEAddress(char **local_address);
127 * @brief Used to start Gatt Server thread for service creation and advertise ble service.
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
134 CAResult_t CAStartBleGattServer();
137 * @brief Used to stop BLE Gatt Service.
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
144 CAResult_t CAStopBleGattServer();
147 * @brief Used to stop Gatt Server thread and remove service registration, stop advertising.
150 void CATerminateBleGattServer();
153 * @brief Used to store upper layer callback locally which will be used to send the data to
155 * @param callback [IN] Callback function to pass the data to CA layer.
158 void CASetBLEReqRespServerCallback(CABLEServerDataReceivedCallback callback);
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.
165 * @param charValue [IN] Data that we want to send to client(unicast)/clients(multicast)
166 * @param charValueLen [IN] Length of the data.
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
173 CAResult_t CAUpdateCharacteristicsInGattServer(const char *charValue, const uint32_t charValueLen);
176 * @brief Used to start CAStartBleGattClientThread for initializing Gatt Client
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
183 CAResult_t CAStartBLEGattClient();
186 * @brief Used to stop Gatt Client gracefully in turn it will call CATerminateBLEGattClient
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
193 void CAStopBLEGattClient();
196 * @brief Used to unset all the callbacks and stop service discovery
199 void CATerminateBLEGattClient();
202 * @brief Sets the value of characteristic and update the value to GATTServer(unicast).
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(#TRANSFER_TYPE)
208 * @param position [IN] The unique index of each ble server. Used for multicast feature.
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
215 CAResult_t CAUpdateCharacteristicsToGattServer(const char *remoteAddress, const char *data,
216 const int32_t dataLen, TRANSFER_TYPE type,
217 const int32_t position);
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
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
230 CAResult_t CAUpdateCharacteristicsToAllGattServers(const char *data, const int32_t dataLen);
233 * @brief Used to store upper layer callback locally which will be used to send the data to
235 * @param callback [IN] Callback function to pass the data to CA layer.
239 void CASetBLEReqRespClientCallback(CABLEClientDataReceivedCallback callback);
242 * @brief Used to Set the gThreadPool handle which is required for spawning new thread.
244 * @param handle [IN] Thread pool handle which is given by above layer for using thread
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
251 void CASetBleServerThreadPoolHandle(u_thread_pool_t handle);
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
259 void CASetBleClientThreadPoolHandle(u_thread_pool_t handle);
262 * @brief Used to unset the callback of adapter connection state change.
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
269 CAResult_t CAUnSetLEAdapterStateChangedCb();
274 #endif //_CA_LE_INTERFACE_H_