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 ******************************************************************/
24 * This file provides APIs for BLE modules.
27 #ifndef CA_LE_INTERFACE_H_
28 #define CA_LE_INTERFACE_H_
33 #include "cathreadpool.h"
41 * Provide info about different mode of data transfer.
43 * This enum is used to differentiate between unicast and multicast
48 LE_MULTICAST, /**< When this enum is selected, data will be updated to all OIC servers. */
49 LE_UNICAST /**< When this enum is selected, data will be updated to desired OIC Server. */
53 * This will be used to notify device status changes to the LE adapter layer.
54 * @param[in] adapter_state State of the adapter.
56 typedef void (*CALEDeviceStateChangedCallback)(CAAdapterState_t adapter_state);
59 * Notify the adapter layer that a packet was received from the GATT
62 * @param[in] remoteAddress Remote endpoint Address.
63 * @param[in] data Data received.
64 * @param[in] dataLength Length of the data received.
65 * @param[in] sentLength Length of the data sent.
67 * @return ::CA_STATUS_OK or Appropriate error code.
68 * @retval ::CA_STATUS_OK Successful.
69 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
70 * @retval ::CA_STATUS_FAILED Operation failed.
72 typedef CAResult_t (*CABLEDataReceivedCallback)(const char *remoteAddress,
75 uint32_t *sentLength);
78 * Initialize the LE adapter layer. This will be invoked from the CA
81 * @return ::CA_STATUS_OK or Appropriate error code
82 * @retval ::CA_STATUS_OK Successful
83 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
84 * @retval ::CA_STATUS_FAILED Operation failed
86 CAResult_t CAInitializeLEAdapter();
89 * Start the LE adapter layer.
91 * This function will be invoked from the CA layer when the LE
92 * "network" is selected via @c CASelectNetwork(). It gives an
93 * opportunity for LE adapter implementations to perform operations
94 * before starting a GATT client or server. Most LE adapter
95 * implementations will simply implement this function as no-op.
97 * @return ::CA_STATUS_OK or Appropriate error code
99 CAResult_t CAStartLEAdapter();
102 * Stop the LE adapter layer.
104 * This function will be invoked from the CA layer when the LE
105 * "network" is unselected via @c CAUnselectNetwork(). It gives an
106 * opportunity for LE adapter implementations to perform operations
107 * after stopping a GATT client or server. Most LE adapter
108 * implementations will simply implement this function as no-op.
110 * @return ::CA_STATUS_OK or Appropriate error code
112 CAResult_t CAStopLEAdapter();
115 * Used to get the current state of the LE adapter.
117 * @return ::CA_STATUS_OK or Appropriate error code
118 * @retval ::CA_STATUS_OK Successful
119 * @retval ::CA_ADAPTER_NOT_ENABLED adapter not enabled
120 * @retval ::CA_STATUS_FAILED Operation failed
122 CAResult_t CAGetLEAdapterState();
125 * Initialize the network monitor layer of the LE adapter. Mutex
126 * variables required to operate in this layer and other parameters
127 * can be initialized in this function.
129 * @return ::CA_STATUS_OK or Appropriate error code
130 * @retval ::CA_STATUS_OK Successful
131 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
132 * @retval ::CA_STATUS_FAILED Operation failed
134 CAResult_t CAInitializeLENetworkMonitor();
137 * Terminate the network monitor layer of the LE adapter. The
138 * variables initialized in @c CAInitializeLENetworkMonitor() must be
139 * cleared in this function.
141 void CATerminateLENetworkMonitor();
144 * Set the callback for the device state changes in the adapter.
146 * @param[in] callback Callback to notify the Device state change to
149 * @return ::CA_STATUS_OK or Appropriate error code
150 * @retval ::CA_STATUS_OK Successful
151 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
152 * @retval ::CA_STATUS_FAILED Operation failed
154 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
157 * Provides the MAC address of the local Bluetooth adapter.
159 * @param[out] local_address Pointer to the location where bd address
160 * needs to be stored.
162 * @return ::CA_STATUS_OK or Appropriate error code
163 * @retval ::CA_STATUS_OK Successful
164 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
165 * @retval ::CA_STATUS_FAILED Operation failed
167 CAResult_t CAGetLEAddress(char **local_address);
170 * Start Gatt Server thread for service creation and advertise BLE
173 * @return ::CA_STATUS_OK or Appropriate error code
174 * @retval ::CA_STATUS_OK Successful
175 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
176 * @retval ::CA_STATUS_FAILED Operation failed
178 CAResult_t CAStartLEGattServer();
181 * Stop BLE Gatt Service.
183 * @return ::CA_STATUS_OK or Appropriate error code
184 * @retval ::CA_STATUS_OK Successful
185 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
186 * @retval ::CA_STATUS_FAILED Operation failed
188 CAResult_t CAStopLEGattServer();
191 * initialize gatt server
193 * @return ::CA_STATUS_OK or Appropriate error code
194 * @retval ::CA_STATUS_OK Successful
195 * @retval ::CA_STATUS_FAILED Operation failed
197 CAResult_t CAInitializeLEGattServer();
200 * Stop Gatt Server thread and remove service registration, stop
203 void CATerminateLEGattServer();
206 * Used to store upper layer callback locally which will be used to
207 * send the data to application.
209 * @param[in] callback Callback function to pass the data to CA layer.
211 void CASetLEReqRespServerCallback(CABLEDataReceivedCallback callback);
214 * Update characteristics(Read/Write) value that we want to send to
217 * @param[in] address BD address of Gatt client
218 * @param[in] value Data that we want to send to client(unicast)
219 * @param[in] valueLen Length of the data.
221 * @return ::CA_STATUS_OK or Appropriate error code
222 * @retval ::CA_STATUS_OK Successful
223 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
224 * @retval ::CA_STATUS_FAILED Operation failed
226 CAResult_t CAUpdateCharacteristicsToGattClient(const char *address,
227 const uint8_t *value,
231 * Update characteristics(Read/Write) value that we want to multicast
234 * @param[in] value Data that we want to send to clients(multicast)
235 * @param[in] valueLen Length of the data.
237 * @return ::CA_STATUS_OK or Appropriate error code
238 * @retval ::CA_STATUS_OK Successful
239 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
240 * @retval ::CA_STATUS_FAILED Operation failed
242 CAResult_t CAUpdateCharacteristicsToAllGattClients(const uint8_t *value,
246 * Start @c CAStartBleGattClientThread for initializing Gatt Client.
248 * @return ::CA_STATUS_OK or Appropriate error code
249 * @retval ::CA_STATUS_OK Successful
250 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
251 * @retval ::CA_STATUS_FAILED Operation failed
253 CAResult_t CAStartLEGattClient();
256 * Stop Gatt client gracefully. In turn it will call the
257 * @c CATerminateBLEGattClient function.
259 * @return ::CA_STATUS_OK or Appropriate error code
260 * @retval ::CA_STATUS_OK Successful
261 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
262 * @retval ::CA_STATUS_FAILED Operation failed
264 void CAStopLEGattClient();
269 * @return ::CA_STATUS_OK or Appropriate error code
270 * @retval ::CA_STATUS_OK Successful
271 * @retval ::CA_STATUS_FAILED Operation failed
273 CAResult_t CAInitializeLEGattClient();
276 * Unset all the callbacks and stop service discovery
278 void CATerminateLEGattClient();
281 * Read the data from characteristics and invoke notify callback.
283 void CACheckLEData();
286 * Set the value of characteristic and update the value to
287 * GATTServer (unicast).
289 * @param[in] remoteAddress The address of the remote device
290 * @param[in] data The value of characteristic (byte array)
291 * @param[in] dataLen The length of value
292 * @param[in] type Type of the transfer(::CALETransferType_t)
293 * @param[in] position The unique index of each ble server. Used
294 * for multicast feature.
296 * @return ::CA_STATUS_OK or Appropriate error code
297 * @retval ::CA_STATUS_OK Successful
298 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
299 * @retval ::CA_STATUS_FAILED Operation failed
301 CAResult_t CAUpdateCharacteristicsToGattServer(const char *remoteAddress,
304 CALETransferType_t type,
308 * Set the value of characteristic and update the value to all
309 * registered GATTServer (multicast).
311 * @param[in] data The value of characteristic (byte array)
312 * @param[in] dataLen The length of value
314 * @return ::CA_STATUS_OK or Appropriate error code
315 * @retval ::CA_STATUS_OK Successful
316 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
317 * @retval ::CA_STATUS_FAILED Operation failed
319 CAResult_t CAUpdateCharacteristicsToAllGattServers(const uint8_t *data,
323 * Store upper layer callback locally which will be used to send the
324 * data to application.
326 * @param[in] callback Callback function to pass the data to CA layer.
328 void CASetLEReqRespClientCallback(CABLEDataReceivedCallback callback);
331 * Set the server thread pool handle which is required for spawning
334 * @param[in] handle Thread pool handle which is given by above layer
335 * for using thread creation task.
337 * @return ::CA_STATUS_OK or Appropriate error code
338 * @retval ::CA_STATUS_OK Successful
339 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
340 * @retval ::CA_STATUS_FAILED Operation failed
342 void CASetLEServerThreadPoolHandle(ca_thread_pool_t handle);
345 * Set the client thread pool handle which is required for spawning new
348 * @param[in] handle Thread pool handle which is given by above layer
349 * for using thread creation task.
351 void CASetLEClientThreadPoolHandle(ca_thread_pool_t handle);
354 * Unset the callback of adapter connection state change.
356 * @return ::CA_STATUS_OK or Appropriate error code.
357 * @retval ::CA_STATUS_OK Successful.
358 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
359 * @retval ::CA_STATUS_FAILED Operation failed.
361 CAResult_t CAUnSetLEAdapterStateChangedCb();
364 * This will be used to notify errors in BLE adapter.
366 * @param[in] remoteAddress Remote endpoint Address
367 * @param[in] data Data received
368 * @param[in] dataLength Length of the data received
369 * @param[in] result error code as per CAResult_t
371 typedef void (*CABLEErrorHandleCallback)(const char *remoteAddress,
376 * Set the client error handler callback.
378 * @param[in] callback Callback function to update error to the
381 void CASetBLEClientErrorHandleCallback(CABLEErrorHandleCallback callback);
385 * Set the server error handler callback.
387 * @param[in] callback Callback function to update error to the
390 void CASetBLEServerErrorHandleCallback(CABLEErrorHandleCallback callback);
396 #endif /* CA_LE_INTERFACE_H_ */