ble_gattc_cache.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file ble_gattc_cache.h
5 *
6 * @brief BLE GATTC API
7 *
8 ****************************************************************************************
9 * @attention
10 #####Copyright (c) 2019 GOODIX
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15 * Redistributions of source code must retain the above copyright
16 notice, this list of conditions and the following disclaimer.
17 * Redistributions in binary form must reproduce the above copyright
18 notice, this list of conditions and the following disclaimer in the
19 documentation and/or other materials provided with the distribution.
20 * Neither the name of GOODIX nor the names of its contributors may be used
21 to endorse or promote products derived from this software without
22 specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35 *****************************************************************************************
36 */
37 /**
38 * @addtogroup BLE
39 * @{
40 */
41
42 /**
43 * @addtogroup BLE_GATT Generic Attribute Profile (GATT)
44 * @{
45 * @brief Definitions and prototypes for the GATT interface.
46 */
47
48 /**
49 @addtogroup BLE_GATTC_CACHE Generic Attribute Profile (GATT) Client Cache
50 @{
51 @brief Definitions and prototypes for the GATT client cache interfaces.
52 */
53
54 #ifndef _BLE_GATTC_CACHE_H_
55 #define _BLE_GATTC_CACHE_H_
56
57 #include "ble_error.h"
58 #include "ble_gatt.h"
59 #include "ble_att.h"
60 #include "ble_gapc.h"
61 #include <stdint.h>
62 #include <stdbool.h>
63
64 /** @addtogroup BLE_GATT_CACHE_DEFINES Defines
65 * @{ */
66 #define MAX_GATT_CACHE_NUM (0x10) /**< Max number of GATT CACHE. */
67 /** @} */
68
69 /** @addtogroup BLE_GATTC_CACHE_ENUMERATIONS Enumerations
70 * @{ */
71 /**
72 * @brief GATT Client Cache Attribute type IDs.
73 */
74 typedef enum
75 {
76 BLE_GATTC_CACHE_PRI_SERV, /**< Primary Service Declaration. */
77 BLE_GATTC_CACHE_SEC_SERV, /**< Secondary Service Declaration. */
78 BLE_GATTC_CACHE_INC_SRVC, /**< Included Service Declaration. */
79 BLE_GATTC_CACHE_ATTR_CHAR, /**< Characteristic Declaration. */
80 BLE_GATTC_CACHE_ATTR_DESC, /**< Characteristic Descriptor. */
81 } gattc_cache_attr_t;
82 /** @} */
83
84 /** @addtogroup BLE_GATTC_CACHE_STRUCTURES Structures
85 * @{ */
86
87 /**
88 * @brief GATTC Cache service attribute structure.
89 */
90 typedef struct
91 {
92 uint16_t start_hdl; /**< Start handle. */
93 uint16_t end_hdl; /**< End handle. */
94 uint8_t uuid_len; /**< Service UUID length. */
95 uint8_t *p_uuid; /**< Service UUID. */
96 } ble_gattc_cache_service_t;
97
98 /**
99 * @brief GATTC Cache include attribute structure.
100 */
101 typedef struct
102 {
103 uint16_t start_hdl; /**< Start handle. */
104 uint16_t end_hdl; /**< End handle. */
105 uint8_t uuid_len; /**< Service UUID length. */
106 uint8_t *p_uuid; /**< Service UUID. */
107 } ble_gattc_cache_include_t;
108
109 /**
110 * @brief GATTC Cache characteristic attribute structure.
111 */
112 typedef struct
113 {
114 uint8_t prop; /**< Properties. */
115 uint16_t handle_value; /**< Handle of the Characteristic Value. */
116 uint8_t uuid_len; /**< Characteristic UUID length. */
117 uint8_t *p_uuid; /**< Characteristic UUID. */
118 } ble_gattc_cache_char_t;
119
120 /**
121 * @brief GATTC Cache characteristic descriptor attribute structure.
122 */
123 typedef struct
124 {
125 uint8_t uuid_len; /**< Descriptor UUID length. */
126 uint8_t *p_uuid; /**< Descriptor UUID. */
127 } ble_gattc_cache_desc_t;
128
129 /**
130 * @brief GATTC cache attribute information uinon.
131 */
132 union attr_cache_info
133 {
134 ble_gattc_cache_service_t service_decl; /**< Service Declaration. */
135 ble_gattc_cache_include_t include_decl; /**< Include Declaration. */
136 ble_gattc_cache_char_t char_decl; /**< Characteristic Declaration. */
137 ble_gattc_cache_desc_t char_desc; /**< Characteristic Descriptor. */
138 };
139
140 /**
141 * @brief GATTC cache attribute information structure.
142 */
143 typedef struct
144 {
145 uint16_t handle; /**< Attribute Handle. */
146 uint8_t attr_type; /**< Attribute type. See @ref gattc_cache_attr_t. */
147 union attr_cache_info info; /**< Attribute cache information. */
148 } attr_cache_info_t;
149
150
151 /**
152 * @brief GATT caching list
153 */
154 typedef struct
155 {
156 uint8_t num; /**< Number of bonded device. */
157 ble_gap_bdaddr_t items[MAX_GATT_CACHE_NUM]; /**< GATT caching addr info. */
158 } gatt_cache_list_t;
159 /** @} */
160
161 /** @addtogroup BLE_GATTC_CACHE_FUNCTIONS Functions
162 * @{ */
163
164 /**
165 ****************************************************************************************
166 * @brief GATTC cache feature enable.
167 *
168 * @note Once enabling peer cache feature and caching data finished, the event @ref BLE_GATTC_EVT_CACHE_UPDATE will be called.
169 *
170 * @param[in] conn_idx: Current connection index.
171 *
172 * @retval SDK_SUCCESS: Successfully enable cache feature.
173 * @retval BLE_SDK_ERR_BAD_PARAM: Invalid parameter(s) supplied.
174 ****************************************************************************************
175 */
176 uint16_t ble_gattc_cache_enable(uint8_t conn_idx);
177
178 /**
179 ****************************************************************************************
180 * @brief GATTC cache feature disable.
181 *
182 * @note This function will delete caching data saved in nvds and disable cache feature.
183 *
184 * @param[in] conn_idx: Current connection index.
185 *
186 * @retval SDK_SUCCESS: Successfully enable cache feature.
187 * @retval BLE_SDK_ERR_BAD_PARAM: Invalid parameter(s) supplied.
188 ****************************************************************************************
189 */
190 uint16_t ble_gattc_cache_disable(uint8_t conn_idx);
191
192 /**
193 ****************************************************************************************
194 * @brief GATTC Get cache feature state.
195 *
196 * @note This function returns cache feature state.
197 *
198 * @param[in] conn_idx: Current connection index.
199 *
200 * @return true if cache feature enable, false otherwise.
201 ****************************************************************************************
202 */
203 bool ble_gattc_cache_feat_get(uint8_t conn_idx);
204
205 /**
206 ****************************************************************************************
207 * @brief GATTC cache data get.
208 *
209 * @note User should get cache data after gattc_cb_fun_t::app_gattc_cache_update_cb called.
210 * Real cache data length will be returned whether user provide enough buf or not.
211 * If cache data is NULL, p_cache_count will return cache data length.
212 *
213 *
214 * @param[in] conn_idx: Current connection index.
215 * @param[in] p_cache_data: The attribute cache buf.
216 * @param[out] p_cache_count: The count of attribute cache buf.
217 *
218 * @retval SDK_SUCCESS: Successfully get cache attributes info.
219 * @retval BLE_SDK_ERR_BAD_PARAM: Invalid parameter(s) supplied.
220 * @retval BLE_SDK_ERR_CACHE_NOT_ENABLE: Cache feature is not enabled.
221 * @retval BLE_SDK_ERR_BUSY: Caching data operation is not finished.
222 * @retval BLE_SDK_ERR_BUF_LEN_NOT_ENOUGH: The cache buf lenth is not enough.
223 ****************************************************************************************
224 */
225 uint16_t ble_gattc_cache_get(uint8_t conn_idx, attr_cache_info_t *p_cache_data, uint16_t *p_cache_count);
226
227 /**
228 ****************************************************************************************
229 * @brief Get the content of the whole GATT caching list.
230 *
231 * @param[in] p_cache_list: Pointer to the output caching list.
232 *
233 * @retval ::SDK_SUCCESS: Operation is successful.
234 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
235 ****************************************************************************************
236 */
237 uint16_t ble_gattc_cache_list_get(gatt_cache_list_t *p_cache_list);
238
239
240 /**
241 ****************************************************************************************
242 * @brief GATTC cache date delete on disconnection state.
243 *
244 * @param[in] p_peer_bd_addr: Identity address of peer device.
245 *
246 * @retval SDK_SUCCESS: Successfully delete cache in nvds.
247 * @retval BLE_SDK_ERR_BAD_PARAM: Invalid parameter(s) supplied.
248 * @retval BLE_SDK_ERR_LIST_ITEM_NOT_FOUND: Item not found in list.
249 ****************************************************************************************
250 */
251 uint16_t ble_gattc_cache_delete(ble_gap_bdaddr_t *p_peer_bd_addr);
252 /** @} */
253
254 #endif
255
256 /** @} */
257
258 /** @} */
259 /** @} */
260
gatt_cache_list_t::num
uint8_t num
Definition: ble_gattc_cache.h:156
ble_gattc_cache_desc_t::p_uuid
uint8_t * p_uuid
Definition: ble_gattc_cache.h:126
ble_gattc_cache_include_t
GATTC Cache include attribute structure.
Definition: ble_gattc_cache.h:102
ble_gattc_cache_service_t::start_hdl
uint16_t start_hdl
Definition: ble_gattc_cache.h:92
ble_gattc_cache_service_t
GATTC Cache service attribute structure.
Definition: ble_gattc_cache.h:91
attr_cache_info::include_decl
ble_gattc_cache_include_t include_decl
Definition: ble_gattc_cache.h:135
ble_gattc_cache_char_t::prop
uint8_t prop
Definition: ble_gattc_cache.h:114
ble_gap_bdaddr_t
The struct of broadcast address with broadcast type.
Definition: ble_gapc.h:320
ble_gattc_cache_char_t::p_uuid
uint8_t * p_uuid
Definition: ble_gattc_cache.h:117
ble_gattc_cache_feat_get
bool ble_gattc_cache_feat_get(uint8_t conn_idx)
GATTC Get cache feature state.
ble_gattc_cache_delete
uint16_t ble_gattc_cache_delete(ble_gap_bdaddr_t *p_peer_bd_addr)
GATTC cache date delete on disconnection state.
ble_gattc_cache_include_t::end_hdl
uint16_t end_hdl
Definition: ble_gattc_cache.h:104
BLE_GATTC_CACHE_ATTR_DESC
@ BLE_GATTC_CACHE_ATTR_DESC
Definition: ble_gattc_cache.h:80
ble_gattc_cache_include_t::uuid_len
uint8_t uuid_len
Definition: ble_gattc_cache.h:105
ble_gatt.h
BLE GATT.
ble_gattc_cache_include_t::p_uuid
uint8_t * p_uuid
Definition: ble_gattc_cache.h:106
gatt_cache_list_t
GATT caching list.
Definition: ble_gattc_cache.h:155
attr_cache_info::service_decl
ble_gattc_cache_service_t service_decl
Definition: ble_gattc_cache.h:134
ble_gattc_cache_desc_t::uuid_len
uint8_t uuid_len
Definition: ble_gattc_cache.h:125
ble_gattc_cache_enable
uint16_t ble_gattc_cache_enable(uint8_t conn_idx)
GATTC cache feature enable.
attr_cache_info
GATTC cache attribute information uinon.
Definition: ble_gattc_cache.h:133
BLE_GATTC_CACHE_INC_SRVC
@ BLE_GATTC_CACHE_INC_SRVC
Definition: ble_gattc_cache.h:78
ble_error.h
File that contains error codes.
ble_gapc.h
BLE GAPC API.
ble_gattc_cache_include_t::start_hdl
uint16_t start_hdl
Definition: ble_gattc_cache.h:103
ble_gattc_cache_disable
uint16_t ble_gattc_cache_disable(uint8_t conn_idx)
GATTC cache feature disable.
BLE_GATTC_CACHE_PRI_SERV
@ BLE_GATTC_CACHE_PRI_SERV
Definition: ble_gattc_cache.h:76
ble_gattc_cache_service_t::end_hdl
uint16_t end_hdl
Definition: ble_gattc_cache.h:93
gattc_cache_attr_t
gattc_cache_attr_t
GATT Client Cache Attribute type IDs.
Definition: ble_gattc_cache.h:75
ble_gattc_cache_char_t
GATTC Cache characteristic attribute structure.
Definition: ble_gattc_cache.h:113
MAX_GATT_CACHE_NUM
#define MAX_GATT_CACHE_NUM
Definition: ble_gattc_cache.h:66
ble_gattc_cache_get
uint16_t ble_gattc_cache_get(uint8_t conn_idx, attr_cache_info_t *p_cache_data, uint16_t *p_cache_count)
GATTC cache data get.
attr_cache_info_t
GATTC cache attribute information structure.
Definition: ble_gattc_cache.h:144
BLE_GATTC_CACHE_SEC_SERV
@ BLE_GATTC_CACHE_SEC_SERV
Definition: ble_gattc_cache.h:77
attr_cache_info_t::handle
uint16_t handle
Definition: ble_gattc_cache.h:145
ble_gattc_cache_char_t::uuid_len
uint8_t uuid_len
Definition: ble_gattc_cache.h:116
ble_gattc_cache_char_t::handle_value
uint16_t handle_value
Definition: ble_gattc_cache.h:115
attr_cache_info::char_decl
ble_gattc_cache_char_t char_decl
Definition: ble_gattc_cache.h:136
ble_gattc_cache_list_get
uint16_t ble_gattc_cache_list_get(gatt_cache_list_t *p_cache_list)
Get the content of the whole GATT caching list.
ble_att.h
Attribute Protocol.
ble_gattc_cache_desc_t
GATTC Cache characteristic descriptor attribute structure.
Definition: ble_gattc_cache.h:124
attr_cache_info::char_desc
ble_gattc_cache_desc_t char_desc
Definition: ble_gattc_cache.h:137
ble_gattc_cache_service_t::p_uuid
uint8_t * p_uuid
Definition: ble_gattc_cache.h:95
BLE_GATTC_CACHE_ATTR_CHAR
@ BLE_GATTC_CACHE_ATTR_CHAR
Definition: ble_gattc_cache.h:79
ble_gattc_cache_service_t::uuid_len
uint8_t uuid_len
Definition: ble_gattc_cache.h:94