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 ******************************************************************/
23 * This file contains the APIs for BT LE communications.
25 #ifndef CA_LECLIENT_H_
26 #define CA_LECLIENT_H_
28 #include "calestate.h"
30 #include "cathreadpool.h"
31 #include "uarraylist.h"
44 BLE_SCAN_ENABLE = 0, /**< BLE scan is working */
45 BLE_SCAN_DISABLE, /**< BLE scan is not working */
46 BLE_SCAN_NONE /**< Initialize State */
50 * Callback to be notified on reception of any data from remote devices.
51 * @param[in] address MAC address of remote device.
52 * @param[in] data Data received from remote device.
53 * @pre Callback must be registered using CALESetCallback(CAPacketReceiveCallback callback)
55 typedef void (*CAPacketReceiveCallback)(const char *address, const uint8_t *data);
58 * initialize JNI object.
60 void CALEClientJniInit();
63 * set context of application.
65 void CALEClientJNISetContext();
68 * create interface object and initialize the object.
69 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
71 CAResult_t CALEClientCreateJniInterfaceObject();
74 * set UUID for setting scanfilter
75 * @param[in] uuid UUID string(service UUID or manufacture data)
76 * @param[in] uuid_type Type of UUID i.e. service UUID or manufacture data
78 void CALEClientAddUuid(char* uuid, int uuid_type);
80 * initialize client for BLE.
81 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
83 CAResult_t CALEClientInitialize();
86 * terminate client for BLE.
88 void CALEClientTerminate();
91 * destroy interface object and terminate the interface.
92 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
94 CAResult_t CALEClientDestroyJniInterface();
97 * for destroy sending routine.
98 * @param[in] env JNI interface pointer.
99 * @param[in] gatt Gatt profile object.
101 void CALEClientSendFinish(JNIEnv *env, jobject gatt);
104 * send negotiation message after gatt connection is done.
105 * @param[in] address remote address.
106 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
108 CAResult_t CALEClientSendNegotiationMessage(const char* address);
111 * send data for unicast (interface).
112 * @param[in] address remote address.
113 * @param[in] data data for transmission.
114 * @param[in] dataLen data length.
115 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
117 CAResult_t CALEClientSendUnicastMessage(const char *address, const uint8_t *data,
118 const uint32_t dataLen);
121 * send data for multicast (interface).
122 * @param[in] data data for transmission.
123 * @param[in] dataLen data length.
124 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
126 CAResult_t CALEClientSendMulticastMessage(const uint8_t *data, const uint32_t dataLen);
129 * start unicast server.
130 * @param[in] address remote address.
131 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
133 CAResult_t CALEClientStartUnicastServer(const char *address);
136 * start multicast server (start discovery).
137 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
139 CAResult_t CALEClientStartMulticastServer();
142 * stop unicast server.
144 void CALEClientStopUnicastServer();
147 * stop multicast server (stop discovery).
149 void CALEClientStopMulticastServer();
152 * set this callback for receiving data packets from peer devices.
153 * @param[in] callback callback to be notified on reception of
154 * unicast/multicast data packets.
156 void CALEClientSetCallback(CAPacketReceiveCallback callback);
159 * waiting to get scanned device from BT Platform.
160 * if there is no scanned device in the list.
161 * @param[in] env JNI interface pointer.
162 * @param[in] address LE address.
163 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
165 CAResult_t CALEClientIsThereScannedDevices(JNIEnv *env, const char* address);
168 * send data for unicast (implement).
169 * @param[in] address remote address.
170 * @param[in] data data for transmission.
171 * @param[in] dataLen data length.
172 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
174 CAResult_t CALEClientSendUnicastMessageImpl(const char *address, const uint8_t *data,
175 const uint32_t dataLen);
178 * send data for multicast (implement).
179 * @param[in] env JNI interface pointer.
180 * @param[in] data data for transmission.
181 * @param[in] dataLen data length.
182 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
184 CAResult_t CALEClientSendMulticastMessageImpl(JNIEnv *env, const uint8_t *data,
185 const uint32_t dataLen);
188 * send data to remote device.
189 * if it isn't connected yet. connect LE before try to send data.
190 * @param[in] env JNI interface pointer.
191 * @param[in] device bluetooth device object.
192 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
194 CAResult_t CALEClientSendData(JNIEnv *env, jobject device);
197 * get address from bluetooth gatt object.
198 * @param[in] env JNI interface pointer.
199 * @param[in] gatt Gatt profile object.
200 * @return bluetooth address.
202 jstring CALEClientGetAddressFromGattObj(JNIEnv *env, jobject gatt);
205 * get remote address from bluetooth socket object.
206 * @param[in] env JNI interface pointer.
207 * @param[in] bluetoothSocketObj bluetooth socket.
208 * @return bluetooth address.
210 jstring CALEClientGetRemoteAddress(JNIEnv *env, jobject bluetoothSocketObj);
214 * @param[in] env JNI interface pointer.
215 * @param[in] bluetoothGatt gatt profile object.
216 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
218 CAResult_t CALEClientGattClose(JNIEnv *env, jobject bluetoothGatt);
221 * start to scan whole bluetooth devices (interface).
222 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
224 CAResult_t CALEClientStartScan();
227 * start to scan whole bluetooth devices (implement).
228 * @param[in] env JNI interface pointer.
229 * @param[in] callback callback to receive device object by scanning.
230 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
232 CAResult_t CALEClientStartScanImpl(JNIEnv *env, jobject callback);
235 * start to scan whole bluetooth devices for android API level 21 (implement).
236 * @param[in] env JNI interface pointer.
237 * @param[in] callback callback to receive device object by scanning.
238 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
240 CAResult_t CALEClientStartScanImplForV21(JNIEnv *env, jobject callback);
243 * start to scan target bluetooth devices for service uuid (implement).
244 * @param[in] env JNI interface pointer.
245 * @param[in] uuids target UUID.
246 * @param[in] callback callback to receive device object by scanning.
247 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
249 CAResult_t CALEClientStartScanWithUUIDImpl(JNIEnv *env, jobjectArray uuids,
253 * start to scan target bluetooth devices for service uuid for android API level 21 (implement).
254 * @param[in] env JNI interface pointer.
255 * @param[in] uuids target UUID.
256 * @param[in] callback callback to receive device object by scanning.
257 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
259 CAResult_t CALEClientStartScanWithUUIDImplForV21(JNIEnv *env, jobjectArray uuids,
264 * @param[in] env JNI interface pointer.
265 * @param[in] uuid uuid.
266 * @return uuid object.
268 jobject CALEClientGetUUIDObject(JNIEnv *env, const char *uuid);
271 * stop scan (interface).
272 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
274 CAResult_t CALEClientStopScan();
277 * stop scan (implement).
278 * @param[in] env JNI interface pointer.
279 * @param[in] callback callback to receive device object by scanning.
280 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
282 CAResult_t CALEClientStopScanImpl(JNIEnv *env, jobject callback);
285 * stop scan for android API level 21(implement).
286 * @param[in] env JNI interface pointer.
287 * @param[in] callback callback to receive device object by scanning.
288 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
290 CAResult_t CALEClientStopScanImplForV21(JNIEnv *env, jobject callback);
293 * connect to gatt server hosted.
294 * @param[in] env JNI interface pointer.
295 * @param[in] bluetoothDevice bluetooth Device object.
296 * @param[in] autoconnect whether to directly connect to the remote device(false) or
297 * to automatically connect as soon as the remote device
299 * @return gatt object
301 jobject CALEClientConnect(JNIEnv *env, jobject bluetoothDevice, jboolean autoconnect);
304 * disconnect to gatt server by a target device.
305 * @param[in] env JNI interface pointer.
306 * @param[in] bluetoothGatt Gatt profile object.
307 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
309 CAResult_t CALEClientDisconnect(JNIEnv *env, jobject bluetoothGatt);
312 * disconnect to gatt server by whole devices.
313 * @param[in] env JNI interface pointer.
314 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
316 CAResult_t CALEClientDisconnectAll(JNIEnv *env);
319 * disconnect to gatt server by selected address.
320 * @param[in] env JNI interface pointer.
321 * @param[in] remoteAddress remote address.
322 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
324 CAResult_t CALEClientDisconnectforAddress(JNIEnv *env, jstring remoteAddress);
327 * request MTU size negotiation to server.
328 * @param[in] env JNI interface pointer.
329 * @param[in] bluetoothGatt gatt object.
330 * @param[in] size MTU size.
331 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
333 CAResult_t CALEClientRequestMTU(JNIEnv *env, jobject bluetoothGatt, jint size);
335 * start discovery server.
336 * @param[in] env JNI interface pointer.
337 * @param[in] bluetoothGatt Gatt profile object.
338 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
340 CAResult_t CALEClientDiscoverServices(JNIEnv *env, jobject bluetoothGatt);
343 * call CALESetValueAndWriteCharacteristic when connection is successful.
344 * @param[in] env JNI interface pointer.
345 * @param[in] gatt Gatt profile object.
346 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
348 CAResult_t CALEClientWriteCharacteristic(JNIEnv *env, jobject gatt);
351 * create GattCharacteristic and call CALEClientWriteCharacteristicImpl
352 * for request to write gatt characteristic.
353 * @param[in] env JNI interface pointer.
354 * @param[in] gatt Gatt profile object.
355 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
357 CAResult_t CALESetValueAndWriteCharacteristic(JNIEnv *env, jobject gatt);
360 * request to write gatt characteristic.
361 * @param[in] env JNI interface pointer.
362 * @param[in] bluetoothGatt Gatt profile object.
363 * @param[in] gattCharacteristic characteristic object that contain data to send.
364 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
366 CAResult_t CALEClientWriteCharacteristicImpl(JNIEnv *env, jobject bluetoothGatt,
367 jobject gattCharacteristic);
370 * request to read gatt characteristic.
371 * @param[in] env JNI interface pointer.
372 * @param[in] bluetoothGatt Gatt profile object.
373 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
375 CAResult_t CALEClientReadCharacteristic(JNIEnv *env, jobject bluetoothGatt);
378 * enable notification for a target device.
379 * @param[in] env JNI interface pointer.
380 * @param[in] bluetoothGatt Gatt profile object.
381 * @param[in] characteristic Characteristic object.
382 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
384 CAResult_t CALEClientSetCharacteristicNotification(JNIEnv *env, jobject bluetoothGatt,
385 jobject characteristic);
388 * create gatt characteristic object.
389 * @param[in] env JNI interface pointer.
390 * @param[in] bluetoothGatt Gatt profile object.
391 * @param[in] data for make Characteristic with data.
392 * @return Gatt Characteristic object.
394 jobject CALEClientCreateGattCharacteristic(JNIEnv *env, jobject bluetoothGatt, jbyteArray data);
398 * @param[in] env JNI interface pointer.
399 * @param[in] bluetoothGatt Gatt profile object.
400 * @param[in] characterUUID for make BluetoothGattCharacteristic object.
401 * @return Gatt Service.
403 jobject CALEClientGetGattService(JNIEnv *env, jobject bluetoothGatt, jstring characterUUID);
406 * get value from characteristic.
407 * @param[in] env JNI interface pointer.
408 * @param[in] characteristic Characteristic object.
409 * @return value in characteristic.
411 jbyteArray CALEClientGetValueFromCharacteristic(JNIEnv *env, jobject characteristic);
415 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
417 CAResult_t CALEClientCreateUUIDList();
420 * set UUID to descriptor.
421 * @param[in] env JNI interface pointer.
422 * @param[in] bluetoothGatt Gatt profile object.
423 * @param[in] characteristic Characteristic object.
424 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
426 CAResult_t CALEClientSetUUIDToDescriptor(JNIEnv *env, jobject bluetoothGatt,
427 jobject characteristic);
430 * add device object to scan device list.
431 * @param[in] env JNI interface pointer.
432 * @param[in] device bluetooth device object.
433 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
435 CAResult_t CALEClientAddScanDeviceToList(JNIEnv *env, jobject device);
438 * check whether the device exist in list or not.
439 * @param[in] env JNI interface pointer.
440 * @param[in] remoteAddress remote address.
441 * @return true or false.
443 bool CALEClientIsDeviceInScanDeviceList(JNIEnv *env, const char *remoteAddress);
446 * remove all devices in scan device list.
447 * @param[in] env JNI interface pointer.
448 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
450 CAResult_t CALEClientRemoveAllScanDevices(JNIEnv *env);
453 * remove target device in scan device list.
454 * @param[in] env JNI interface pointer.
455 * @param[in] remoteAddress remote address.
456 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
458 CAResult_t CALEClientRemoveDeviceInScanDeviceList(JNIEnv *env, jstring remoteAddress);
461 * add gatt object to gatt object list.
462 * @param[in] env JNI interface pointer.
463 * @param[in] gatt Gatt profile object.
464 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
466 CAResult_t CALEClientAddGattobjToList(JNIEnv *env, jobject gatt);
469 * check whether the gatt object exist in list or not.
470 * @param[in] env JNI interface pointer.
471 * @param[in] remoteAddress remote address.
472 * @return true or false.
474 bool CALEClientIsGattObjInList(JNIEnv *env, const char *remoteAddress);
477 * get the gatt object.
478 * @param[in] env JNI interface pointer.
479 * @param[in] remoteAddress remote address.
480 * @return gatt object.
482 jobject CALEClientGetGattObjInList(JNIEnv *env, const char* remoteAddress);
485 * remove all gatt objects in gatt object list.
486 * @param[in] env JNI interface pointer.
487 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
489 CAResult_t CALEClientRemoveAllGattObjs(JNIEnv *env);
492 * remove target device in gatt object list.
493 * @param[in] env JNI interface pointer.
494 * @param[in] gatt Gatt profile object.
495 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
497 CAResult_t CALEClientRemoveGattObj(JNIEnv *env, jobject gatt);
500 * remove gatt object of target device for address in gatt object list.
501 * @param[in] env JNI interface pointer.
502 * @param[in] gatt Gatt profile object.
503 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
505 CAResult_t CALEClientRemoveGattObjForAddr(JNIEnv *env, jstring addr);
508 * get ble address from Bluetooth device.
509 * @param[in] env JNI interface pointer.
510 * @param[in] bluetoothDevice Bluetooth device.
511 * @return ble address.
513 jstring CALEClientGetLEAddressFromBTDevice(JNIEnv *env, jobject bluetoothDevice);
516 * update new state information by Bluetooth device object.
517 * @param[in] env JNI interface pointer.
518 * @param[in] device Bluetooth device.
519 * @param[in] state_type state type.
520 * @param[in] target_state state index to update.
521 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
523 CAResult_t CALEClientUpdateDeviceStateWithBtDevice(JNIEnv *env,
526 uint16_t target_state);
529 * set flag into State List.
530 * @param[in] env JNI interface pointer.
531 * @param[in] jni_address remote address.
532 * @param[in] state_idx state index.
533 * @param[in] flag auto connect flag.
535 CAResult_t CALEClientSetFlagToState(JNIEnv *env, jstring jni_address,
536 jint state_idx, jboolean flag);
539 * get flag from State List.
540 * @param[in] env JNI interface pointer.
541 * @param[in] jni_address remote address.
542 * @param[in] state_idx state index.
543 * @return current flag;
545 jboolean CALEClientGetFlagFromState(JNIEnv *env, jstring jni_address, jint state_idx);
549 * @param[in] address the address of the remote device.
550 * @return mtu size negotiated from remote device.
552 uint16_t CALEClientGetMtuSize(const char* address);
555 * Reset values of device state for all of devices.
556 * this method has to be invoked when BT adapter is disabled.
557 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
559 CAResult_t CALEClientResetDeviceStateForAll();
562 * create scan device list.
564 void CALEClientCreateDeviceList();
567 * update the counter which data is sent to remote device.
568 * @param[in] env JNI interface pointer.
570 void CALEClientUpdateSendCnt(JNIEnv *env);
574 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
576 CAResult_t CALEClientInitGattMutexVaraibles();
581 void CALEClientTerminateGattMutexVariables();
584 * set send finish flag.
585 * @param[in] flag finish flag.
587 void CALEClientSetSendFinishFlag(bool flag);
590 * close the connection of the profile proxy to the Service.
591 * @param[in] env JNI interface pointer.
592 * @param[in] gatt gatt profile object.
593 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
595 CAResult_t CALEClientCloseProfileProxy(JNIEnv *env, jobject gatt);
598 * connect to GATT Server hosted by this device.
599 * @param[in] env JNI interface pointer.
600 * @param[in] bluetoothDevice bluetooth device object.
601 * @param[in] autoconnect connect as soon as the device becomes avaiable(true).
602 * @return gatt profile object
604 jobject CALEClientGattConnect(JNIEnv *env, jobject bluetoothDevice, jboolean autoconnect);
607 * connect to GATT Server hosted by this device directly.
608 * @param[in] env JNI interface pointer.
609 * @param[in] bluetoothDevice bluetooth device object.
610 * @param[in] autoconnect connect as soon as the device becomes avaiable(true).
611 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
613 CAResult_t CALEClientDirectConnect(JNIEnv *env, jobject bluetoothDevice, jboolean autoconnect);
616 * check connection status.
617 * @param[in] address the address of the remote device.
618 * @return true or false.
620 bool CALEClientIsConnected(const char* address);
623 * set new interval time and working count.
624 * @param[in] intervalTime interval time(Seconds).
625 * @param[in] workingCount working count for selected interval time.
626 * @param[in] nextScanningStep set next scanning state.
628 void CALEClientSetScanInterval(int32_t intervalTime, int32_t workingCount,
629 CALEScanState_t nextScanningStep);
632 * restart scanning with new interval time and working count.
633 * @param[in] intervalTime interval time(Seconds).
634 * @param[in] workingCount working count for selected interval time.
635 * @param[in] nextScanningStep set next scanning state.
637 void CALERestartScanWithInterval(int32_t intervalTime, int32_t workingCount,
638 CALEScanState_t nextScanningStep);
641 * start LE scanning logic with interval time and working count.
642 * @return ::CA_STATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
644 CAResult_t CALEClientStartScanWithInterval();
647 * stop LE scanning logic with interval time and cycle.
649 void CALEClientStopScanWithInterval();
652 * check if retry logic for connection routine has to be stopped or not.
653 * in case of error value including this method, connection routine has to be stopped.
654 * since there is no retry logic for this error reason in this client.
655 * @param state constant value of bluetoothgatt.
656 * @return true - waiting for background connection in BT platform.
657 * false - connection routine has to be stopped.
659 bool CALECheckConnectionStateValue(jint state);
665 #endif /* CA_LECLIENT_H_ */