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"
34 #include "uarraylist.h"
42 * Provide info about different mode of data transfer.
44 * This enum is used to differentiate between unicast and multicast
49 LE_MULTICAST, /**< When this enum is selected, data will be updated to all OIC servers. */
50 LE_UNICAST /**< When this enum is selected, data will be updated to desired OIC Server. */
54 * Stores the information of the Data to be sent from the queues.
56 * This structure will be pushed to the sender/receiver queue for
61 /// Remote endpoint contains the information of remote device.
62 CAEndpoint_t *remoteEndpoint;
64 /// Data to be transmitted over LE transport.
67 /// Length of the data being transmitted.
70 /// Sender information list
71 u_arraylist_t * senderInfo;
75 * This will be used to notify device status changes to the LE adapter layer.
76 * @param[in] adapter_state State of the adapter.
78 typedef void (*CALEDeviceStateChangedCallback)(CAAdapterState_t adapter_state);
81 * This will be used to notify device connection state changes to the LE adapter layer.
82 * @param[in] adapter Transport type information.
83 * @param[in] remoteAddress Endpoint object from which the connection status is changed.
84 * @param[in] connected State of connection.
86 typedef void (*CALEConnectionStateChangedCallback)(CATransportAdapter_t adapter,
87 const char *remoteAddress, bool connected);
90 * Notify the adapter layer that a packet was received from the GATT
93 * @param[in] remoteAddress Remote endpoint Address.
94 * @param[in] data Data received.
95 * @param[in] dataLength Length of the data received.
96 * @param[in] sentLength Length of the data sent.
98 * @return ::CA_STATUS_OK or Appropriate error code.
99 * @retval ::CA_STATUS_OK Successful.
100 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
101 * @retval ::CA_STATUS_FAILED Operation failed.
103 typedef CAResult_t (*CABLEDataReceivedCallback)(const char *remoteAddress,
106 uint32_t *sentLength);
109 * Initialize the LE adapter layer. This will be invoked from the CA
112 * @param[in] threadPool Thread pool handle
113 * @return ::CA_STATUS_OK or Appropriate error code
114 * @retval ::CA_STATUS_OK Successful
115 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
116 * @retval ::CA_STATUS_FAILED Operation failed
118 CAResult_t CAInitializeLEAdapter(const ca_thread_pool_t threadPool);
121 * Start the LE adapter layer.
123 * This function will be invoked from the CA layer when the LE
124 * "network" is selected via @c CASelectNetwork(). It gives an
125 * opportunity for LE adapter implementations to perform operations
126 * before starting a GATT client or server. Most LE adapter
127 * implementations will simply implement this function as no-op.
129 * @return ::CA_STATUS_OK or Appropriate error code
131 CAResult_t CAStartLEAdapter();
134 * Stop the LE adapter layer.
136 * This function will be invoked from the CA layer when the LE
137 * "network" is unselected via @c CAUnselectNetwork(). It gives an
138 * opportunity for LE adapter implementations to perform operations
139 * after stopping a GATT client or server. Most LE adapter
140 * implementations will simply implement this function as no-op.
142 * @return ::CA_STATUS_OK or Appropriate error code
144 CAResult_t CAStopLEAdapter();
147 * Used to get the current state of the LE adapter.
149 * @return ::CA_STATUS_OK or Appropriate error code
150 * @retval ::CA_STATUS_OK Successful
151 * @retval ::CA_ADAPTER_NOT_ENABLED adapter not enabled
152 * @retval ::CA_STATUS_FAILED Operation failed
154 CAResult_t CAGetLEAdapterState();
157 * Initialize the network monitor layer of the LE adapter. Mutex
158 * variables required to operate in this layer and other parameters
159 * can be initialized in this function.
161 * @return ::CA_STATUS_OK or Appropriate error code
162 * @retval ::CA_STATUS_OK Successful
163 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
164 * @retval ::CA_STATUS_FAILED Operation failed
166 CAResult_t CAInitializeLENetworkMonitor();
169 * Terminate the network monitor layer of the LE adapter. The
170 * variables initialized in @c CAInitializeLENetworkMonitor() must be
171 * cleared in this function.
173 void CATerminateLENetworkMonitor();
176 * Set the callback for the device state changes in the adapter.
178 * @param[in] callback Callback to notify the Device state change to
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
186 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
189 * Set the callback for the device connection state changes.
191 * @param[in] callback Callback to notify the Device connection state change to
194 * @return ::CA_STATUS_OK or Appropriate error code
195 * @retval ::CA_STATUS_OK Successful
196 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
197 * @retval ::CA_STATUS_FAILED Operation failed
199 CAResult_t CASetLENWConnectionStateChangedCb(CALEConnectionStateChangedCallback callback);
202 * Provides the MAC address of the local Bluetooth adapter.
204 * @param[out] local_address Pointer to the location where bd address
205 * needs to be stored.
207 * @return ::CA_STATUS_OK or Appropriate error code
208 * @retval ::CA_STATUS_OK Successful
209 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
210 * @retval ::CA_STATUS_FAILED Operation failed
212 CAResult_t CAGetLEAddress(char **local_address);
215 * Start Gatt Server thread for service creation and advertise BLE
218 * @return ::CA_STATUS_OK or Appropriate error code
219 * @retval ::CA_STATUS_OK Successful
220 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
221 * @retval ::CA_STATUS_FAILED Operation failed
223 CAResult_t CAStartLEGattServer();
226 * Stop BLE Gatt Service.
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
233 CAResult_t CAStopLEGattServer();
236 * initialize gatt server
238 * @return ::CA_STATUS_OK or Appropriate error code
239 * @retval ::CA_STATUS_OK Successful
240 * @retval ::CA_STATUS_FAILED Operation failed
242 CAResult_t CAInitializeLEGattServer();
245 * Stop Gatt Server thread and remove service registration, stop
248 void CATerminateLEGattServer();
251 * Used to store upper layer callback locally which will be used to
252 * send the data to application.
254 * @param[in] callback Callback function to pass the data to CA layer.
256 void CASetLEReqRespServerCallback(CABLEDataReceivedCallback callback);
259 * Update characteristics(Read/Write) value that we want to send to
262 * @param[in] address BD address of Gatt client
263 * @param[in] value Data that we want to send to client(unicast)
264 * @param[in] valueLen Length of the data.
266 * @return ::CA_STATUS_OK or Appropriate error code
267 * @retval ::CA_STATUS_OK Successful
268 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
269 * @retval ::CA_STATUS_FAILED Operation failed
271 CAResult_t CAUpdateCharacteristicsToGattClient(const char *address,
272 const uint8_t *value,
276 * Update characteristics(Read/Write) value that we want to multicast
279 * @param[in] value Data that we want to send to clients(multicast)
280 * @param[in] valueLen Length of the data.
282 * @return ::CA_STATUS_OK or Appropriate error code
283 * @retval ::CA_STATUS_OK Successful
284 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
285 * @retval ::CA_STATUS_FAILED Operation failed
287 CAResult_t CAUpdateCharacteristicsToAllGattClients(const uint8_t *value,
291 * Start @c CAStartBleGattClientThread for initializing Gatt Client.
293 * @return ::CA_STATUS_OK or Appropriate error code
294 * @retval ::CA_STATUS_OK Successful
295 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
296 * @retval ::CA_STATUS_FAILED Operation failed
298 CAResult_t CAStartLEGattClient();
301 * Stop Gatt client gracefully. In turn it will call the
302 * @c CATerminateBLEGattClient function.
304 * @return ::CA_STATUS_OK or Appropriate error code
305 * @retval ::CA_STATUS_OK Successful
306 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
307 * @retval ::CA_STATUS_FAILED Operation failed
309 void CAStopLEGattClient();
314 * @return ::CA_STATUS_OK or Appropriate error code
315 * @retval ::CA_STATUS_OK Successful
316 * @retval ::CA_STATUS_FAILED Operation failed
318 CAResult_t CAInitializeLEGattClient();
321 * Unset all the callbacks and stop service discovery
323 void CATerminateLEGattClient();
326 * Read the data from characteristics and invoke notify callback.
328 void CACheckLEData();
331 * Set the value of characteristic and update the value to
332 * GATTServer (unicast).
334 * @param[in] remoteAddress The address of the remote device
335 * @param[in] data The value of characteristic (byte array)
336 * @param[in] dataLen The length of value
337 * @param[in] type Type of the transfer(::CALETransferType_t)
338 * @param[in] position The unique index of each ble server. Used
339 * for multicast feature.
341 * @return ::CA_STATUS_OK or Appropriate error code
342 * @retval ::CA_STATUS_OK Successful
343 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
344 * @retval ::CA_STATUS_FAILED Operation failed
346 CAResult_t CAUpdateCharacteristicsToGattServer(const char *remoteAddress,
349 CALETransferType_t type,
353 * Set the value of characteristic and update the value to all
354 * registered GATTServer (multicast).
356 * @param[in] data The value of characteristic (byte array)
357 * @param[in] dataLen The length of value
359 * @return ::CA_STATUS_OK or Appropriate error code
360 * @retval ::CA_STATUS_OK Successful
361 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
362 * @retval ::CA_STATUS_FAILED Operation failed
364 CAResult_t CAUpdateCharacteristicsToAllGattServers(const uint8_t *data,
368 * Store upper layer callback locally which will be used to send the
369 * data to application.
371 * @param[in] callback Callback function to pass the data to CA layer.
373 void CASetLEReqRespClientCallback(CABLEDataReceivedCallback callback);
376 * Set the server thread pool handle which is required for spawning
379 * @param[in] handle Thread pool handle which is given by above layer
380 * for using thread creation task.
382 * @return ::CA_STATUS_OK or Appropriate error code
383 * @retval ::CA_STATUS_OK Successful
384 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments
385 * @retval ::CA_STATUS_FAILED Operation failed
387 void CASetLEServerThreadPoolHandle(ca_thread_pool_t handle);
390 * Set the client thread pool handle which is required for spawning new
393 * @param[in] handle Thread pool handle which is given by above layer
394 * for using thread creation task.
396 void CASetLEClientThreadPoolHandle(ca_thread_pool_t handle);
399 * Unset the callback of adapter state change.
401 * @return ::CA_STATUS_OK or Appropriate error code.
402 * @retval ::CA_STATUS_OK Successful.
403 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
404 * @retval ::CA_STATUS_FAILED Operation failed.
406 CAResult_t CAUnSetLEAdapterStateChangedCb();
409 * Unset the callback of adapter connection state change.
411 * @return ::CA_STATUS_OK or Appropriate error code.
412 * @retval ::CA_STATUS_OK Successful.
413 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
414 * @retval ::CA_STATUS_FAILED Operation failed.
416 CAResult_t CAUnSetLENWConnectionStateChangedCb();
419 * This will be used to notify errors in BLE adapter.
421 * @param[in] remoteAddress Remote endpoint Address
422 * @param[in] data Data received
423 * @param[in] dataLength Length of the data received
424 * @param[in] result error code as per CAResult_t
426 typedef void (*CABLEErrorHandleCallback)(const char *remoteAddress,
431 * Set the client error handler callback.
433 * @param[in] callback Callback function to update error to the
436 void CASetBLEClientErrorHandleCallback(CABLEErrorHandleCallback callback);
440 * Set the server error handler callback.
442 * @param[in] callback Callback function to update error to the
445 void CASetBLEServerErrorHandleCallback(CABLEErrorHandleCallback callback);
450 #endif /* CA_LE_INTERFACE_H_ */