Update snapshot(2018-02-07)
[platform/upstream/iotivity.git] / 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
23  *
24  * This file provides APIs for BLE modules.
25  */
26
27 #ifndef CA_LE_INTERFACE_H_
28 #define CA_LE_INTERFACE_H_
29
30 #include <stdbool.h>
31
32 #include "cacommon.h"
33 #include "cathreadpool.h"
34 #include "uarraylist.h"
35
36 #ifdef __cplusplus
37 extern "C"
38 {
39 #endif
40
41 /**
42  * Provide info about different mode of data transfer.
43  *
44  * This enum is used to differentiate between unicast and multicast
45  * data transfer.
46  */
47 typedef enum
48 {
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. */
51 } CALETransferType_t;
52
53 /**
54  * Stores the information of the Data to be sent from the queues.
55  *
56  * This structure will be pushed to the sender/receiver queue for
57  * processing.
58  */
59 typedef struct
60 {
61     /// Remote endpoint contains the information of remote device.
62     CAEndpoint_t *remoteEndpoint;
63
64     /// Data to be transmitted over LE transport.
65     uint8_t *data;
66
67     /// Length of the data being transmitted.
68     uint32_t dataLen;
69
70     /// Sender information list
71     u_arraylist_t * senderInfo;
72 } CALEData_t;
73
74 /**
75  * The MTU supported for BLE adapter
76  */
77 #ifdef __APPLE__
78 #define CA_DEFAULT_BLE_MTU_SIZE  152
79 #else
80 #define CA_DEFAULT_BLE_MTU_SIZE  20
81 #endif
82 /**
83  * The MTU supported for BLE spec
84  */
85 #define CA_SUPPORTED_BLE_MTU_SIZE  517
86
87 /**
88  * The Header of the MTU supported for BLE spec
89  */
90 #define CA_BLE_MTU_HEADER_SIZE  5
91
92 /**
93  * This will be used to notify device status changes to the LE adapter layer.
94  * @param[in]  adapter_state State of the adapter.
95  */
96 typedef void (*CALEDeviceStateChangedCallback)(CAAdapterState_t adapter_state);
97
98 /**
99  * This will be used to notify device connection state changes to the LE adapter layer.
100  * @param[in]   adapter        Transport type information.
101  * @param[in]   remoteAddress  Endpoint object from which the connection status is changed.
102  * @param[in]   connected      State of connection.
103  */
104 typedef void (*CALEConnectionStateChangedCallback)(CATransportAdapter_t adapter,
105                                                    const char *remoteAddress, bool connected);
106
107 /**
108  * Notify the adapter layer that a packet was received from the GATT
109  * peer.
110  *
111  * @param[in]  remoteAddress  Remote endpoint Address.
112  * @param[in]  data           Data received.
113  * @param[in]  dataLength     Length of the data received.
114  * @param[in]  sentLength     Length of the data sent.
115  *
116  * @return ::CA_STATUS_OK or Appropriate error code.
117  * @retval ::CA_STATUS_OK  Successful.
118  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
119  * @retval ::CA_STATUS_FAILED Operation failed.
120  */
121 typedef CAResult_t (*CABLEDataReceivedCallback)(const char *remoteAddress,
122                                                 const uint8_t *data,
123                                                 uint32_t dataLength,
124                                                 uint32_t *sentLength);
125
126 /**
127  * Initialize the LE adapter layer. This will be invoked from the CA
128  * layer.
129  *
130  * @param[in] threadPool Thread pool handle
131  * @return ::CA_STATUS_OK or Appropriate error code
132  * @retval ::CA_STATUS_OK  Successful
133  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
134  * @retval ::CA_STATUS_FAILED Operation failed
135  */
136 CAResult_t CAInitializeLEAdapter();
137
138 /**
139  * Start the LE adapter layer.
140  *
141  * This function will be invoked from the CA layer when the LE
142  * "network" is selected via @c CASelectNetwork().  It gives an
143  * opportunity for LE adapter implementations to perform operations
144  * before starting a GATT client or server.  Most LE adapter
145  * implementations will simply implement this function as no-op.
146  *
147  * @return ::CA_STATUS_OK or Appropriate error code
148  */
149 CAResult_t CAStartLEAdapter();
150
151 /**
152  * Stop the LE adapter layer.
153  *
154  * This function will be invoked from the CA layer when the LE
155  * "network" is unselected via @c CAUnselectNetwork().  It gives an
156  * opportunity for LE adapter implementations to perform operations
157  * after stopping a GATT client or server.  Most LE adapter
158  * implementations will simply implement this function as no-op.
159  *
160  * @return ::CA_STATUS_OK or Appropriate error code
161  */
162 CAResult_t CAStopLEAdapter();
163
164 /**
165  * Used to get the current state of the LE adapter.
166  *
167  * @return ::CA_STATUS_OK or Appropriate error code
168  * @retval ::CA_STATUS_OK  Successful
169  * @retval ::CA_ADAPTER_NOT_ENABLED  adapter not enabled
170  * @retval ::CA_STATUS_FAILED Operation failed
171  */
172 CAResult_t CAGetLEAdapterState();
173
174 /**
175  * Initialize the network monitor layer of the LE adapter.  Mutex
176  * variables required to operate in this layer and other parameters
177  * can be initialized in this function.
178  *
179  * @return ::CA_STATUS_OK or Appropriate error code
180  * @retval ::CA_STATUS_OK  Successful
181  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
182  * @retval ::CA_STATUS_FAILED Operation failed
183  */
184 CAResult_t CAInitializeLENetworkMonitor();
185
186 /**
187  * Terminate the network monitor layer of the LE adapter. The
188  * variables initialized in @c CAInitializeLENetworkMonitor() must be
189  * cleared in this function.
190  */
191 void CATerminateLENetworkMonitor();
192
193 /**
194  * Set the callback for the device state changes in the adapter.
195  *
196  * @param[in] callback Callback to notify the Device state change to
197  *            the CA Layer
198  *
199  * @return ::CA_STATUS_OK or Appropriate error code
200  * @retval ::CA_STATUS_OK  Successful
201  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
202  * @retval ::CA_STATUS_FAILED Operation failed
203  */
204 CAResult_t CASetLEAdapterStateChangedCb(CALEDeviceStateChangedCallback callback);
205
206 /**
207  * Set the callback for the device connection state changes.
208  *
209  * @param[in] callback Callback to notify the Device connection state change to
210  *            the CA Layer
211  *
212  * @return ::CA_STATUS_OK or Appropriate error code
213  * @retval ::CA_STATUS_OK  Successful
214  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
215  * @retval ::CA_STATUS_FAILED Operation failed
216  */
217 CAResult_t CASetLENWConnectionStateChangedCb(CALEConnectionStateChangedCallback callback);
218
219 /**
220  * Provides the MAC address of the local Bluetooth adapter.
221  *
222  * @param[out] local_address Pointer to the location where bd address
223  *                           needs to be stored.
224  *
225  * @return ::CA_STATUS_OK or Appropriate error code
226  * @retval ::CA_STATUS_OK  Successful
227  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
228  * @retval ::CA_STATUS_FAILED Operation failed
229  */
230 CAResult_t CAGetLEAddress(char **local_address);
231
232 /**
233  * Start Gatt Server thread for service creation and advertise BLE
234  * service.
235  *
236  * @return ::CA_STATUS_OK or Appropriate error code
237  * @retval ::CA_STATUS_OK  Successful
238  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
239  * @retval ::CA_STATUS_FAILED Operation failed
240  */
241 CAResult_t CAStartLEGattServer();
242
243 /**
244  * Stop BLE Gatt Service.
245  *
246  * @return ::CA_STATUS_OK or Appropriate error code
247  * @retval ::CA_STATUS_OK  Successful
248  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
249  * @retval ::CA_STATUS_FAILED Operation failed
250  */
251 CAResult_t CAStopLEGattServer();
252
253 /**
254  * initialize gatt server
255  *
256  * @return ::CA_STATUS_OK or Appropriate error code
257  * @retval ::CA_STATUS_OK  Successful
258  * @retval ::CA_STATUS_FAILED Operation failed
259  */
260 CAResult_t CAInitializeLEGattServer();
261
262 /**
263  * Stop Gatt Server thread and remove service registration, stop
264  * advertising.
265  */
266 void CATerminateLEGattServer();
267
268 /**
269  * Used to store upper layer callback locally which will be used to
270  * send the data to application.
271  *
272  * @param[in] callback Callback function to pass the data to CA layer.
273  */
274 void CASetLEReqRespServerCallback(CABLEDataReceivedCallback callback);
275
276 /**
277  * Update characteristics(Read/Write) value that we want to send to
278  * particular client.
279  *
280  * @param[in] address  BD address of Gatt client
281  * @param[in] value    Data that we want to send to client(unicast)
282  * @param[in] valueLen Length of the data.
283  *
284  * @return ::CA_STATUS_OK or Appropriate error code
285  * @retval ::CA_STATUS_OK  Successful
286  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
287  * @retval ::CA_STATUS_FAILED Operation failed
288  */
289 CAResult_t CAUpdateCharacteristicsToGattClient(const char *address,
290                                                const uint8_t *value,
291                                                uint32_t valueLen);
292
293 /**
294  * Update characteristics(Read/Write) value that we want to multicast
295  * to all clients.
296  *
297  * @param[in] value    Data that we want to send to clients(multicast)
298  * @param[in] valueLen Length of the data.
299  *
300  * @return ::CA_STATUS_OK or Appropriate error code
301  * @retval ::CA_STATUS_OK  Successful
302  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
303  * @retval ::CA_STATUS_FAILED Operation failed
304  */
305 CAResult_t CAUpdateCharacteristicsToAllGattClients(const uint8_t *value,
306                                                    uint32_t valueLen);
307
308 /**
309  * Start @c CAStartBleGattClientThread for initializing Gatt Client.
310  *
311  * @return ::CA_STATUS_OK or Appropriate error code
312  * @retval ::CA_STATUS_OK  Successful
313  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
314  * @retval ::CA_STATUS_FAILED Operation failed
315  */
316 CAResult_t CAStartLEGattClient();
317
318 /**
319  * Stop Gatt client gracefully.  In turn it will call the
320  * @c CATerminateBLEGattClient function.
321  *
322  * @return ::CA_STATUS_OK or Appropriate error code
323  * @retval ::CA_STATUS_OK  Successful
324  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
325  * @retval ::CA_STATUS_FAILED Operation failed
326  */
327 void CAStopLEGattClient();
328
329 /**
330  * initialize Client
331  *
332  * @return ::CA_STATUS_OK or Appropriate error code
333  * @retval ::CA_STATUS_OK  Successful
334  * @retval ::CA_STATUS_FAILED Operation failed
335  */
336 CAResult_t CAInitializeLEGattClient();
337
338 /**
339  * Unset all the callbacks and stop service discovery
340  */
341 void CATerminateLEGattClient();
342
343 /**
344  * Read the data from characteristics and invoke notify callback.
345  */
346 void CACheckLEData();
347
348 /**
349  * Set the value of characteristic and update the value to
350  * GATTServer (unicast).
351  *
352  * @param[in] remoteAddress The address of the remote device
353  * @param[in] data          The value of characteristic (byte array)
354  * @param[in] dataLen       The length of value
355  * @param[in] type          Type of the transfer(::CALETransferType_t)
356  * @param[in] position      The unique index of each ble server. Used
357  *                          for multicast feature.
358  *
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
363  */
364 CAResult_t  CAUpdateCharacteristicsToGattServer(const char *remoteAddress,
365                                                 const uint8_t *data,
366                                                 uint32_t dataLen,
367                                                 CALETransferType_t type,
368                                                 int32_t position);
369
370 /**
371  * Set the value of characteristic and update the value to all
372  * registered GATTServer (multicast).
373  *
374  * @param[in]  data    The value of characteristic (byte array)
375  * @param[in]  dataLen The length of value
376  *
377  * @return ::CA_STATUS_OK or Appropriate error code
378  * @retval ::CA_STATUS_OK  Successful
379  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
380  * @retval ::CA_STATUS_FAILED Operation failed
381  */
382 CAResult_t CAUpdateCharacteristicsToAllGattServers(const uint8_t *data,
383                                                    uint32_t dataLen);
384
385 /**
386  * Store upper layer callback locally which will be used to send the
387  * data to application.
388  *
389  * @param[in] callback Callback function to pass the data to CA layer.
390  */
391 void CASetLEReqRespClientCallback(CABLEDataReceivedCallback callback);
392
393 /**
394  * Set the server thread pool handle which is required for spawning
395  * new thread.
396  *
397  * @param[in] handle Thread pool handle which is given by above layer
398  *                   for using thread creation task.
399  *
400  * @return ::CA_STATUS_OK or Appropriate error code
401  * @retval ::CA_STATUS_OK  Successful
402  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
403  * @retval ::CA_STATUS_FAILED Operation failed
404  */
405 void CASetLEServerThreadPoolHandle(ca_thread_pool_t handle);
406
407 /**
408 * Set the client thread pool handle which is required for spawning new
409 * thread.
410 *
411 * @param[in] handle Thread pool handle which is given by above layer
412 *                   for using thread creation task.
413 */
414 void CASetLEClientThreadPoolHandle(ca_thread_pool_t handle);
415
416 /**
417  * Unset the callback of adapter state change.
418  *
419  * @return ::CA_STATUS_OK or Appropriate error code.
420  * @retval ::CA_STATUS_OK  Successful.
421  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
422  * @retval ::CA_STATUS_FAILED Operation failed.
423  */
424 CAResult_t CAUnSetLEAdapterStateChangedCb();
425
426 /**
427  * Unset the callback of adapter connection state change.
428  *
429  * @return ::CA_STATUS_OK or Appropriate error code.
430  * @retval ::CA_STATUS_OK  Successful.
431  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
432  * @retval ::CA_STATUS_FAILED Operation failed.
433  */
434 CAResult_t CAUnSetLENWConnectionStateChangedCb();
435
436 /**
437  * This will be used to notify errors in BLE adapter.
438  *
439  * @param[in] remoteAddress Remote endpoint Address
440  * @param[in] data          Data received
441  * @param[in] dataLength    Length of the data received
442  * @param[in] result        error code as per CAResult_t
443  */
444 typedef void (*CABLEErrorHandleCallback)(const char *remoteAddress,
445                                          const uint8_t *data,
446                                          uint32_t dataLength,
447                                          CAResult_t result);
448 /**
449  * Set the client error handler callback.
450  *
451  * @param[in] callback Callback function to update error to the
452  *                     adapter.
453  */
454 void CASetBLEClientErrorHandleCallback(CABLEErrorHandleCallback callback);
455
456
457 /**
458  * Set the server error handler callback.
459  *
460  * @param[in] callback Callback function to update error to the
461  *                     adapter.
462  */
463 void CASetBLEServerErrorHandleCallback(CABLEErrorHandleCallback callback);
464
465 /**
466  * This is the callback which will be called whenever there is change in gatt connection
467  * with Client(Connected/Disconnected).
468  *
469  * @param[in]  connected      State of connection.
470  * @param[in]  remoteAddress  Mac address of the remote device in which we made connection.
471  */
472 void CALEGattServerConnectionStateChanged(bool connected, const char *remoteAddress);
473
474 /**
475  * This is the callback which will be called whenever there is change in gatt connection
476  * with server(Connected/Disconnected)
477  *
478  * @param[in]  connected     State of connection
479  * @param[in]  remoteAddress Mac address of the remote device in which we made connection.
480  */
481 void CALEGattConnectionStateChanged(bool connected, const char *remoteAddress);
482
483 #ifdef __cplusplus
484 }
485 #endif
486
487 #endif /* CA_LE_INTERFACE_H_ */