• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2021 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef OHOS_BT_GATT_H
17 #define OHOS_BT_GATT_H
18 
19 #include "ohos_bt_def.h"
20 
21 /* e.g. Legacy SCAN_RSP to an ADV_IND, 0x1B
22    OHOS_BLE_EVT_TYPE_LEGACY_ADV | OHOS_BLE_EVT_TYPE_SCAN_RESPONSE | OHOS_BLE_EVT_TYPE_SCANNABLE_ADV | */
23 
24 #define OHOS_BLE_EVT_TYPE_CONNECTABLE_ADV 0x01 /* bit[0] */
25 #define OHOS_BLE_EVT_TYPE_SCANNABLE_ADV 0x02 /* bit[1] */
26 #define OHOS_BLE_EVT_TYPE_DIRECTED_ADV 0x04 /* bit[2] */
27 #define OHOS_BLE_EVT_TYPE_SCAN_RESPONSE 0x08 /* bit[3] */
28 #define OHOS_BLE_EVT_TYPE_LEGACY_ADV 0x10 /* bit[4] */
29 #define OHOS_BLE_EVT_TYPE_DATA_STATUS_COMPLETE 0x00 /* bit[6:5] , 0b00:Complete */
30 #define OHOS_BLE_EVT_TYPE_DATA_STATUS_INCOMPLETE 0x20 /* bit[6:5], 0b01:Incomplete, more data to come */
31 /* bit[6:5], 0b10:Incomplete,data truncated, no more to come */
32 #define OHOS_BLE_EVT_TYPE_DATA_STATUS_INCOMPLETE_TRUNCATED 0x40
33 
34 typedef enum {
35     OHOS_BLE_ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00,
36     OHOS_BLE_ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY = 0x01,
37     OHOS_BLE_ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST = 0x02,
38     OHOS_BLE_ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST = 0x03,
39 } BleAdvFilter;
40 
41 /* BLUETOOTH CORE SPECIFICATION Version 5.2|Vol4,Part E, "HCI_LE_Set_Advertising_Parameters" */
42 typedef enum {
43     OHOS_BLE_ADV_IND = 0x00, /* Connectable and scannable undirected advertising (default) */
44     OHOS_BLE_ADV_DIRECT_IND_HIGH = 0x01, /* Connectable high duty cycle directed advertising */
45     OHOS_BLE_ADV_SCAN_IND = 0x02, /* Scannable undirected advertising */
46     OHOS_BLE_ADV_NONCONN_IND = 0x03, /* Non connectable undirected advertising */
47     OHOS_BLE_ADV_DIRECT_IND_LOW  = 0x04, /* Connectable low duty cycle directed advertising */
48 } BleAdvType;
49 
50 /* Local IO capability, shall be the same value defined in HCI Specification. */
51 typedef enum {
52     OHOS_BLE_IO_CAP_OUT = 0x00, /* DisplayOnly */
53     OHOS_BLE_IO_CAP_IO, /* DisplayYesNo */
54     OHOS_BLE_IO_CAP_IN, /* KeyboardOnly */
55     OHOS_BLE_IO_CAP_NONE, /* NoInputNoOutput */
56     OHOS_BLE_IO_CAP_KBDISP, /* Keyboard display */
57 } BleIoCapMode;
58 
59 typedef enum {
60     OHOS_BLE_AUTH_NO_BOND = 0x00,
61     OHOS_BLE_AUTH_BOND,
62     OHOS_BLE_AUTH_REQ_MITM,
63     OHOS_BLE_AUTH_REQ_SC_ONLY,
64     OHOS_BLE_AUTH_REQ_SC_BOND,
65     OHOS_BLE_AUTH_REQ_SC_MITM,
66     OHOS_BLE_AUTH_REQ_SC_MITM_BOND
67 } BleAuthReqMode;
68 
69 typedef enum {
70     OHOS_BLE_FILTER_ACTION_ADD = 0x00,
71     OHOS_BLE_FILTER_ACTION_DELETE,
72     OHOS_BLE_FILTER_ACTION_CLEAR
73 } BleFilterActionType;
74 
75 typedef enum {
76     OHOS_BLE_ADV_ADDRESS_FILTER_MASK = 0x01,
77     OHOS_BLE_SERVICE_DATA_CHANGE_FILTER_MASK = 0x02,
78     OHOS_BLE_SERVICE_UUID_CHECK_MASK = 0x04,
79     OHOS_BLE_SERVICE_SOLICITATION_UUID_CHECK_MASK = 0x08,
80     OHOS_BLE_LOCAL_NAME_CHECK_MASK = 0x10,
81     OHOS_BLE_MANUFACTURER_DATA_CHECK_MASK = 0x20,
82     OHOS_BLE_SERVICE_DATA_CHECK_MASK = 0x40
83 } BleFilterSelectMask;
84 
85 typedef enum {
86     OHOS_BLE_FILTER_LOGIC_OR = 0x00,
87     OHOS_BLE_FILTER_LOGIC_AND
88 } BleFilterLogicType;
89 
90 typedef enum {
91     OHOS_BLE_FILTER_IMMEDIATE_MODE = 0x00,
92     OHOS_BLE_FILTER_ON_FOUND_MODE,
93     OHOS_BLE_FILTER_BATCHED_MODE
94 } BleFilterDeliveryMode;
95 
96 typedef enum {
97     OHOS_BLE_ADV_ADDRESS_FILTER = 0x00,
98     OHOS_BLE_SERVICE_DATA_CHANGE_FILTER,
99     OHOS_BLE_SERVICE_UUID_CHECK_FILTER,
100     OHOS_BLE_SERVICE_SOLICITATION_UUID_CHECK_FILTER,
101     OHOS_BLE_LOCAL_NAME_CHECK_FILTER,
102     OHOS_BLE_MANUFACTURER_DATA_CHECK_FILTER,
103     OHOS_BLE_SERVICE_DATA_CHECK_FILTER
104 } BleFilterSelectType;
105 
106 typedef enum {
107     OHOS_BLE_FILTER_PUBLIC_ADDR = 0x00,
108     OHOS_BLE_FILTER_RANDOM_ADDR
109 } BleFilterAddrType;
110 
111 /* Ble scan type */
112 typedef enum {
113     OHOS_BLE_SCAN_TYPE_PASSIVE = 0x00, /* Passive Scanning. No scan request PDUs shall be sent. */
114     OHOS_BLE_SCAN_TYPE_ACTIVE, /* Active Scanning. Scan request PDUs may be sent. */
115 } BleScanType;
116 
117 /* Scan filter policy, possible values of BleScanParams::scanFilterPolicy
118    0-Accept all advertisement packets except directed advertising packets not addressed to this device (default);
119    1-Accept only advertisement packets from devices where the advertiser's address is in the White list.
120    Directed advertising packets which are not addressed for this device shall be ignored;
121    2-Accept all undirected advertisement packets, and all directed advertising packets where the initiator address
122    is a resolvable private address, and all directed advertising packets addressed to this device;
123    3-Accept all undirected advertisement packets from devices where the advertiser's address is in the White list,
124    and all directed advertising packets where the initiator address is a resolvable private address, and all
125    directed advertising packets addressed to this device. */
126 typedef enum {
127     OHOS_BLE_SCAN_FILTER_POLICY_ACCEPT_ALL = 0x00,
128     OHOS_BLE_SCAN_FILTER_POLICY_ONLY_WHITE_LIST,
129     OHOS_BLE_SCAN_FILTER_POLICY_ACCEPT_ALL_AND_RPA,
130     OHOS_BLE_SCAN_FILTER_POLICY_ONLY_WHITE_LIST_AND_RPA
131 } BleScanFilterPolicy;
132 
133 /* Extended Advertising Event Type, possible values of BtScanResultData::eventType */
134 typedef enum {
135     OHOS_BLE_EVT_NON_CONNECTABLE_NON_SCANNABLE = 0x00, /* Extended Non-Connectable and Non-Scannable undirected */
136     OHOS_BLE_EVT_NON_CONNECTABLE_NON_SCANNABLE_DIRECTED = 0x04, /* Extended NonConnectable and NonScannable directed */
137     OHOS_BLE_EVT_CONNECTABLE = 0x01, /* Extended Connectable undirected */
138     OHOS_BLE_EVT_CONNECTABLE_DIRECTED = 0x05, /* Extended Connectable directed */
139     OHOS_BLE_EVT_SCANNABLE = 0x02, /* Extended Scannable undirected */
140     OHOS_BLE_EVT_SCANNABLE_DIRECTED = 0x06, /* Extended Scannable directed */
141 
142     OHOS_BLE_EVT_LEGACY_NON_CONNECTABLE = 0x10, /* Legacy Non-Connectable undirected, ADV_NONCONN_IND */
143     OHOS_BLE_EVT_LEGACY_SCANNABLE = 0x12, /* Legacy Scannable undirected, ADV_SCAN_IND */
144     OHOS_BLE_EVT_LEGACY_CONNECTABLE = 0x13, /* Legacy Connectable & Scannable undirected, ADV_IND */
145     OHOS_BLE_EVT_LEGACY_CONNECTABLE_DIRECTED = 0x15, /* Legacy Connectable directed, ADV_DIRECT_IND */
146     OHOS_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV_SCAN = 0x1A, /* Legacy SCAN_RSP to an ADV_SCAN_IND */
147     OHOS_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV = 0x1B, /* Legacy SCAN_RSP to an ADV_IND */
148 } BleScanResultEvtType;
149 
150 /* Extended Advertising Data Status, possible values of BtScanResultData::dataStatus */
151 typedef enum {
152     OHOS_BLE_DATA_COMPLETE = 0x00, /* Complete data or final trunck */
153     OHOS_BLE_DATA_INCOMPLETE_MORE_TO_COME = 0x01, /* Incomplete data, more data to come */
154     OHOS_BLE_DATA_INCOMPLETE_TRUNCATED = 0x02, /* Incomplete data, truncated, no more data to come */
155 } BleScanResultDataStatus;
156 
157 /* Addr type of scan result, possible values of BtScanResultData::addrType */
158 typedef enum {
159     OHOS_BLE_PUBLIC_DEVICE_ADDRESS = 0x00, /* Public Device Address */
160     OHOS_BLE_RANDOM_DEVICE_ADDRESS = 0x01, /* Random Device Address */
161     OHOS_BLE_PUBLIC_IDENTITY_ADDRESS = 0x02, /* Public Identity Address (corresponds to Resolved Private Address) */
162     /* Random (static) Identity Address (corresponds to Resolved Private Address) */
163     OHOS_BLE_RANDOM_STATIC_IDENTITY_ADDRESS = 0x03,
164     OHOS_BLE_UNRESOLVABLE_RANDOM_DEVICE_ADDRESS = 0xFE,
165     OHOS_BLE_NO_ADDRESS = 0xFF, /* No address provided (anonymous advertisement) */
166 } BleScanResultAddrType;
167 
168 /* adv data */
169 typedef struct {
170     unsigned short advLength;
171     char *advData; /* advertising data */
172     unsigned short scanRspLength;
173     char *scanRspData; /* scan response data */
174 } BleConfigAdvData;
175 
176 typedef struct {
177     /* Minimum advertising interval for undirected and low duty cycle directed advertising. [N * 0.625ms] */
178     int minInterval;
179     /* Maximum advertising interval for undirected and low duty cycle directed advertising. [N * 0.625ms] */
180     int maxInterval;
181     BleAdvType advType;
182     unsigned char ownAddrType; /* Ref. Core spec Version 5.2|Vol 4,Part E, HCI_LE_Set_Advertising_Parameters */
183     unsigned char peerAddrType; /* Ref. Core spec Version 5.2|Vol 4,Part E, HCI_LE_Set_Advertising_Parameters */
184     BdAddr peerAddr;
185     int channelMap; /* channel used bit map, bit[0:2]->[37,38,39]. e.g. 0x01-only 37 used, 0x07-all used */
186     BleAdvFilter advFilterPolicy;
187     int txPower; /* dbm */
188     int duration; /* duration for sending BLE ADV. [N * 10 ms] */
189 } BleAdvParams;
190 
191 /* used to add or delete a filter specification or clear a filter list for onchip filtering */
192 typedef struct {
193     unsigned char clientId; /* APP identifier */
194     unsigned char action; /* BleFilterActionType, [0->add,1->delte,2->clear] */
195     unsigned char filtIndex; /* Filter index 0 ~ max_filter */
196     unsigned int featureSelection; /* BleFilterSelectMask, Bit masks for the selected features */
197     unsigned int listLogicType; /* BleFilterLogicType, Logic operation for each feature selected in featureSelection */
198     unsigned char filtLogicType; /* BleFilterLogicType */
199     unsigned char rssiHighThres; /* [In dBm] ignore the advertiser if the signal is lower than rssiHighThres */
200     unsigned char rssiLowThres; /* Valid only if delivery_mode is on_found [in dBm] */
201     unsigned char deliveryMode; /* BleFilterDeliveryMode */
202     /* Time for firmware to linger and collect additional advertisements before reporting.
203        (Valid only if deliveryMode is on_found)[in milliseconds] */
204     unsigned int onFoundTimeout;
205     /* If an advertisement, after being found, is not seen contiguously for the lost_timeout period,
206        it will be reported lost. (Valid only if deliveryMode is on_found)[in milliseconds] */
207     unsigned int onLostTimeout;
208     /* If an advertisement in onFound lingers in firmware for the onfound_timeout duration,
209        it will collect a few advertisements and the count is checked. If the count exceeds onFoundTimeoutCnt,
210        it's reported OnFound, immediately thereafter. Valid only if deliveryMode is on_found [count] */
211     unsigned char onFoundTimeoutCnt;
212     /* Total number of advertisers to track per filter. Valid only if delivery_mode is on_found [count] */
213     unsigned int numOfTrackingEntries;
214 } BleAdvScanFilterParam;
215 
216 typedef struct {
217     unsigned char clientId; /* APP identifier */
218     unsigned char action; /* BleFilterActionType, [0->add, 1->delte, 2->clear] */
219     unsigned char filtType; /* BleFilterSelectType */
220     unsigned char filtIndex; /* filter index */
221     int manufacturerId; /* manufacturer id  */
222     int manufacturerIdMask; /* the mask of manufacturer id */
223     BtUuid *uuid; /* uuid, 128bit */
224     BtUuid *uuidMask; /* mask of 128bit uuid */
225     BdAddr *bdAddr; /* address, e.g. "AA:BB:CC:DD:EE:FF" */
226     unsigned char addrType; /* BleFilterAddrType, [0->public, 1->random] */
227     unsigned int dataLen; /* length of value */
228     char *data; /* value */
229     unsigned int maskLen; /* length of mask */
230     char mask; /* mask */
231 } BleAdvScanFilterCondition;
232 
233 /* BLE scan parameter */
234 typedef struct {
235     /* Time interval from when the Controller started its last scan until it begins the subsequent scan.
236        [N=0xXX] Time = N * 0.625 ms */
237     unsigned short scanInterval;
238     /* Duration of the scan on the primary advertising physical channel. [N=0xXX] Time = N * 0.625 ms */
239     unsigned short scanWindow;
240     unsigned char scanType; /* one of BleScanType, [0->Passive, 1->Active] */
241     unsigned char scanPhy; /* [0->LE 1M phy, 1->LE 2M phy, 2->LE Coded phy] */
242     unsigned char scanFilterPolicy; /* one of BleScanFilterPolicy */
243 } BleScanParams;
244 
245 typedef struct {
246     unsigned char *advData;
247     unsigned int advDataLen;
248     unsigned char *rspData;
249     unsigned int rspDataLen;
250 } StartAdvRawData;
251 
252 typedef struct {
253     unsigned char eventType; /* Advertising event type, one of BleScanResultEvtType */
254     unsigned char dataStatus; /* Data status, one of BleScanResultDataStatus */
255     unsigned char addrType; /* one of BleScanResultAddrType, except 0xFE */
256     BdAddr addr;
257     unsigned char primaryPhy; /* 0x01->LE 1M phy, 0x03->LE Coded phy */
258     unsigned char secondaryPhy; /* 0x00->No packets, 0x01->LE 1M phy, 0x02->LE 2M phy, 0x03->LE Coded phy */
259     /* Value of the Advertising SID subfield in the ADI field of the PDU or, for scan responses,
260        in the ADI field of the original scannable advertisement, 0xFF->No ADI field provided */
261     unsigned char advSid;
262     char txPower; /* Range: -127 to +20dBm, 0x7F->Tx Power information not available */
263     char rssi; /* Range: -127 to +20dBm, 0x7F->RSSI is not available */
264     /* Interval of the periodic advertising, Time = N * 1.25 ms, 0x0000->No periodic advertising */
265     unsigned short periodicAdvInterval;
266     unsigned char directAddrType; /* one of BleScanResultAddrType, except 0xFF */
267     BdAddr directAddr; /* TargetA address for directed advertising event only */
268     unsigned char advLen;
269     unsigned char *advData;
270 } BtScanResultData;
271 
272 /* Callback invoked when start adv operation has completed */
273 typedef void (*AdvEnableCallback)(int advId, int status);
274 
275 /* Callback invoked when stop adv operation has completed */
276 typedef void (*AdvDisableCallback)(int advId, int status);
277 
278 /* Callback invoked when adv instance data set operation has completed */
279 typedef void (*AdvDataCallback)(int advId, int status);
280 
281 /* Callback invoked when adv param update operation has completed */
282 typedef void (*AdvUpdateCallback)(int advId, int status);
283 
284 /* Callback invoked when security response operation has completed */
285 typedef void (*SecurityRespondCallback)(const BdAddr *bdAddr);
286 
287 /* Callback for scan results */
288 typedef void (*ScanResultCallback)(BtScanResultData *scanResultdata);
289 
290 /* Callback invoked when a scan filter enable/disable has completed */
291 typedef void (*ScanFilterStatusCallback)(int enable, int clientId, int status);
292 
293 /* Callback invoked when a scan filter configuration command has completed */
294 typedef void (*ScanFilterCfgCallback)(int action, int clientId, int status, int filtType, int avblSpace);
295 
296 /* Callback invoked when a scan filter param setup has completed */
297 typedef void (*ScanFilterParamCallback)(int action, int clientId, int status, int avblSpace);
298 
299 /* Callback invoked when scan parameter set has completed */
300 typedef void (*ScanParameterSetCompletedCallback)(int clientId, int status);
301 
302 typedef struct {
303     AdvEnableCallback advEnableCb; /* start adv */
304     AdvDisableCallback advDisableCb; /* stop adv */
305     AdvDataCallback advDataCb;
306     AdvUpdateCallback advUpdateCb; /* update adv */
307     SecurityRespondCallback securityRespondCb;
308     ScanResultCallback scanResultCb;
309     ScanFilterCfgCallback scanFilterCfgCb;
310     ScanFilterParamCallback scanFilterParamCb;
311     ScanFilterStatusCallback scanFilterStatusCb;
312     ScanParameterSetCompletedCallback scanParamSetCb;
313 } BtGattCallbacks;
314 
315 /*
316  * @brief Initialize the Bluetooth protocol stack
317  * @param[in] void
318  * @return 0-success, other-fail
319  */
320 int InitBtStack(void);
321 
322 /*
323  * @brief Bluetooth protocol stack enable
324  * @param[in] void
325  * @return 0-success, other-fail
326  */
327 int EnableBtStack(void);
328 
329 /*
330  * @brief Bluetooth protocol stack disable
331  * @param[in] void
332  * @return 0-success, other-fail
333  */
334 int DisableBtStack(void);
335 
336 /*
337  * @brief set this device's name for friendly
338  * @param[in] <name> device name
339  * @param[in] <len> length
340  * @return 0-success, other-fail
341  */
342 int SetDeviceName(const char *name, unsigned int len);
343 
344 /*
345  * @brief set advertising data
346  * @param[in] <advId> specified by upper layer
347  * @param[in] <data> adv data or scan response
348  * @return 0-success, other-fail
349  */
350 int BleSetAdvData(int advId, const BleConfigAdvData *data);
351 
352 /*
353  * @brief start ble advertising
354  * @param[in] <advId> specified by upper layer
355  * @param[in] <param> ble advertising param list
356  * @return 0-success, other-fail
357  */
358 int BleStartAdv(int advId, const BleAdvParams *param);
359 
360 /*
361  * @brief stop ble advertising
362  * @param[in] <advId> specified by upper layer
363  * @return 0-success, other-fail
364  */
365 int BleStopAdv(int advId);
366 
367 /*
368  * @Update the parameters as per spec, user manual specified values and restart multi ADV
369  * @param[in] <advId> specified by upper layer
370  * @param[in] <param> ble advertising param list
371  * @return 0-success, other-fail
372  */
373 int BleUpdateAdv(int advId, const BleAdvParams *param);
374 
375 /*
376  * @brief set security IO capability
377  * @param[in] <mode> BleIoCapMode
378  * @return 0-success, other-fail
379  */
380 int BleSetSecurityIoCap(BleIoCapMode mode);
381 
382 /*
383  * @brief set security authority
384  * @param[in] <mode> BleAuthReqMode
385  * @return 0-success, other-fail
386  */
387 int BleSetSecurityAuthReq(BleAuthReqMode mode);
388 
389 /*
390  * @brief The device accept or reject the connection initiator.
391  * @param[in] <bdAddr> initiator's address
392  * @param[in] <accept> 0-reject, 1-accept
393  * @return 0-success, other-fail
394  */
395 int BleGattSecurityRsp(BdAddr bdAddr, bool accept);
396 
397 /*
398  * @brief read bt mac address
399  * @param[in] <mac> mac addr
400  * @param[in] <len> addr length
401  * @return 0-success, other-fail
402  */
403 int ReadBtMacAddr(unsigned char *mac, unsigned int len);
404 
405 /*
406  * @brief Setup scan filter params
407  * @param[in] <param> BleAdvScanFilterParam
408  * @return 0-success, other-fail
409  */
410 int BleScanFilterParamSetup(BleAdvScanFilterParam *param);
411 
412 /*
413  * @brief Configure a scan filter condition
414  * @param[in] <param> BleAdvScanFilterCondition
415  * @return 0-success, other-fail
416  */
417 int BleScanFilterAddRemove(BleAdvScanFilterCondition *param);
418 
419 /*
420  * @brief Clear all scan filter conditions for specific filter index
421  * @param[in] <clientId> client Id
422  * @param[in] <filterIndex> filter index
423  * @return 0-success, other-fail
424  */
425 int BleScanFilterClear(int clientId, int filterIndex);
426 
427 /*
428  * @brief Enable / disable scan filter feature
429  * @param[in] <clientId> client Id
430  * @param[in] <enable> 0-disable, 1-enable
431  * @return 0-success, other-fail
432  */
433 int BleScanFilterEnable(int clientId, bool enable);
434 
435 /*
436  * @brief Set BLE scan parameters
437  * @param[in] <clientId> client Id
438  * @param[in] <param> BleScanParams, include scanInterval,scanWindow and so on.
439  * @return 0-success, other-fail
440  */
441 int BleSetScanParameters(int clientId, BleScanParams *param);
442 
443 /*
444  * @brief Start Ble scan
445  * @return 0-success, other-fail
446  */
447 int BleStartScan(void);
448 
449 /*
450  * @brief Stop Ble scan
451  * @return 0-success, other-fail
452  */
453 int BleStopScan(void);
454 
455 /*
456  * @brief Callback invoked for gatt common function
457  * @param[in] <BtGattCallbacks> Callback funcs
458  * @return 0-success, other-fail
459  */
460 int BleGattRegisterCallbacks(BtGattCallbacks *func);
461 
462 /*
463  * @brief Start advertising include set adv data.
464  * This API will not described in the development manual, only for Hilink.
465  * @return 0-success, other-fail
466  */
467 int BleStartAdvEx(int *advId, const StartAdvRawData rawData, BleAdvParams advParam);
468 #endif
469