ble_gatts.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file ble_gatts.h
5 *
6 * @brief BLE GATTS 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 /**
39 * @addtogroup BLE
40 * @{
41 */
42
43 /**
44 * @addtogroup BLE_GATT Generic Attribute Profile (GATT)
45 * @{
46 * @brief Definitions and prototypes for the GATT interface.
47 */
48
49 /**
50 @addtogroup BLE_SDK_GATTS Generic Attribute Profile (GATT) Server
51 @{
52 @brief Definitions and prototypes for the GATT server interface.
53 */
54
55
56 #ifndef __BLE_GATTS_H__
57 #define __BLE_GATTS_H__
58
59 #include "ble_error.h"
60 #include "ble_att.h"
61 #include "ble_gatt.h"
62
63 #include <stdint.h>
64
65 /** @addtogroup BLE_GATTS_DEFINES Defines
66 * @{ */
67
68 /** @defgroup BLE_GATTS_MAX_INC_SRVC_NUM Max Number of Included Services
69 * @{ */
70 #define MAX_INC_SRVC_NUM (5) /**< The max number of Included Services a Primary/Secondary service can have. Used by @ref gatts_create_db_t. */
71 /** @} */
72
73 /** @defgroup BLE_GATTS_ATTR_PERM_BIT Attribute Permission Bit
74 * @{ */
75 #define BROADCAST (0x01) /**< In one byte, bit0 means: Broadcast bit. Used by @ref BROADCAST_ENABLE. */
76 #define READ (0x02) /**< In one byte, bit1 means: Read bit. Used by @ref READ_PERM_UNSEC, @ref READ_PERM */
77 #define WRITE_CMD (0x04) /**< In one byte, bit2 means: Write_cmd bit. Used by @ref WRITE_CMD_PERM_UNSEC, @ref WRITE_CMD_PERM. */
78 #define WRITE_REQ (0x08) /**< In one byte, bit3 means: Write_req bit. Used by @ref WRITE_REQ_PERM_UNSEC, @ref WRITE_REQ_PERM. */
79 #define NOTIFY (0x10) /**< In one byte, bit4 means: Notify bit. Used by @ref NOTIFY_PERM_UNSEC, @ref NOTIFY_PERM. */
80 #define INDICATE (0x20) /**< In one byte, bit5 means: Indicate bit. Used by @ref INDICATE_PERM_UNSEC, @ref INDICATE_PERM */
81 #define WRITE_SIGNED (0x40) /**< In one byte, bit6 means: Write_signed bit. Used by @ref WRITE_SIGNED_PERM_UNSEC, @ref WRITE_SIGNED_PERM. */
82 #define EXT_PROP (0x80) /**< In one byte, bit7 means: Ext_property bit. Used by @ref EXT_PROP_ENABLE. */
83 /** @} */
84
85 /** @defgroup BLE_GATTS_ATTR_PERM_POS Attribute Permission Value Position
86 * @{ */
87 #define READ_POS (0x00) /**< Bit position of read permission. Used by @ref READ_PERM. */
88 #define WRITE_POS (0x02) /**< Bit position of write permission. Used by @ref WRITE_CMD_PERM, @ref WRITE_REQ_PERM, @ref WRITE_SIGNED_PERM. */
89 #define INDICATE_POS (0x04) /**< Bit position of indicate bit. Used by @ref INDICATE_PERM. */
90 #define NOTIFY_POS (0x06) /**< Bit position of notify bit. Used by @ref NOTIFY_PERM. */
91 /** @} */
92
93 /** @defgroup BLE_GATTS_SEC_LEVEL Attribute and Service Access Rights
94 * @{ */
95
96 #define NOAUTH (0x00) /**< LE security mode 1, level 1. Link does not need to be encrypted or authenticated.
97 Parameter of @ref SRVC_PERM, @ref READ_PERM, @ref WRITE_REQ_PERM, @ref WRITE_CMD_PERM, @ref WRITE_SIGNED_PERM, @ref INDICATE_PERM, @ref NOTIFY_PERM. */
98 #define UNAUTH (0x01) /**< LE security mode 1, level 2. Link needs to be encrypted, but not to be authenticated.
99 Parameter of @ref SRVC_PERM, @ref READ_PERM, @ref WRITE_REQ_PERM, @ref WRITE_CMD_PERM, @ref WRITE_SIGNED_PERM, @ref INDICATE_PERM, @ref NOTIFY_PERM. */
100 #define AUTH (0x02) /**< LE security mode 1, level 3. Link needs to be encrypted and authenticated (MITM).
101 Parameter of @ref SRVC_PERM, @ref READ_PERM, @ref WRITE_REQ_PERM, @ref WRITE_CMD_PERM, @ref WRITE_SIGNED_PERM, @ref INDICATE_PERM, @ref NOTIFY_PERM. */
102 #define SEC_CON (0x03) /**< LE security mode 1, level 4. Link needs to be encrypted and authenticated (secure connections).
103 Parameter of @ref SRVC_PERM, @ref READ_PERM, @ref WRITE_REQ_PERM, @ref WRITE_CMD_PERM, @ref WRITE_SIGNED_PERM, @ref INDICATE_PERM, @ref NOTIFY_PERM. */
104 /** @} */
105
106 /** @defgroup BLE_GATTS_SEC_LEVEL_MASK Attribute and Service Security Level Mask
107 * @{ */
108 #define SEC_LEVEL_MASK (0x03) /**< Security level mask.
109 Used by @ref SRVC_PERM, @ref READ_PERM, @ref WRITE_REQ_PERM, @ref WRITE_CMD_PERM, @ref WRITE_SIGNED_PERM, @ref INDICATE_PERM, @ref NOTIFY_PERM. */
110 /** @} */
111
112 /** @defgroup BLE_GATTS_UUID_TYPE Attribute and Service UUID Type
113 * @{ */
114 #define UUID_TYPE_16 (0x00) /**< 16-bit UUID length. Parameter of @ref SRVC_UUID_TYPE_SET, @ref ATT_UUID_TYPE_SET. */
115 #define UUID_TYPE_128 (0x02) /**< 128-bit UUID length. Parameter of @ref SRVC_UUID_TYPE_SET, @ref ATT_UUID_TYPE_SET. */
116 /** @} */
117
118 /**
119 * Service permissions
120 *
121 * | 7 | 6--5 | 4 | 3--2 | 1 | 0 |
122 * |----|--------|----|--------|----|----|
123 * |SEC |UUID_LEN|DIS | AUTH |EKS | MI |
124 *
125 * Bit [0] : Service is multi-instantiated (0 = not support; 1 = support) \n
126 * Bit [1] : Encryption key size must be 16 bytes (0 = not need; 1 = need) \n
127 * Bit [2-3]: Service permission (0 = NOAUTH; 1 = UNAUTH; 2 = AUTH; 3 = SEC_CON) \n
128 * Bit [4] : Disable the service (0 = no; 1 = yes) \n
129 * Bit [5-6]: UUID Length Type (0 = 16 bits; 2 = 128 bits) \n
130 * Bit [7] : Secondary Service (0 = Primary Service; 1 = Secondary Service) \n
131 */
132
133 /** @defgroup BLE_GATTS_SRVC_PERM Service Permission
134 * @{ */
135 #define SRVC_SECONDARY_SET (0x80) /**< Secondary service set. */
136 #define SRVC_UUID_TYPE_SET(uuid_len) ((uuid_len) << 5) /**< Service UUID length set. See @ref BLE_GATTS_UUID_TYPE. */
137 #define SRVC_DISABLE (0x10) /**< Service disable. */
138 #define SRVC_PERM(sec_level) (((sec_level) & SEC_LEVEL_MASK) << 2) /**< Service permission authentication. See @ref BLE_GATTS_SEC_LEVEL. */
139 #define SRVC_ENCRP_KEY_SIZE_16 (0x02) /**< 16 bytes service encryption key size . */
140 #define SRVC_MULTI_ENABLE (0x01) /**< Service is multi-instantiated. */
141 /** @} */
142
143 /**
144 * Attribute permission
145 *
146 * | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7--6 | 5--4 | 3--2 | 1--0 |
147 * |----|----|----|----|----|----|----|----|--------|--------|--------|--------|
148 * |EXT | WS | I | N | WR | WC | RD | B | NP | IP | WP | RP |
149 *
150 * Bit [0-1]: Read permission (0 = NOAUTH; 1 = UNAUTH; 2 = AUTH; 3 = SEC_CON) \n
151 * Bit [2-3]: Write permission (0 = NOAUTH; 1 = UNAUTH; 2 = AUTH; 3 = SEC_CON) \n
152 * Bit [4-5]: Indicate permission (0 = NOAUTH; 1 = UNAUTH; 2 = AUTH; 3 = SEC_CON) \n
153 * Bit [6-7]: Notify permission (0 = NOAUTH; 1 = UNAUTH; 2 = AUTH; 3 = SEC_CON) \n
154 *
155 * Bit [8] : Broadcast permission \n
156 * Bit [9] : Read accepted \n
157 * Bit [10] : Write Command accepted \n
158 * Bit [11] : Write Request accepted \n
159 * Bit [12] : Notify accepted \n
160 * Bit [13] : Indicate accepted \n
161 * Bit [14] : Write Signed accepted \n
162 * Bit [15] : Extended Properties present \n
163 */
164
165 /** @defgroup BLE_GATTS_ATTR_PERM Attribute Permission
166 * @{ */
167 #define READ_PERM_UNSEC (READ << 8) /**< Default Read permission. */
168 #define READ_PERM(sec_level) (READ << 8 | (((sec_level) & SEC_LEVEL_MASK) << READ_POS)) /**< Read permission set.
169 See @ref BLE_GATTS_SEC_LEVEL. */
170 #define WRITE_REQ_PERM_UNSEC (WRITE_REQ << 8) /**< Default Write Permission. */
171 #define WRITE_REQ_PERM(sec_level) (WRITE_REQ << 8 | (((sec_level) & SEC_LEVEL_MASK) << WRITE_POS)) /**< Write permission set.
172 See @ref BLE_GATTS_SEC_LEVEL. */
173 #define WRITE_CMD_PERM_UNSEC (WRITE_CMD << 8) /**< Default Write without Response Permission. */
174 #define WRITE_CMD_PERM(sec_level) (WRITE_CMD << 8 | (((sec_level) & SEC_LEVEL_MASK) << WRITE_POS)) /**< Write without Response permission set.
175 See @ref BLE_GATTS_SEC_LEVEL. */
176 #define WRITE_SIGNED_PERM_UNSEC (WRITE_SIGNED << 8) /**< Default Authenticated Signed Write Permission. */
177 #define WRITE_SIGNED_PERM(sec_level) (WRITE_SIGNED << 8 | (((sec_level) & SEC_LEVEL_MASK) << WRITE_POS)) /**< Authenticated Signed Write permission set.
178 See @ref BLE_GATTS_SEC_LEVEL. */
179 #define INDICATE_PERM_UNSEC (INDICATE << 8) /**< Default Indicate Permission. */
180 #define INDICATE_PERM(sec_level) (INDICATE << 8 | (((sec_level) & SEC_LEVEL_MASK) << INDICATE_POS)) /**< Indicate permission set.
181 See @ref BLE_GATTS_SEC_LEVEL. */
182 #define NOTIFY_PERM_UNSEC (NOTIFY << 8) /**< Default Notify Permission. */
183 #define NOTIFY_PERM(sec_level) (NOTIFY << 8 | (((sec_level) & SEC_LEVEL_MASK) << NOTIFY_POS)) /**< Notify permission set.
184 See @ref BLE_GATTS_SEC_LEVEL. */
185 #define BROADCAST_ENABLE (BROADCAST << 8) /**< Broadcast enable. */
186 #define EXT_PROP_ENABLE (EXT_PROP << 8) /**< Extended Properties enable. */
187 /** @} */
188
189 /**
190 * Attribute extend permission
191 *
192 * | 15 | 14--13 | 12 | 11--0 |
193 * |----|---------|----|-----------------------------------------------------------|
194 * | VL |UUID_LEN |EKS | RESERVED |
195 *
196 * Bit [0-11] : Reserved \n
197 * Bit [12] : Encryption key size must be 16 bytes (0 = not need; 1 = need) \n
198 * Bit [14-13]: UUID length type (0 = 16 bits; 2 = 128 bits) \n
199 * Bit [15] : Value location (0 = value saved in BLE Stack; 1 = value saved in user space) \n
200 */
201
202 /** @defgroup BLE_GATTS_ATTR_EXT_PERM Attribute Extend Permission
203 * @{ */
204 #define ATT_VAL_LOC_USER (1 << 15) /**< Value location which means value saved in user space, the profile's read/write callback will be called. */
205 #define ATT_VAL_LOC_STACK (0 << 15) /**< Value location which means value saved in BLE Stack. */
206 #define ATT_UUID_TYPE_SET(uuid_len) ((uuid_len) << 13) /**< Attribute UUID length set. See @ref BLE_GATTS_UUID_TYPE */
207 #define ATT_ENC_KEY_SIZE_16 (0x1000) /**< 16 bytes attribute encryption key size . */
208 /** @} */
209
210
211 /** @} */
212
213 /** @addtogroup BLE_GATTS_ENUMERATIONS Enumerations
214 * @{ */
215
216 /**
217 * @brief Service table type.
218 */
219 typedef enum
220 {
221 SERVICE_TABLE_TYPE_16 = 0x00, /**< 16-bit service table type. */
222 SERVICE_TABLE_TYPE_128, /**< 128-bit service table type. */
223 } gatts_service_type_t;
224
225
226 /** @} */
227
228
229 /** @addtogroup BLE_GATTS_STRUCTURES Structures
230 * @{ */
231
232 /**
233 * @brief Service(16-bit UUID) description.
234 */
235 typedef struct
236 {
237 uint16_t uuid; /**< 16-bit LSB-first UUID */
238 uint16_t perm; /**< Attribute permissions, see @ref BLE_GATTS_ATTR_PERM. \n
239 - For Primary/Secondary/Included Services, must be @ref READ_PERM_UNSEC. \n
240 - For Characteristic Declaration, must be @ref READ_PERM_UNSEC. \n
241 - For Characteristic Extended Properties, must be @ref READ_PERM_UNSEC. \n
242 - For Characteristic Presentation Format, must be @ref READ_PERM_UNSEC. \n
243 - For Characteristic Aggregate Format, must be @ref READ_PERM_UNSEC. */
244
245 uint16_t ext_perm; /**< Attribute extended permissions, see @ref BLE_GATTS_ATTR_EXT_PERM. \n
246 - For Primary/Secondary/Included Services, this field is not used and should be set to 0. \n
247 - For Characteristic Declaration, this field is not used and should be set to 0. \n
248 - For Characteristic Extended Properties, this field is not used and should be set to 0. \n
249 - For Client Characteristic Configuration and Server Characteristic Configuration, value must be saved in user space,
250 user needn't to set this value location bit. The UUID length type must be set to 0.*/
251
252 uint16_t max_size; /**< Attribute max size. \n
253 - For Primary/Secondary/Included Services, this field is not used, set to 0. \n
254 - For Characteristic Declaration, this field is not used, set to 0. \n
255 - For Characteristic Extended Properties, this field contains 2-byte value. \n
256 - For Client Characteristic Configuration and Server Characteristic Configuration, this field is not used, set to 0. \n
257 - For others, this field is attribute max size. */
258 } attm_desc_t;
259
260 /**
261 * @brief Service(128 bits UUID) description.
262 */
263 typedef struct
264 {
265 uint8_t uuid[16]; /**< 128 bits UUID LSB First. */
266 uint16_t perm; /**< Attribute permissions, see @ref BLE_GATTS_ATTR_PERM. \n
267 - For Primary/Secondary/Included Services, must be @ref READ_PERM_UNSEC. \n
268 - For Characteristic Declaration, must be @ref READ_PERM_UNSEC. \n
269 - For Characteristic Extended Properties, must be @ref READ_PERM_UNSEC. \n
270 - For Characteristic Presentation Format, must be @ref READ_PERM_UNSEC. \n
271 - For Characteristic Aggregate Format, must be @ref READ_PERM_UNSEC. */
272
273 uint16_t ext_perm; /**< Attribute extended permissions, see @ref BLE_GATTS_ATTR_EXT_PERM. \n
274 - For Primary/Secondary/Included Services, this field is not used, set to 0. \n
275 - For Characteristic Declaration, this field is not used, set to 0. \n
276 - For Characteristic Extended Properties, this field is not used, set to 0. \n
277 - For Client Characteristic Configuration and Server Characteristic Configuration, value must be saved in user space,
278 user needn't to set this value location bit. The UUID length type must be set to 0.*/
279
280 uint16_t max_size; /**< Attribute max size. \n
281 - For Primary/Secondary/Included Services, this field is not used, set to 0. \n
282 - For Characteristic Declaration, this field is not used, set to 0. \n
283 - For Characteristic Extended Properties, this field contains 2-byte value. \n
284 - For Client Characteristic Configuration and Server Characteristic Configuration, this field is not used, set to 0. \n
285 - For others, this field is attribute max size. */
286 } attm_desc_128_t;
287
288 /**
289 * @brief Parameter of Added service description.
290 */
291 typedef struct
292 {
293
294 uint16_t *shdl; /**< Service start handle pointer.
295 If *shdl = 0, it returns a handle using the first available handle (*shdl is modified);
296 otherwise it verifies if the given start handle can be used to allocate handle range. */
297 const uint8_t *uuid; /**< Service UUID pointer. The pointer points to the Service UUID LSB. */
298 uint8_t *attr_tab_cfg; /**< Attribute table selector pointer. It can be set to NULL to select all items of attribute table.
299 Each bit matches with an attribute of attribute table. \n
300 EXAMPLE:if attr_tab_cfg points to array {0x3F, 0x03}, it means that the 0.1.2.3.4.5.8.9 items of attribute table will be added to database. */
301
302 uint8_t max_nb_attr; /**< Number of attributes in attribute table. */
303 union attribute_table /**< Attribute table. */
304 {
305 const attm_desc_t *attr_tab_16; /**< 16 bits service description. The pointer point to attribute table of 16 bits service. See @ref attm_desc_t. */
306 const attm_desc_128_t *attr_tab_128; /**< 128 bits service description. The pointer point to attribute table of 128 bits service. See @ref attm_desc_128_t. */
307 } attr_tab; /**< Attribute table. */
308 uint16_t *inc_srvc_handle[MAX_INC_SRVC_NUM]; /**< Pointer array of Included Service start handle's address. */
309 uint16_t inc_srvc_num; /**< Included Service number for this service. */
310 uint8_t srvc_perm; /**< Service permission. See @ref BLE_GATTS_SRVC_PERM. */
311 gatts_service_type_t attr_tab_type; /**< Service table type. See @ref gatts_service_type_t. */
312 } gatts_create_db_t;
313
314 /**
315 * @brief GATT read attribute result description.
316 */
317 typedef struct
318 {
319 uint16_t handle; /**< Handle of the read attribute. */
320 uint16_t length; /**< Length of read data. */
321 uint8_t status; /**< Status of read operation by upper layers. See @ref BLE_STACK_ERROR_CODES.*/
322 uint8_t *value; /**< Attribute value pointer. */
323 } gatts_read_cfm_t;
324
325 /**
326 * @brief GATT write attribute result description.
327 */
328 typedef struct
329 {
330 uint16_t handle; /**< Handle of the attribute written. */
331 uint8_t status; /**< Status of write operation by upper layers. See @ref BLE_STACK_ERROR_CODES.*/
332 } gatts_write_cfm_t;
333
334 /**
335 * @brief GATT prepare write result description.
336 */
337 typedef struct
338 {
339 uint16_t handle; /**< Handle of the attribute in prepare write operation. */
340 uint16_t length; /**< Current length of the attribute. */
341 uint8_t status; /**< Status of prepare write operation by upper layers. See @ref BLE_STACK_ERROR_CODES.*/
342 } gatts_prep_write_cfm_t;
343
344
345 /**
346 * @brief GATT sending Notification or Indication event param description.
347 */
348 typedef struct
349 {
350 gatt_evt_type_t type; /**< Request type (Notification/Indication). see @ref gatt_evt_type_t. */
351 uint16_t handle; /**< Characteristic Value handle to be notified or indicated. */
352 uint16_t length; /**< Length of Characteristic Value to be sent. */
353 uint8_t *value; /**< Characteristic Value pointer. */
354 } gatts_noti_ind_t;
355
356 /** @} */
357
358
359 /** @addtogroup BLE_GATTS_FUNCTIONS Functions
360 * @{ */
361 /**
362 ****************************************************************************************
363 * @brief Register a service's attribute list.
364 *
365 * @param[in, out] p_param: Pointer to the parameter used in creating databases. see @ref gatts_create_db_t.
366 *
367 * @retval ::SDK_SUCCESS: Database has been registered successfully.
368 * @retval ::SDK_ERR_POINTER_NULL: Param is NULL or param's members are NULL.
369 * @retval ::SDK_ERR_INVALID_PARAM: The member of param is invalid.
370 * @retval ::SDK_ERR_INVALID_HANDLE: The service handles can not be allocated.
371 * @retval ::SDK_ERR_NO_RESOURCES: There is not enough memory to allocate service buffer.
372 * @retval ::SDK_ERR_INVALID_PERM: Permissions of Client Characteristic Configuration or Server Characteristic Configuration are not set correctly.
373 ****************************************************************************************
374 */
375 uint16_t ble_gatts_srvc_db_create(gatts_create_db_t *p_param);
376
377 /**
378 ****************************************************************************************
379 * @brief Update attribute value only if the attribute value is saved in the BLE Stack space.
380 *
381 * @param[in] handle: Attribute handle.
382 * @param[in] length: Size of the value to set.
383 * @param[in] offset: Data offset of the value in attribute value.
384 * @param[in] p_value: The value to set. If offset = 0, the value is the new attribute value; otherwise, the value is part of the new attribute value.
385 *
386 * @retval ::SDK_SUCCESS: Successfully update the attribute value.
387 * @retval ::SDK_ERR_POINTER_NULL: Value is NULL.
388 * @retval ::SDK_ERR_INVALID_HANDLE: Handle not exist in database.
389 * @retval ::SDK_ERR_REQ_NOT_SUPPORTED: Attribute data is not present in database or cannot be modified.
390 * @retval ::SDK_ERR_INVALID_ATT_VAL_LEN: New value length exceeds maximum attribute value length.
391 * @retval ::SDK_ERR_INVALID_OFFSET: Offset exceeds current attribute value length.
392 ****************************************************************************************
393 */
394 uint16_t ble_gatts_value_set(uint16_t handle, uint16_t length, uint16_t offset, const uint8_t* p_value);
395
396 /**
397 ****************************************************************************************
398 * @brief Retrieve attribute value only if the attribute value is saved in the BLE Stack space.
399 *
400 * @param[in] handle: Attribute handle.
401 * @param[in,out] p_length: Input as buffer size and output as attribute value length.
402 * @param[out] p_value: Buffer to store attribute value when buffer size is enough.
403 *
404 * @retval ::SDK_SUCCESS: Attribute value retrieved successfully.
405 * @retval ::SDK_ERR_POINTER_NULL: The pointer to input buffer size or input buffer is NULL.
406 * @retval ::SDK_ERR_INVALID_HANDLE: Handle not exist in the database.
407 * @retval ::SDK_ERR_REQ_NOT_SUPPORTED: Attribute data is not present in database.
408 * @retval ::SDK_ERR_INVALID_ATT_VAL_LEN: Attribute data value size is bigger than buffer size.
409 * @retval ::SDK_ERR_APP_ERROR: Database is not correctly initialized by application.
410 ****************************************************************************************
411 */
412 uint16_t ble_gatts_value_get(uint16_t handle, uint16_t* p_length, uint8_t* p_value);
413
414 /**
415 ****************************************************************************************
416 * @brief Update attribute permission.
417 * @note The modifications of attribute permission to service/character/include/character_extended_properties_descriptor declaration: not supported. \n
418 * The modifications of attribute permission to others: perm can be updated and EKS of ext_perm can be updated.See @ref BLE_GATTS_ATTR_PERM.
419 *
420 * @param[in] handle: Attribute handle.
421 * @param[in] perm: New attribute permission.
422 * @param[in] ext_perm: New attribute extended permission.
423 *
424 * @retval ::SDK_SUCCESS: Update attribute permission successfully.
425 * @retval ::SDK_ERR_INVALID_HANDLE: Handle not exist in the database.
426 * @retval ::SDK_ERR_REQ_NOT_SUPPORTED: Attribute permission can't be modified.
427 ****************************************************************************************
428 */
429 uint16_t ble_gatts_attr_permission_set(uint16_t handle, uint16_t perm, uint16_t ext_perm);
430
431 /**
432 ****************************************************************************************
433 * @brief Retrieve attribute permission.
434 *
435 * @param[in] handle: Attribute handle.
436 * @param[out] p_perm: Attribute permission value to be returned.
437 * @param[out] p_ext_perm: Attribute extended permission value to be returned.
438 *
439 * @retval ::SDK_SUCCESS: Retrieve attribute permission successfully.
440 * @retval ::SDK_ERR_POINTER_NULL: Perm or ext_perm is NULL.
441 * @retval ::SDK_ERR_INVALID_HANDLE: Handle not exist in the database.
442 ****************************************************************************************
443 */
444 uint16_t ble_gatts_attr_permission_get(uint16_t handle, uint16_t *p_perm, uint16_t *p_ext_perm);
445
446 /**
447 ****************************************************************************************
448 * @brief Respond to an attribute read request. It is used in profile read callback function @ref gatts_prf_cbs_t::app_gatts_read_cb
449 * to send attribute value to stack which is saved in user space.
450 *
451 * @note The status member gatts_read_cfm_t::status should be set to @ref BLE_ATT_ERR_INSUFF_AUTHOR
452 * to control the authorization of particular read operations of a client.
453 *
454 * @param[in] conn_idx: Current connection index.
455 * @param[in] p_param: Pointer to the parameters filled by profile. See @ref gatts_read_cfm_t.
456 *
457 * @retval ::SDK_SUCCESS: Send read confirm value to stack successfully.
458 * @retval ::SDK_ERR_POINTER_NULL: Param is NULL.
459 * @retval ::SDK_ERR_INVALID_CONN_IDX: Conidx is invalid.
460 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
461 ****************************************************************************************
462 */
463 uint16_t ble_gatts_read_cfm(uint8_t conn_idx, const gatts_read_cfm_t *p_param);
464
465 /**
466 ****************************************************************************************
467 * @brief Respond to an attribute write request. It is used in profile write callback function
468 * @ref gatts_prf_cbs_t::app_gatts_write_cb to send write operation status to stack.
469 *
470 * @note The status member gatts_write_cfm_t::status should be set to @ref BLE_ATT_ERR_INSUFF_AUTHOR
471 * to control the authorization of particular client's write operation.
472 *
473 * @param[in] conn_idx: Current connection index.
474 * @param[in] p_param: Pointer to the parameters filled by profile. see @ref gatts_write_cfm_t.
475 *
476 * @retval ::SDK_SUCCESS: Send write confirm status to stack successfully.
477 * @retval ::SDK_ERR_POINTER_NULL: Param is NULL.
478 * @retval ::SDK_ERR_INVALID_CONN_IDX: Conidx is invalid.
479 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
480 ****************************************************************************************
481 */
482 uint16_t ble_gatts_write_cfm(uint8_t conn_idx, const gatts_write_cfm_t *p_param);
483
484 /**
485 ****************************************************************************************
486 * @brief Respond to an attribute prepare write request. It is used in profile prepare write callback
487 * function @ref gatts_prf_cbs_t::app_gatts_prep_write_cb to send prepare write operation status to stack.
488 *
489 * @note The status member gatts_prep_write_cfm_t::status should be set to @ref BLE_ATT_ERR_INSUFF_AUTHOR
490 * to control the authorization of particular client's write operation.
491 *
492 * @param[in] conn_idx: Current connection index.
493 * @param[in] p_param: Pointer to the parameters filled by profile. see @ref gatts_prep_write_cfm_t.
494 *
495 * @retval ::SDK_SUCCESS: Send prepare write confirm status to stack successfully.
496 * @retval ::SDK_ERR_POINTER_NULL: Param is NULL.
497 * @retval ::SDK_ERR_INVALID_CONN_IDX: Conidx is invalid.
498 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
499 ****************************************************************************************
500 */
501 uint16_t ble_gatts_prepare_write_cfm(uint8_t conn_idx, const gatts_prep_write_cfm_t *p_param);
502
503 /**
504 ****************************************************************************************
505 * @brief Send out a notification or an indication. The execution status of sending notification or
506 * indication will be retrieved in the complete callback function @ref gatts_prf_cbs_t::app_gatts_ntf_ind_cb.
507 *
508 * @note Check whether the relevant Client Characteristic Configuration Descriptor is enabled before using this API.
509 *
510 * @param[in] conn_idx: Current connection index.
511 * @param[in] p_param: Pointer to the parameters filled by profile. see @ref gatts_noti_ind_t.
512 *
513 * @retval ::SDK_SUCCESS: Send Notification or Indication event to stack successfully.
514 * @retval ::SDK_ERR_POINTER_NULL: Param is NULL.
515 * @retval ::SDK_ERR_INVALID_CONN_IDX: Conidx is invalid.
516 * @retval ::SDK_ERR_INVALID_PARAM: Type is invalid.
517 * @retval ::SDK_ERR_INVALID_HANDLE: Handle not exist in the database.
518 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
519 ****************************************************************************************
520 */
521 uint16_t ble_gatts_noti_ind(uint8_t conn_idx, const gatts_noti_ind_t *p_param);
522
523 /**
524 ****************************************************************************************
525 * @brief When service on local device finishes upgrade, call this API to send service upgrade to stack.
526 * If the bonded device connects again, the stack will send service change to the bonded device until the bonded
527 * device has sent back indication confirmation.
528 ****************************************************************************************
529 */
530 void ble_gatts_service_changed(void);
531 /** @} */
532
533 #endif // BLE_SDK_GATTS_H_
534 /** @} */
535
536 /** @} */
537 /** @} */
538
gatts_service_type_t
gatts_service_type_t
Service table type.
Definition: ble_gatts.h:220
gatts_read_cfm_t::length
uint16_t length
Length of read data.
Definition: ble_gatts.h:320
attm_desc_t
Service(16-bit UUID) description.
Definition: ble_gatts.h:236
SERVICE_TABLE_TYPE_16
@ SERVICE_TABLE_TYPE_16
16-bit service table type.
Definition: ble_gatts.h:221
SERVICE_TABLE_TYPE_128
@ SERVICE_TABLE_TYPE_128
128-bit service table type.
Definition: ble_gatts.h:222
gatts_noti_ind_t::length
uint16_t length
Length of Characteristic Value to be sent.
Definition: ble_gatts.h:352
ble_gatts_read_cfm
uint16_t ble_gatts_read_cfm(uint8_t conn_idx, const gatts_read_cfm_t *p_param)
Respond to an attribute read request.
ble_gatts_prepare_write_cfm
uint16_t ble_gatts_prepare_write_cfm(uint8_t conn_idx, const gatts_prep_write_cfm_t *p_param)
Respond to an attribute prepare write request.
gatts_create_db_t::srvc_perm
uint8_t srvc_perm
Service permission.
Definition: ble_gatts.h:310
gatts_noti_ind_t::value
uint8_t * value
Characteristic Value pointer.
Definition: ble_gatts.h:353
attm_desc_128_t
Service(128 bits UUID) description.
Definition: ble_gatts.h:264
ble_gatt.h
BLE GATT.
ble_gatts_write_cfm
uint16_t ble_gatts_write_cfm(uint8_t conn_idx, const gatts_write_cfm_t *p_param)
Respond to an attribute write request.
gatts_noti_ind_t
GATT sending Notification or Indication event param description.
Definition: ble_gatts.h:349
gatt_evt_type_t
gatt_evt_type_t
GATT common events.
Definition: ble_gatt.h:67
gatts_read_cfm_t::value
uint8_t * value
Attribute value pointer.
Definition: ble_gatts.h:322
gatts_create_db_t::attr_tab_type
gatts_service_type_t attr_tab_type
Service table type.
Definition: ble_gatts.h:311
ble_gatts_srvc_db_create
uint16_t ble_gatts_srvc_db_create(gatts_create_db_t *p_param)
Register a service's attribute list.
gatts_create_db_t::attribute_table::attr_tab_16
const attm_desc_t * attr_tab_16
16 bits service description.
Definition: ble_gatts.h:305
ble_gatts_attr_permission_set
uint16_t ble_gatts_attr_permission_set(uint16_t handle, uint16_t perm, uint16_t ext_perm)
Update attribute permission.
gatts_write_cfm_t
GATT write attribute result description.
Definition: ble_gatts.h:329
gatts_create_db_t::attr_tab_cfg
uint8_t * attr_tab_cfg
Attribute table selector pointer.
Definition: ble_gatts.h:298
ble_gatts_value_set
uint16_t ble_gatts_value_set(uint16_t handle, uint16_t length, uint16_t offset, const uint8_t *p_value)
Update attribute value only if the attribute value is saved in the BLE Stack space.
attm_desc_128_t::max_size
uint16_t max_size
Attribute max size.
Definition: ble_gatts.h:280
gatts_create_db_t::inc_srvc_num
uint16_t inc_srvc_num
Included Service number for this service.
Definition: ble_gatts.h:309
gatts_prep_write_cfm_t::length
uint16_t length
Current length of the attribute.
Definition: ble_gatts.h:340
ble_error.h
File that contains error codes.
gatts_create_db_t::attribute_table
< Attribute table.
Definition: ble_gatts.h:304
gatts_prep_write_cfm_t::status
uint8_t status
Status of prepare write operation by upper layers.
Definition: ble_gatts.h:341
attm_desc_128_t::perm
uint16_t perm
Attribute permissions, see Attribute Permission.
Definition: ble_gatts.h:266
gatts_read_cfm_t::handle
uint16_t handle
Handle of the read attribute.
Definition: ble_gatts.h:319
attm_desc_t::ext_perm
uint16_t ext_perm
Attribute extended permissions, see Attribute Extend Permission.
Definition: ble_gatts.h:245
attm_desc_t::uuid
uint16_t uuid
16-bit LSB-first UUID
Definition: ble_gatts.h:237
gatts_read_cfm_t::status
uint8_t status
Status of read operation by upper layers.
Definition: ble_gatts.h:321
MAX_INC_SRVC_NUM
#define MAX_INC_SRVC_NUM
The max number of Included Services a Primary/Secondary service can have.
Definition: ble_gatts.h:70
gatts_prep_write_cfm_t
GATT prepare write result description.
Definition: ble_gatts.h:338
gatts_create_db_t::shdl
uint16_t * shdl
Service start handle pointer.
Definition: ble_gatts.h:294
gatts_write_cfm_t::status
uint8_t status
Status of write operation by upper layers.
Definition: ble_gatts.h:331
gatts_create_db_t::uuid
const uint8_t * uuid
Service UUID pointer.
Definition: ble_gatts.h:297
gatts_noti_ind_t::type
gatt_evt_type_t type
Request type (Notification/Indication).
Definition: ble_gatts.h:350
gatts_prep_write_cfm_t::handle
uint16_t handle
Handle of the attribute in prepare write operation.
Definition: ble_gatts.h:339
ble_gatts_attr_permission_get
uint16_t ble_gatts_attr_permission_get(uint16_t handle, uint16_t *p_perm, uint16_t *p_ext_perm)
Retrieve attribute permission.
gatts_create_db_t::max_nb_attr
uint8_t max_nb_attr
Number of attributes in attribute table.
Definition: ble_gatts.h:302
gatts_write_cfm_t::handle
uint16_t handle
Handle of the attribute written.
Definition: ble_gatts.h:330
ble_gatts_noti_ind
uint16_t ble_gatts_noti_ind(uint8_t conn_idx, const gatts_noti_ind_t *p_param)
Send out a notification or an indication.
gatts_create_db_t
Parameter of Added service description.
Definition: ble_gatts.h:292
ble_att.h
Attribute Protocol.
ble_gatts_value_get
uint16_t ble_gatts_value_get(uint16_t handle, uint16_t *p_length, uint8_t *p_value)
Retrieve attribute value only if the attribute value is saved in the BLE Stack space.
ble_gatts_service_changed
void ble_gatts_service_changed(void)
When service on local device finishes upgrade, call this API to send service upgrade to stack.
gatts_noti_ind_t::handle
uint16_t handle
Characteristic Value handle to be notified or indicated.
Definition: ble_gatts.h:351
gatts_create_db_t::attribute_table::attr_tab_128
const attm_desc_128_t * attr_tab_128
128 bits service description.
Definition: ble_gatts.h:306
attm_desc_t::max_size
uint16_t max_size
Attribute max size.
Definition: ble_gatts.h:252
attm_desc_t::perm
uint16_t perm
Attribute permissions, see Attribute Permission.
Definition: ble_gatts.h:238
gatts_read_cfm_t
GATT read attribute result description.
Definition: ble_gatts.h:318
attm_desc_128_t::ext_perm
uint16_t ext_perm
Attribute extended permissions, see Attribute Extend Permission.
Definition: ble_gatts.h:273