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. */
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. */
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. */
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. */
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. */
128 
129 /**
130  * @brief GATTC cache attribute information uinon.
131  */
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. */
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. */
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  */
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:304
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