Cordio Stack and Cordio Profiles  r2p3-02rel0
app_db.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief Application framework device database.
6  *
7  * Copyright (c) 2011-2018 Arm Ltd. All Rights Reserved.
8  * ARM Ltd. confidential and proprietary.
9  *
10  * IMPORTANT. Your use of this file is governed by a Software License Agreement
11  * ("Agreement") that must be accepted in order to download or otherwise receive a
12  * copy of this file. You may not use or copy this file for any purpose other than
13  * as described in the Agreement. If you do not agree to all of the terms of the
14  * Agreement do not use this file and delete all copies in your possession or control;
15  * if you do not have a copy of the Agreement, you must contact ARM Ltd. prior
16  * to any use, copying or further distribution of this software.
17  */
18 /*************************************************************************************************/
19 #ifndef APP_DB_H
20 #define APP_DB_H
21 
22 #include "wsf_os.h"
23 #include "dm_api.h"
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /*! \addtogroup APP_FRAMEWORK_DB_API
30  * \{ */
31 
32 /**************************************************************************************************
33  Macros
34 **************************************************************************************************/
35 
36 /*! \brief No device database record handle */
37 #define APP_DB_HDL_NONE NULL
38 
39 /**************************************************************************************************
40  Data Types
41 **************************************************************************************************/
42 
43 /*! \brief Device database record handle type */
44 typedef void *appDbHdl_t;
45 
46 /**************************************************************************************************
47  Function Declarations
48 **************************************************************************************************/
49 
50 /** \name App Database
51  * Store known device and security information.
52  */
53 /**@{*/
54 
55 /*************************************************************************************************/
56 /*!
57  * \brief Initialize the device database.
58  *
59  * \return None.
60  */
61 /*************************************************************************************************/
62 void AppDbInit(void);
63 
64 /*************************************************************************************************/
65 /*!
66  * \brief Create a new device database record.
67  *
68  * \param addrType Address type.
69  * \param pAddr Peer device address.
70  *
71  * \return Database record handle.
72  */
73 /*************************************************************************************************/
74 appDbHdl_t AppDbNewRecord(uint8_t addrType, uint8_t *pAddr);
75 
76 /*************************************************************************************************/
77 /*!
78 * \brief Get next device database record for a given database record. For the first database
79 * record, the function should be called with 'hdl' set to 'APP_DB_HDL_NONE'.
80 *
81 * \param hdl Database record handle.
82 *
83 * \return Next database record handle found. APP_DB_HDL_NONE, otherwise.
84 */
85 /*************************************************************************************************/
86 appDbHdl_t AppDbGetNextRecord(appDbHdl_t hdl);
87 
88 /*************************************************************************************************/
89 /*!
90  * \brief Delete a new device database record.
91  *
92  * \param hdl Database record handle.
93  *
94  * \return None.
95  */
96 /*************************************************************************************************/
97 void AppDbDeleteRecord(appDbHdl_t hdl);
98 
99 /*************************************************************************************************/
100 /*!
101  * \brief Validate a new device database record. This function is called when pairing is
102  * successful and the devices are bonded.
103  *
104  * \param hdl Database record handle.
105  * \param keyMask Bitmask of keys to validate.
106  *
107  * \return None.
108  */
109 /*************************************************************************************************/
110 void AppDbValidateRecord(appDbHdl_t hdl, uint8_t keyMask);
111 
112 /*************************************************************************************************/
113 /*!
114  * \brief Check if a record has been validated. If it has not, delete it. This function
115  * is typically called when the connection is closed.
116  *
117  * \param hdl Database record handle.
118  *
119  * \return None.
120  */
121 /*************************************************************************************************/
122 void AppDbCheckValidRecord(appDbHdl_t hdl);
123 
124 /*************************************************************************************************/
125 /*!
126 * \brief Check if a database record is in use.
127 
128 * \param hdl Database record handle.
129 *
130 * \return TURE if record in use. FALSE, otherwise.
131 */
132 /*************************************************************************************************/
133 bool_t AppDbRecordInUse(appDbHdl_t hdl);
134 
135 /*************************************************************************************************/
136 /*!
137  * \brief Check if there is a stored bond with any device.
138  *
139  * \return TRUE if a bonded device is found, FALSE otherwise.
140  */
141 /*************************************************************************************************/
143 
144 /*************************************************************************************************/
145 /*!
146  * \brief Delete all database records.
147  *
148  * \return None.
149  */
150 /*************************************************************************************************/
151 void AppDbDeleteAllRecords(void);
152 
153 /*************************************************************************************************/
154 /*!
155  * \brief Find a device database record by peer address.
156  *
157  * \param addrType Address type.
158  * \param pAddr Peer device address.
159  *
160  * \return Database record handle or APP_DB_HDL_NONE if not found.
161  */
162 /*************************************************************************************************/
163 appDbHdl_t AppDbFindByAddr(uint8_t addrType, uint8_t *pAddr);
164 
165 /*************************************************************************************************/
166 /*!
167  * \brief Find a device database record from data in an LTK request.
168  *
169  * \param encDiversifier Encryption diversifier associated with key.
170  * \param pRandNum Pointer to random number associated with key.
171  *
172  * \return Database record handle or APP_DB_HDL_NONE if not found.
173  */
174 /*************************************************************************************************/
175 appDbHdl_t AppDbFindByLtkReq(uint16_t encDiversifier, uint8_t *pRandNum);
176 
177 /*************************************************************************************************/
178 /*!
179  * \brief Get the device database record handle associated with an open connection.
180  *
181  * \param connId Connection identifier.
182  *
183  * \return Database record handle or APP_DB_HDL_NONE.
184  */
185 /*************************************************************************************************/
186 appDbHdl_t AppDbGetHdl(dmConnId_t connId);
187 
188 /*************************************************************************************************/
189 /*!
190  * \brief Get a key from a device database record.
191  *
192  * \param hdl Database record handle.
193  * \param type Type of key to get.
194  * \param pSecLevel If the key is valid, returns the security level of the key.
195  *
196  * \return Pointer to the key if the key is valid or NULL if not valid.
197  */
198 /*************************************************************************************************/
199 dmSecKey_t *AppDbGetKey(appDbHdl_t hdl, uint8_t type, uint8_t *pSecLevel);
200 
201 /*************************************************************************************************/
202 /*!
203  * \brief Set a key in a device database record.
204  *
205  * \param hdl Database record handle.
206  * \param pKey Key data.
207  *
208  * \return None.
209  */
210 /*************************************************************************************************/
211 void AppDbSetKey(appDbHdl_t hdl, dmSecKeyIndEvt_t *pKey);
212 
213 /*************************************************************************************************/
214 /*!
215  * \brief Get the client characteristic configuration descriptor table.
216  *
217  * \param hdl Database record handle.
218  *
219  * \return Pointer to client characteristic configuration descriptor table.
220  */
221 /*************************************************************************************************/
222 uint16_t *AppDbGetCccTbl(appDbHdl_t hdl);
223 
224 /*************************************************************************************************/
225 /*!
226  * \brief Set a value in the client characteristic configuration table.
227  *
228  * \param hdl Database record handle.
229  * \param idx Table index.
230  * \param value Client characteristic configuration value.
231  *
232  * \return None.
233  */
234 /*************************************************************************************************/
235 void AppDbSetCccTblValue(appDbHdl_t hdl, uint16_t idx, uint16_t value);
236 
237 /*************************************************************************************************/
238 /*!
239  * \brief Get the discovery status.
240  *
241  * \param hdl Database record handle.
242  *
243  * \return Discovery status.
244  */
245 /*************************************************************************************************/
246 uint8_t AppDbGetDiscStatus(appDbHdl_t hdl);
247 
248 /*************************************************************************************************/
249 /*!
250  * \brief Set the discovery status.
251  *
252  * \param hdl Database record handle.
253  * \param status Discovery status.
254  *
255  * \return None.
256  */
257 /*************************************************************************************************/
258 void AppDbSetDiscStatus(appDbHdl_t hdl, uint8_t status);
259 
260 /*************************************************************************************************/
261 /*!
262  * \brief Get the cached handle list.
263  *
264  * \param hdl Database record handle.
265  *
266  * \return Pointer to handle list.
267  */
268 /*************************************************************************************************/
269 uint16_t *AppDbGetHdlList(appDbHdl_t hdl);
270 
271 /*************************************************************************************************/
272 /*!
273  * \brief Set the cached handle list.
274  *
275  * \param hdl Database record handle.
276  * \param pHdlList Pointer to handle list.
277  *
278  * \return None.
279  */
280 /*************************************************************************************************/
281 void AppDbSetHdlList(appDbHdl_t hdl, uint16_t *pHdlList);
282 
283 /*************************************************************************************************/
284 /*!
285  * \brief Get the device name.
286  *
287  * \param pLen Returned device name length.
288  *
289  * \return Pointer to UTF-8 string containing the device name or NULL if not set.
290  */
291 /*************************************************************************************************/
292 char *AppDbGetDevName(uint8_t *pLen);
293 
294 /*************************************************************************************************/
295 /*!
296  * \brief Set the device name.
297  *
298  * \param len Device name length.
299  * \param pStr UTF-8 string containing the device name.
300  *
301  * \return None.
302  */
303 /*************************************************************************************************/
304 void AppDbSetDevName(uint8_t len, char *pStr);
305 
306 /*************************************************************************************************/
307 /*!
308 * \brief Get address resolution attribute value read from a peer device.
309 *
310 * \param hdl Database record handle.
311 *
312 * \return TRUE if address resolution is supported in peer device. FALSE, otherwise.
313 */
314 /*************************************************************************************************/
315 bool_t AppDbGetPeerAddrRes(appDbHdl_t hdl);
316 
317 /*************************************************************************************************/
318 /*!
319 * \brief Set address resolution attribute value for a peer device.
320 *
321 * \param hdl Database record handle.
322 * \param addrRes Peer address resolution attribue value.
323 *
324 * \return None.
325 */
326 /*************************************************************************************************/
327 void AppDbSetPeerAddrRes(appDbHdl_t hdl, uint8_t addrRes);
328 
329 /*************************************************************************************************/
330 /*!
331 * \brief Get sign counter for a peer device.
332 *
333 * \param hdl Database record handle.
334 *
335 * \return Sign counter for peer device.
336 */
337 /*************************************************************************************************/
338 uint32_t AppDbGetPeerSignCounter(appDbHdl_t hdl);
339 
340 /*************************************************************************************************/
341 /*!
342 * \brief Set sign counter for a peer device.
343 *
344 * \param hdl Database record handle.
345 * \param signCounter Sign counter for peer device.
346 *
347 * \return None.
348 */
349 /*************************************************************************************************/
350 void AppDbSetPeerSignCounter(appDbHdl_t hdl, uint32_t signCounter);
351 
352 /*************************************************************************************************/
353 /*!
354  * \brief Get the peer device added to resolving list flag value.
355  *
356  * \param hdl Database record handle.
357  *
358  * \return TRUE if peer device's been added to resolving list. FALSE, otherwise.
359  */
360 /*************************************************************************************************/
361 bool_t AppDbGetPeerAddedToRl(appDbHdl_t hdl);
362 
363 /*************************************************************************************************/
364 /*!
365  * \brief Set the peer device added to resolving list flag to a given value.
366  *
367  * \param hdl Database record handle.
368  * \param peerAddedToRl Peer device added to resolving list flag value.
369  *
370  * \return None.
371  */
372 /*************************************************************************************************/
373 void AppDbSetPeerAddedToRl(appDbHdl_t hdl, bool_t peerAddedToRl);
374 
375 /*************************************************************************************************/
376 /*!
377  * \brief Get resolvable private address only attribute present flag for a peer device.
378  *
379  * \param hdl Database record handle.
380  *
381  * \return TRUE if RPA Only attribute is present on peer device. FALSE, otherwise.
382  */
383 /*************************************************************************************************/
384 bool_t AppDbGetPeerRpao(appDbHdl_t hdl);
385 
386 /*************************************************************************************************/
387 /*!
388  * \brief Set resolvable private address only attribute present flag for a peer device.
389  *
390  * \param hdl Database record handle.
391  * \param peerRpao Resolvable private address only attribute present flag.
392  *
393  * \return None.
394  */
395 /*************************************************************************************************/
396 void AppDbSetPeerRpao(appDbHdl_t hdl, bool_t peerRpao);
397 
398 /**@}*/
399 
400 /*! \} */ /*! APP_FRAMEWORK_DB_API */
401 
402 #ifdef __cplusplus
403 };
404 #endif
405 
406 #endif /* APP_DB_H */
char * AppDbGetDevName(uint8_t *pLen)
Get the device name.
void AppDbValidateRecord(appDbHdl_t hdl, uint8_t keyMask)
Validate a new device database record. This function is called when pairing is successful and the dev...
uint8_t dmConnId_t
Connection identifier.
Definition: dm_api.h:501
void AppDbSetDiscStatus(appDbHdl_t hdl, uint8_t status)
Set the discovery status.
appDbHdl_t AppDbNewRecord(uint8_t addrType, uint8_t *pAddr)
Create a new device database record.
void * appDbHdl_t
Device database record handle type.
Definition: app_db.h:44
bool_t AppDbGetPeerRpao(appDbHdl_t hdl)
Get resolvable private address only attribute present flag for a peer device.
void AppDbSetDevName(uint8_t len, char *pStr)
Set the device name.
appDbHdl_t AppDbFindByLtkReq(uint16_t encDiversifier, uint8_t *pRandNum)
Find a device database record from data in an LTK request.
void AppDbDeleteAllRecords(void)
Delete all database records.
void AppDbSetCccTblValue(appDbHdl_t hdl, uint16_t idx, uint16_t value)
Set a value in the client characteristic configuration table.
uint8_t bool_t
Boolean data type.
Definition: wsf_types.h:78
void AppDbSetPeerAddedToRl(appDbHdl_t hdl, bool_t peerAddedToRl)
Set the peer device added to resolving list flag to a given value.
bool_t AppDbGetPeerAddedToRl(appDbHdl_t hdl)
Get the peer device added to resolving list flag value.
uint8_t AppDbGetDiscStatus(appDbHdl_t hdl)
Get the discovery status.
appDbHdl_t AppDbGetHdl(dmConnId_t connId)
Get the device database record handle associated with an open connection.
void AppDbSetKey(appDbHdl_t hdl, dmSecKeyIndEvt_t *pKey)
Set a key in a device database record.
Data type for DM_SEC_KEY_IND.
Definition: dm_api.h:582
bool_t AppDbRecordInUse(appDbHdl_t hdl)
Check if a database record is in use.
uint32_t AppDbGetPeerSignCounter(appDbHdl_t hdl)
Get sign counter for a peer device.
uint16_t * AppDbGetHdlList(appDbHdl_t hdl)
Get the cached handle list.
appDbHdl_t AppDbGetNextRecord(appDbHdl_t hdl)
Get next device database record for a given database record. For the first database record...
dmSecKey_t * AppDbGetKey(appDbHdl_t hdl, uint8_t type, uint8_t *pSecLevel)
Get a key from a device database record.
void AppDbCheckValidRecord(appDbHdl_t hdl)
Check if a record has been validated. If it has not, delete it. This function is typically called whe...
unsigned long uint32_t
Unsigned 32-bit value.
Definition: wsf_types.h:71
void AppDbSetPeerAddrRes(appDbHdl_t hdl, uint8_t addrRes)
Set address resolution attribute value for a peer device.
void AppDbInit(void)
Initialize the device database.
bool_t AppDbCheckBonded(void)
Check if there is a stored bond with any device.
Device Manager subsystem API.
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
bool_t AppDbGetPeerAddrRes(appDbHdl_t hdl)
Get address resolution attribute value read from a peer device.
void AppDbSetHdlList(appDbHdl_t hdl, uint16_t *pHdlList)
Set the cached handle list.
uint16_t * AppDbGetCccTbl(appDbHdl_t hdl)
Get the client characteristic configuration descriptor table.
void AppDbSetPeerRpao(appDbHdl_t hdl, bool_t peerRpao)
Set resolvable private address only attribute present flag for a peer device.
Union of key types.
Definition: dm_api.h:535
void AppDbDeleteRecord(appDbHdl_t hdl)
Delete a new device database record.
Software foundation OS API.
void AppDbSetPeerSignCounter(appDbHdl_t hdl, uint32_t signCounter)
Set sign counter for a peer device.
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63
appDbHdl_t AppDbFindByAddr(uint8_t addrType, uint8_t *pAddr)
Find a device database record by peer address.