ble_gattc.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file ble_gattc.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 /**
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_GATTC Generic Attribute Profile (GATT) Client
51 @{
52 @brief Definitions and prototypes for the GATT client interfaces.
53 */
54
55 #ifndef __BLE_GATTC_H__
56 #define __BLE_GATTC_H__
57
58 #include "ble_error.h"
59 #include "ble_gatt.h"
60 #include "ble_att.h"
61 #include "gr55xx_sys_cfg.h"
62
63 #include <stdint.h>
64 #include <stdbool.h>
65
66 /** @addtogroup BLE_GATTC_ENUMERATIONS Enumerations
67 * @{ */
68
69 /**
70 * @brief GATT Client Service Discover Attribute type IDs.
71 */
72 typedef enum
73 {
74 BLE_GATTC_BROWSE_NONE, /**< No Attribute Information. */
75 BLE_GATTC_BROWSE_INC_SRVC, /**< Included Service information. */
76 BLE_GATTC_BROWSE_ATTR_CHAR, /**< Characteristic Declaration. */
77 BLE_GATTC_BROWSE_ATTR_VAL, /**< Attribute Value definition. */
78 BLE_GATTC_BROWSE_ATTR_DESC, /**< Attribute Descriptor. */
79 } gatt_attr_t;
80
81 /** @} */
82
83 /** @addtogroup BLE_GATTC_STRUCTURES Structures
84 * @{ */
85
86 /**
87 * @brief GATTC discovery characteristic structure.
88 */
89 typedef struct
90 {
91 uint16_t start_hdl; /**< Start handle. */
92 uint16_t end_hdl; /**< End handle. */
93 ble_uuid_t *p_uuid; /**< Characteristic UUID. */
94 } gattc_disc_char_t;
95
96 /**
97 * @brief GATTC read by characteristic UUID structure.
98 */
99 typedef struct
100 {
101 uint16_t start_hdl; /**< Start handle. */
102 uint16_t end_hdl; /**< End handle. */
103 ble_uuid_t *p_uuid; /**< Characteristic UUID. */
104 } gattc_read_by_uuid_t;
105
106 /**
107 * @brief GATTC write attribute value structure.
108 */
109 typedef struct
110 {
111 uint16_t handle; /**< Attribute handle. */
112 uint16_t offset; /**< value offset to start with. */
113 uint16_t length; /**< Write length. */
114 uint8_t *p_value; /**< Value to write. */
115 } gattc_write_attr_value_t;
116
117 /**
118 * @brief GATTC write without response structure.
119 */
120 typedef struct
121 {
122 bool signed_write; /**< True if signed write should be used when possible/applicable. */
123 uint16_t handle; /**< Attribute handle. */
124 uint16_t length; /**< Write length. */
125 uint8_t *p_value; /**< Value to write. */
126 } gattc_write_no_resp_t;
127
128 /**@brief Read Multiple Handles. */
129 typedef struct
130 {
131 uint16_t handle; /**< Attribute handle. */
132 uint16_t len; /**< Known value: length of the handle (len shall not be set to 0). */
133 } read_multiple_t;
134
135 /**@brief GATTC Read Multiple. */
136 typedef struct
137 {
138 uint16_t handle_count; /**< Handle count of the multiple attributes to be read. */
139 read_multiple_t *p_read_multiple; /**< Pointer to the multiple attributes to be read. */
140 } gattc_read_multiple_t;
141
142
143 /**@brief GATTC Browse information about Characteristic. */
144 typedef struct
145 {
146 uint8_t attr_type; /**< Attribute type. See @ref BLE_GATTC_BROWSE_ATTR_CHAR for Characteristic Declaration. */
147 uint8_t prop; /**< Value property. */
148 uint16_t handle; /**< Value handle. */
149 uint8_t uuid_len; /**< Characteristic UUID length. */
150 uint8_t uuid[BLE_ATT_UUID_128_LEN]; /**< Characteristic UUID. */
151 } gattc_browse_attr_char_t;
152
153 /**@brief GATTC Browse information about Included Service. */
154 typedef struct
155 {
156 uint8_t attr_type; /**< Attribute type. See @ref BLE_GATTC_BROWSE_INC_SRVC for Included Service Information. */
157 uint8_t uuid_len; /**< Included Service UUID length. */
158 uint8_t uuid[BLE_ATT_UUID_128_LEN]; /**< Included Service UUID. */
159 uint16_t start_hdl; /**< Included Service start handle. */
160 uint16_t end_hdl; /**< Included Service end handle. */
161 } gattc_browse_inc_srvc_t;
162
163 /**@brief GATTC Browse information about Attribute. */
164 typedef struct
165 {
166 uint8_t attr_type; /**< Attribute type. See @ref BLE_GATTC_BROWSE_ATTR_VAL for Attribute Value. See @ref BLE_GATTC_BROWSE_ATTR_DESC for Attribute Descriptor. */
167 uint8_t uuid_len; /**< Attribute UUID length. */
168 uint8_t uuid[BLE_ATT_UUID_128_LEN]; /**< Characteristic UUID or Characteristic Descriptor UUID. */
169 } gattc_browse_attr_t;
170
171 /**@brief GATTC Browse attribute information. */
172 union gattc_browse_attr_info
173 {
174 uint8_t attr_type; /**< Attribute type. See @ref gatt_attr_t. */
175 gattc_browse_attr_char_t attr_char; /**< Information about Characteristic. When union attr_type is @ref BLE_GATTC_BROWSE_ATTR_CHAR */
176 gattc_browse_inc_srvc_t inc_srvc; /**< Information about Included Service. When union attr_type is @ref BLE_GATTC_BROWSE_INC_SRVC */
177 gattc_browse_attr_t attr; /**< Information about Attribute. When union attr_type is @ref BLE_GATTC_BROWSE_ATTR_VAL or @ref BLE_GATTC_BROWSE_ATTR_DESC. */
178 };
179
180 /**@brief GATTC Browse service(s) indication. */
181 typedef struct
182 {
183 uint8_t uuid_len; /**< Service UUID length. */
184 uint8_t uuid[BLE_ATT_UUID_128_LEN]; /**< Service UUID. */
185 uint16_t start_hdl; /**< Service start handle. */
186 uint16_t end_hdl; /**< Service end handle. */
187 union gattc_browse_attr_info info[__ARRAY_EMPTY]; /**< Attribute information presented in the service(array length = end_hdl - start_hdl);
188 If attr_type is equal to BLE_GATTC_BROWSE_NONE, the last attribute information has been found in previous one, although not reach the service end handle. */
189 } ble_gattc_browse_srvc_t;
190
191
192
193 /**@brief GATT service. */
194 typedef struct
195 {
196 uint16_t start_hdl; /**< Start handle. */
197 uint16_t end_hdl; /**< End handle. */
198 uint8_t uuid_len; /**< Service UUID length. */
199 uint8_t *p_uuid; /**< Service UUID. */
200 } ble_gattc_service_t;
201
202 /**@brief GATT include. */
203 typedef struct
204 {
205 uint16_t attr_hdl; /**< Attribute handle. */
206 uint16_t start_hdl; /**< Start handle. */
207 uint16_t end_hdl; /**< End handle. */
208 uint8_t uuid_len; /**< Service UUID length. */
209 uint8_t *p_uuid; /**< Service UUID. */
210 } ble_gattc_include_t;
211
212 /**@brief GATT characteristic. */
213 typedef struct
214 {
215 uint16_t handle_decl; /**< Handle of the Characteristic Declaration. */
216 uint16_t handle_value; /**< Handle of the Characteristic Value. */
217 uint8_t prop; /**< Properties. */
218 uint8_t uuid_len; /**< Characteristic UUID length. */
219 uint8_t *p_uuid; /**< Characteristic UUID. */
220 } ble_gattc_char_t;
221
222 /**@brief GATT descriptor. */
223 typedef struct
224 {
225 uint16_t attr_hdl; /**< Attribute handle. */
226 uint8_t uuid_len; /**< Descriptor UUID length. */
227 uint8_t *p_uuid; /**< Descriptor UUID. */
228 } ble_gattc_desc_t;
229
230 /**@brief GATT service discovery. */
231 typedef struct
232 {
233 uint16_t count; /**< Service count. */
234 ble_gattc_service_t services[__ARRAY_EMPTY]; /**< Service data. */
235 }ble_gattc_srvc_disc_t;
236
237 /**@brief GATT include discovery. */
238 typedef struct
239 {
240 uint16_t count; /**< Include count. */
241 ble_gattc_include_t includes[__ARRAY_EMPTY]; /**< Include data. */
242 }ble_gattc_incl_disc_t;
243
244 /**@brief GATT characteristic discovery. */
245 typedef struct
246 {
247 uint16_t count; /**< Characteristic count. */
248 ble_gattc_char_t chars[__ARRAY_EMPTY]; /**< Characteristic data. */
249 }ble_gattc_char_disc_t;
250
251 /**@brief GATT characteristic descriptor discovery. */
252 typedef struct
253 {
254 uint16_t count; /**< Descriptor count. */
255 ble_gattc_desc_t char_descs[__ARRAY_EMPTY]; /**< Descriptor data. */
256 }ble_gattc_char_desc_disc_t;
257
258 /**@brief GATT Client Read value. */
259 typedef struct
260 {
261 uint16_t handle; /**< Attribute handle. */
262 uint16_t offset; /**< Offset of the attribute value. */
263 uint16_t length; /**< Attribute value length. */
264 uint8_t *p_value; /**< Pointer to the attribute value data. */
265 } ble_gattc_read_value_t;
266
267 /**@brief GATT value Read response. */
268 typedef struct
269 {
270 uint16_t count; /**< Value Count. */
271 ble_gattc_read_value_t vals[__ARRAY_EMPTY]; /**< Value(s) list. */
272 }ble_gattc_read_rsp_t;
273
274
275 /**@brief GATT Client Write. */
276 typedef struct
277 {
278 uint16_t handle; /**< Attribute handle. */
279 } ble_gattc_write_t;
280
281
282 /**@brief GATTC Notification and Indication value indication. */
283 typedef struct
284 {
285 gatt_evt_type_t type; /**< Event type. */
286 uint16_t length; /**< Attribute value length. */
287 uint16_t handle; /**< Attribute handle. */
288 uint8_t *p_value; /**< Pointer to the attribute value data. */
289 } ble_gattc_ntf_ind_t;
290
291 /**@brief GATTC Event callback Structures. */
292 typedef struct
293 {
294 void (*app_gattc_srvc_disc_cb)(uint8_t conn_idx, uint8_t status, const ble_gattc_srvc_disc_t * p_prim_srvc_disc); /**< Primary Service Discovery Response callback. */
295 void (*app_gattc_inc_srvc_disc_cb)(uint8_t conn_idx, uint8_t status, const ble_gattc_incl_disc_t * p_inc_srvc_disc); /**< Relationship Discovery Response callback. */
296 void (*app_gattc_char_disc_cb)(uint8_t conn_idx, uint8_t status, const ble_gattc_char_disc_t * p_char_disc); /**< Characteristic Discovery Response callback. */
297 void (*app_gattc_char_desc_disc_cb)(uint8_t conn_idx, uint8_t status, const ble_gattc_char_desc_disc_t *p_char_desc_disc); /**< Descriptor Discovery Response callback. */
298 void (*app_gattc_read_cb)(uint8_t conn_idx, uint8_t status, const ble_gattc_read_rsp_t *p_read_rsp); /**< Read Response callback. */
299 void (*app_gattc_write_cb)(uint8_t conn_idx, uint8_t status, uint16_t handle); /**< Write complete callback. */
300 void (*app_gattc_ntf_ind_cb)(uint8_t conn_idx, const ble_gattc_ntf_ind_t *p_ntf_ind); /**< Handle Value Notification/Indication Event callback. */
301 void (*app_gattc_srvc_browse_cb)(uint8_t conn_idx, uint8_t status, const ble_gattc_browse_srvc_t *p_browse_srvc); /**< Service found callback during browsing procedure. */
302 } gattc_cb_fun_t;
303 /** @} */
304
305 /** @addtogroup BLE_GATTC_FUNCTIONS Functions
306 * @{ */
307
308 /**
309 ****************************************************************************************
310 * @brief Perform MTU Exchange.
311 *
312 * @note MTU Exchange Callback @ref gatt_common_cb_fun_t::app_gatt_mtu_exchange_cb will be called to indicate to APP once receiving the peer response.
313 *
314 * @param[in] conn_idx: Current connection index.
315 *
316 * @retval ::SDK_SUCCESS: Successfully send an MTU Exchange request.
317 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
318 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
319 ****************************************************************************************
320 */
321 uint16_t ble_gattc_mtu_exchange(uint8_t conn_idx);
322
323 /**
324 ****************************************************************************************
325 * @brief Browse all Primary Services or specific Primary Service information on remote GATT server.
326 *
327 * @note This discovery automatically searches for Primary Services, Included Services, Characteristics and Descriptors of each service.
328 * To discover one or more services only, use ble_gattc_primary_services_discover() instead.
329 * This discovery is able to search all Primary Services or a specific one.
330 * If srvc_uuid is NULL, all services are returned.
331 *
332 * @note Function callback @ref gattc_cb_fun_t::app_gattc_srvc_browse_cb will be called for all attributes of each service found.
333 *
334 * @param[in] conn_idx: Current connection index.
335 * @param[in] p_srvc_uuid: Pointer to Service UUID. If it is NULL, all services will be returned.
336 *
337 * @retval ::SDK_SUCCESS: Successfully start the Browse Service(s) procedure.
338 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
339 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
340 ****************************************************************************************
341 */
342 uint16_t ble_gattc_services_browse(uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid);
343
344 /**
345 ****************************************************************************************
346 * @brief Discover Primary Services on remote GATT server.
347 *
348 * @note Function callback @ref gattc_cb_fun_t::app_gattc_srvc_disc_cb will be called for service(s) found.
349 *
350 * @param[in] conn_idx: Current connection index.
351 * @param[in] p_srvc_uuid: Pointer to Service UUID. If it is NULL, all Primary Services will be returned.
352 *
353 * @retval ::SDK_SUCCESS: Successfully start the Primary Service Discovery procedure.
354 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
355 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
356 ****************************************************************************************
357 */
358 uint16_t ble_gattc_primary_services_discover(uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid);
359
360 /**
361 ****************************************************************************************
362 * @brief Discover Included Services on remote GATT server.
363 *
364 * @note Function callback @ref gattc_cb_fun_t::app_gattc_inc_srvc_disc_cb will be called for Included Service(s) found.
365 * @param[in] conn_idx: Current connection index.
366 * @param[in] start_hdl: Start handle.
367 * @param[in] end_hdl: End handle.
368 *
369 * @retval ::SDK_SUCCESS: Successfully start the Relationship Discovery procedure.
370 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
371 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
372 ****************************************************************************************
373 */
374 uint16_t ble_gattc_included_services_discover(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl);
375
376 /**
377 ****************************************************************************************
378 * @brief Discover Characteristics on remote GATT server.
379 * @note Function callback @ref gattc_cb_fun_t::app_gattc_char_disc_cb will be called for Characteristic Declaration(s) found.
380 * @param[in] conn_idx: Current connection index.
381 * @param[in] start_hdl: Start handle.
382 * @param[in] end_hdl: End handle.
383 * @param[in] p_char_uuid: Pointer to Characteristic UUID.If it is NULL, all characteristics are returned.
384 *
385 * @retval ::SDK_SUCCESS: Successfully start the Characteristic Discovery procedure.
386 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
387 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
388 ****************************************************************************************
389 */
390 uint16_t ble_gattc_char_discover(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl, const ble_uuid_t *p_char_uuid);
391
392 /**
393 ****************************************************************************************
394 * @brief Discover Characteristics Descriptors on remote GATT server.
395 *
396 * @note Function callback @ref gattc_cb_fun_t::app_gattc_char_desc_disc_cb will be called for Characteristic Descriptor(s) found.
397 * If the last Descriptor has not been reached, this function must be called again with an updated handle range to continue the discovery.
398 *
399 * @param[in] conn_idx: Current connection index.
400 * @param[in] start_hdl: Start handle.
401 * @param[in] end_hdl: End handle.
402 *
403 * @retval ::SDK_SUCCESS: Successfully start the Descriptor Discovery procedure.
404 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
405 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
406 ****************************************************************************************
407 */
408 uint16_t ble_gattc_char_desc_discover(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl);
409
410 /**
411 ****************************************************************************************
412 * @brief Read Attribute from remote GATT server.
413 *
414 * @note This uses either the "Read Characteristic Value" procedure or the "Read Characteristic Descriptor"
415 * procedure, depending on the attribute pointed by handle. If offset is non-zero or the
416 * attribute length is larger than the MTU, the "Read Long Characteristic Value" procedure or the
417 * "Read Long Characteristic Descriptor" procedure will be used respectively.
418 *
419 * @note Function callback @ref gattc_cb_fun_t::app_gattc_read_cb will be called when Read is finished.
420 * @param[in] conn_idx: Current connection index.
421 * @param[in] handle: Attribute handle.
422 * @param[in] offset: Value offset to start with.
423 *
424 * @retval ::SDK_SUCCESS: Successfully start the Read (Long) procedure.
425 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
426 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
427 ****************************************************************************************
428 */
429 uint16_t ble_gattc_read(uint8_t conn_idx, uint16_t handle, uint16_t offset);
430
431 /**
432 ****************************************************************************************
433 * @brief Read Attribute by UUID.
434 *
435 * @note Function callback @ref gattc_cb_fun_t::app_gattc_read_cb will be called when Read is finished.
436 * @param[in] conn_idx: Current connection index.
437 * @param[in] start_hdl: Start handle.
438 * @param[in] end_hdl: End handle.
439 * @param[in] p_char_uuid: Pointer to Characteristic UUID.
440 *
441 *
442 * @retval ::SDK_SUCCESS: Successfully start the Read using Characteristic UUID procedure.
443 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
444 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
445 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
446 ****************************************************************************************
447 */
448 uint16_t ble_gattc_read_by_uuid(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl, const ble_uuid_t *p_char_uuid);
449
450 /**
451 ****************************************************************************************
452 * @brief Initiate a Read Multiple Characteristic Values procedure
453 *
454 * @note Function callback @ref gattc_cb_fun_t::app_gattc_read_cb will be called for each handle value which is read.
455 * @param[in] conn_idx: Current connection index.
456 * @param[in] p_param: Pointer to the parameters of the value.
457 *
458 * @retval ::SDK_SUCCESS: Successfully start the Read Multiple Characteristic Values procedure.
459 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
460 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
461 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
462 ****************************************************************************************
463 */
464 uint16_t ble_gattc_read_multiple(uint8_t conn_idx, const gattc_read_multiple_t *p_param);
465
466 /**
467 ****************************************************************************************
468 * @brief Write (long) Characteristic (Descriptor) Value.
469 *
470 * @note This uses either the "Write Characteristic Value" procedure or the "Write Characteristic
471 * Descriptor" procedure, depending on the attribute pointed by handle. If offset is non-zero
472 * or the attribute length is larger than the MTU, the "Write Long Characteristic Value" procedure
473 * or the "Write Long Characteristic Descriptor" procedure will be used respectively.
474 *
475 * @note Once completed @ref gattc_cb_fun_t::app_gattc_write_cb will be called.
476 *
477 * @param[in] conn_idx: Current connection index.
478 * @param[in] handle: The handle of the attribute to be written.
479 * @param[in] offset: Offset into the attribute value to be written.
480 * @param[in] length: Length of the value data in bytes.
481 * @param[in] p_value: Pointer to the value data.
482 *
483 * @retval ::SDK_SUCCESS: Successfully start the Write procedure.
484 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
485 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
486 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
487 ****************************************************************************************
488 */
489 uint16_t ble_gattc_write(uint8_t conn_idx, uint16_t handle, uint16_t offset, uint16_t length, const uint8_t *p_value);
490
491 /**
492 ****************************************************************************************
493 * @brief Prepare Long/Reliable Write to remote GATT server.
494 *
495 * @note When this function completes, @ref gattc_cb_fun_t::app_gattc_write_cb will be called.
496 *
497 * @param[in] conn_idx: Current connection index.
498 * @param[in] handle: Attribute handle.
499 * @param[in] offset: Value offset to start with.
500 * @param[in] length: Value length.
501 * @param[in] p_value: Value data.
502 *
503 * @retval ::SDK_SUCCESS: Successfully send a Prepare Write request.
504 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
505 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
506 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
507 ****************************************************************************************
508 */
509 uint16_t ble_gattc_write_prepare(uint8_t conn_idx, uint16_t handle, uint16_t offset, uint16_t length, const uint8_t *p_value);
510
511 /**
512 ****************************************************************************************
513 * @brief Execute Reliable/Long Write to remote GATT server.
514 *
515 * @note When this function completes, @ref gattc_cb_fun_t::app_gattc_write_cb will be called.
516 *
517 * @param[in] conn_idx: Current connection index.
518 * @param[in] execute: True if data shall be written; false if cancel all prepared writes.
519 *
520 * @retval ::SDK_SUCCESS: Successfully send an Execute Write request.
521 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
522 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
523 ****************************************************************************************
524 */
525 uint16_t ble_gattc_write_execute(uint8_t conn_idx, bool execute);
526
527 /**
528 ****************************************************************************************
529 * @brief Write Attribute to remote GATT server (without response).
530 *
531 * @note If signed_write is set to false, the "Write Without Response" procedure will be used.
532 * If signed_write is set to true, the "Signed Write Without Response" procedure will be used on
533 * a link which is not encrypted.
534 * If a link is already encrypted, "Write Without Response" procedure shall be used instead of "Signed Write Without Response".
535 * @note Once completed @ref gattc_cb_fun_t::app_gattc_write_cb will be called.
536 *
537 * @param[in] conn_idx: Current connection index.
538 * @param[in] handle: Attribute handle.
539 * @param[in] signed_write: True if signed write should be used, false write without response.
540 * @param[in] length: Value length.
541 * @param[in] p_value: Value data.
542 *
543 * @retval ::SDK_SUCCESS: Successfully start the (Signed) Write Without Response procedure.
544 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
545 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
546 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
547 ****************************************************************************************
548 */
549 uint16_t ble_gattc_write_no_resp(uint8_t conn_idx, bool signed_write, uint16_t handle, uint16_t length, const uint8_t *p_value);
550
551 /**
552 ****************************************************************************************
553 * @brief Confirm Reception of Indication.
554 *
555 * @note Confirm indication which has been correctly received from the peer.
556 *
557 * @param[in] conn_idx: Current connection index.
558 * @param[in] handle: Value handle.
559 *
560 * @retval ::SDK_SUCCESS: Successfully send indication confirm.
561 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
562 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
563 ****************************************************************************************
564 */
565 uint16_t ble_gattc_indicate_cfm(uint8_t conn_idx, uint16_t handle);
566
567 /** @} */
568
569 #endif
570
571 /** @} */
572
573 /** @} */
574 /** @} */
575
gattc_browse_attr_char_t::prop
uint8_t prop
Value property.
Definition: ble_gattc.h:147
ble_gattc_ntf_ind_t
GATTC Notification and Indication value indication.
Definition: ble_gattc.h:284
gattc_write_no_resp_t
GATTC write without response structure.
Definition: ble_gattc.h:121
gattc_read_multiple_t
GATTC Read Multiple.
Definition: ble_gattc.h:137
read_multiple_t::handle
uint16_t handle
Attribute handle.
Definition: ble_gattc.h:131
read_multiple_t::len
uint16_t len
Known value: length of the handle (len shall not be set to 0).
Definition: ble_gattc.h:132
__ARRAY_EMPTY
#define __ARRAY_EMPTY
Empty Array.
Definition: gr55xx_sys_cfg.h:57
gattc_write_attr_value_t
GATTC write attribute value structure.
Definition: ble_gattc.h:110
BLE_GATTC_BROWSE_ATTR_VAL
@ BLE_GATTC_BROWSE_ATTR_VAL
Attribute Value definition.
Definition: ble_gattc.h:77
read_multiple_t
Read Multiple Handles.
Definition: ble_gattc.h:130
gattc_browse_attr_info::attr_char
gattc_browse_attr_char_t attr_char
Information about Characteristic.
Definition: ble_gattc.h:175
BLE_ATT_UUID_128_LEN
#define BLE_ATT_UUID_128_LEN
UUID length: 16 bytes.
Definition: ble_att.h:65
gattc_write_attr_value_t::offset
uint16_t offset
value offset to start with.
Definition: ble_gattc.h:112
ble_gattc_srvc_disc_t
GATT service discovery.
Definition: ble_gattc.h:232
ble_gattc_char_disc_t::count
uint16_t count
Characteristic count.
Definition: ble_gattc.h:247
ble_gattc_char_t::handle_value
uint16_t handle_value
Handle of the Characteristic Value.
Definition: ble_gattc.h:216
BLE_GATTC_BROWSE_NONE
@ BLE_GATTC_BROWSE_NONE
No Attribute Information.
Definition: ble_gattc.h:74
ble_gattc_read_multiple
uint16_t ble_gattc_read_multiple(uint8_t conn_idx, const gattc_read_multiple_t *p_param)
Initiate a Read Multiple Characteristic Values procedure.
ble_gattc_service_t::p_uuid
uint8_t * p_uuid
Service UUID.
Definition: ble_gattc.h:199
ble_gattc_write_prepare
uint16_t ble_gattc_write_prepare(uint8_t conn_idx, uint16_t handle, uint16_t offset, uint16_t length, const uint8_t *p_value)
Prepare Long/Reliable Write to remote GATT server.
gattc_browse_attr_t::attr_type
uint8_t attr_type
Attribute type.
Definition: ble_gattc.h:166
gattc_browse_attr_info::attr_type
uint8_t attr_type
Attribute type.
Definition: ble_gattc.h:174
gattc_cb_fun_t
GATTC Event callback Structures.
Definition: ble_gattc.h:293
ble_gattc_included_services_discover
uint16_t ble_gattc_included_services_discover(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl)
Discover Included Services on remote GATT server.
gattc_read_multiple_t::p_read_multiple
read_multiple_t * p_read_multiple
Pointer to the multiple attributes to be read.
Definition: ble_gattc.h:139
ble_gattc_char_disc_t
GATT characteristic discovery.
Definition: ble_gattc.h:246
ble_gattc_include_t::end_hdl
uint16_t end_hdl
End handle.
Definition: ble_gattc.h:207
gattc_write_no_resp_t::signed_write
bool signed_write
True if signed write should be used when possible/applicable.
Definition: ble_gattc.h:122
ble_gattc_char_desc_discover
uint16_t ble_gattc_char_desc_discover(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl)
Discover Characteristics Descriptors on remote GATT server.
gatt_attr_t
gatt_attr_t
GATT Client Service Discover Attribute type IDs.
Definition: ble_gattc.h:73
BLE_GATTC_BROWSE_ATTR_CHAR
@ BLE_GATTC_BROWSE_ATTR_CHAR
Characteristic Declaration.
Definition: ble_gattc.h:76
ble_gattc_char_t::handle_decl
uint16_t handle_decl
Handle of the Characteristic Declaration.
Definition: ble_gattc.h:215
gattc_read_by_uuid_t
GATTC read by characteristic UUID structure.
Definition: ble_gattc.h:100
ble_gattc_ntf_ind_t::length
uint16_t length
Attribute value length.
Definition: ble_gattc.h:286
ble_gattc_mtu_exchange
uint16_t ble_gattc_mtu_exchange(uint8_t conn_idx)
Perform MTU Exchange.
ble_gattc_desc_t::uuid_len
uint8_t uuid_len
Descriptor UUID length.
Definition: ble_gattc.h:226
ble_gattc_service_t::uuid_len
uint8_t uuid_len
Service UUID length.
Definition: ble_gattc.h:198
ble_gattc_char_t::uuid_len
uint8_t uuid_len
Characteristic UUID length.
Definition: ble_gattc.h:218
gattc_disc_char_t
GATTC discovery characteristic structure.
Definition: ble_gattc.h:90
gattc_browse_attr_info
GATTC Browse attribute information.
Definition: ble_gattc.h:173
ble_gattc_services_browse
uint16_t ble_gattc_services_browse(uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid)
Browse all Primary Services or specific Primary Service information on remote GATT server.
gattc_browse_inc_srvc_t::start_hdl
uint16_t start_hdl
Included Service start handle.
Definition: ble_gattc.h:159
gattc_read_by_uuid_t::end_hdl
uint16_t end_hdl
End handle.
Definition: ble_gattc.h:102
ble_gatt.h
BLE GATT.
gatt_evt_type_t
gatt_evt_type_t
GATT common events.
Definition: ble_gatt.h:67
gattc_disc_char_t::end_hdl
uint16_t end_hdl
End handle.
Definition: ble_gattc.h:92
gr55xx_sys_cfg.h
Define the chip configuration.
ble_gattc_browse_srvc_t
GATTC Browse service(s) indication.
Definition: ble_gattc.h:182
ble_gattc_char_t
GATT characteristic.
Definition: ble_gattc.h:214
ble_gattc_read_value_t
GATT Client Read value.
Definition: ble_gattc.h:260
gattc_write_no_resp_t::p_value
uint8_t * p_value
Value to write.
Definition: ble_gattc.h:125
ble_gattc_browse_srvc_t::uuid_len
uint8_t uuid_len
Service UUID length.
Definition: ble_gattc.h:183
ble_gattc_incl_disc_t
GATT include discovery.
Definition: ble_gattc.h:239
BLE_GATTC_BROWSE_INC_SRVC
@ BLE_GATTC_BROWSE_INC_SRVC
Included Service information.
Definition: ble_gattc.h:75
gattc_write_attr_value_t::handle
uint16_t handle
Attribute handle.
Definition: ble_gattc.h:111
gattc_browse_attr_t::uuid_len
uint8_t uuid_len
Attribute UUID length.
Definition: ble_gattc.h:167
ble_gattc_char_desc_disc_t
GATT characteristic descriptor discovery.
Definition: ble_gattc.h:253
ble_gattc_char_t::prop
uint8_t prop
Properties.
Definition: ble_gattc.h:217
ble_error.h
File that contains error codes.
ble_gattc_service_t::end_hdl
uint16_t end_hdl
End handle.
Definition: ble_gattc.h:197
gattc_browse_inc_srvc_t::end_hdl
uint16_t end_hdl
Included Service end handle.
Definition: ble_gattc.h:160
ble_gattc_write
uint16_t ble_gattc_write(uint8_t conn_idx, uint16_t handle, uint16_t offset, uint16_t length, const uint8_t *p_value)
Write (long) Characteristic (Descriptor) Value.
gattc_write_attr_value_t::p_value
uint8_t * p_value
Value to write.
Definition: ble_gattc.h:114
ble_gattc_include_t::uuid_len
uint8_t uuid_len
Service UUID length.
Definition: ble_gattc.h:208
ble_gattc_primary_services_discover
uint16_t ble_gattc_primary_services_discover(uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid)
Discover Primary Services on remote GATT server.
gattc_write_attr_value_t::length
uint16_t length
Write length.
Definition: ble_gattc.h:113
ble_gattc_write_no_resp
uint16_t ble_gattc_write_no_resp(uint8_t conn_idx, bool signed_write, uint16_t handle, uint16_t length, const uint8_t *p_value)
Write Attribute to remote GATT server (without response).
ble_gattc_read_value_t::offset
uint16_t offset
Offset of the attribute value.
Definition: ble_gattc.h:262
ble_gattc_desc_t
GATT descriptor.
Definition: ble_gattc.h:224
gattc_write_no_resp_t::length
uint16_t length
Write length.
Definition: ble_gattc.h:124
gattc_disc_char_t::p_uuid
ble_uuid_t * p_uuid
Characteristic UUID.
Definition: ble_gattc.h:93
ble_gattc_srvc_disc_t::count
uint16_t count
Service count.
Definition: ble_gattc.h:233
ble_gattc_write_t::handle
uint16_t handle
Attribute handle.
Definition: ble_gattc.h:278
ble_gattc_service_t
GATT service.
Definition: ble_gattc.h:195
ble_gattc_read
uint16_t ble_gattc_read(uint8_t conn_idx, uint16_t handle, uint16_t offset)
Read Attribute from remote GATT server.
gattc_browse_attr_char_t
GATTC Browse information about Characteristic.
Definition: ble_gattc.h:145
ble_gattc_browse_srvc_t::start_hdl
uint16_t start_hdl
Service start handle.
Definition: ble_gattc.h:185
ble_gattc_char_discover
uint16_t ble_gattc_char_discover(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl, const ble_uuid_t *p_char_uuid)
Discover Characteristics on remote GATT server.
gattc_browse_inc_srvc_t::attr_type
uint8_t attr_type
Attribute type.
Definition: ble_gattc.h:156
gattc_read_by_uuid_t::p_uuid
ble_uuid_t * p_uuid
Characteristic UUID.
Definition: ble_gattc.h:103
ble_gattc_read_value_t::p_value
uint8_t * p_value
Pointer to the attribute value data.
Definition: ble_gattc.h:264
ble_gattc_ntf_ind_t::handle
uint16_t handle
Attribute handle.
Definition: ble_gattc.h:287
ble_gattc_desc_t::p_uuid
uint8_t * p_uuid
Descriptor UUID.
Definition: ble_gattc.h:227
ble_gattc_include_t
GATT include.
Definition: ble_gattc.h:204
ble_gattc_indicate_cfm
uint16_t ble_gattc_indicate_cfm(uint8_t conn_idx, uint16_t handle)
Confirm Reception of Indication.
BLE_GATTC_BROWSE_ATTR_DESC
@ BLE_GATTC_BROWSE_ATTR_DESC
Attribute Descriptor.
Definition: ble_gattc.h:78
ble_gattc_ntf_ind_t::type
gatt_evt_type_t type
Event type.
Definition: ble_gattc.h:285
ble_gattc_char_t::p_uuid
uint8_t * p_uuid
Characteristic UUID.
Definition: ble_gattc.h:219
gattc_browse_inc_srvc_t
GATTC Browse information about Included Service.
Definition: ble_gattc.h:155
gattc_browse_attr_char_t::attr_type
uint8_t attr_type
Attribute type.
Definition: ble_gattc.h:146
gattc_read_by_uuid_t::start_hdl
uint16_t start_hdl
Start handle.
Definition: ble_gattc.h:101
ble_gattc_incl_disc_t::count
uint16_t count
Include count.
Definition: ble_gattc.h:240
gattc_browse_attr_info::attr
gattc_browse_attr_t attr
Information about Attribute.
Definition: ble_gattc.h:177
ble_att.h
Attribute Protocol.
gattc_browse_attr_info::inc_srvc
gattc_browse_inc_srvc_t inc_srvc
Information about Included Service.
Definition: ble_gattc.h:176
ble_gattc_write_t
GATT Client Write.
Definition: ble_gattc.h:277
gattc_write_no_resp_t::handle
uint16_t handle
Attribute handle.
Definition: ble_gattc.h:123
ble_gattc_include_t::p_uuid
uint8_t * p_uuid
Service UUID.
Definition: ble_gattc.h:209
gattc_disc_char_t::start_hdl
uint16_t start_hdl
Start handle.
Definition: ble_gattc.h:91
ble_uuid_t
GATT UUID structure.
Definition: ble_gatt.h:80
gattc_browse_attr_t
GATTC Browse information about Attribute.
Definition: ble_gattc.h:165
gattc_browse_attr_char_t::uuid_len
uint8_t uuid_len
Characteristic UUID length.
Definition: ble_gattc.h:149
ble_gattc_read_rsp_t
GATT value Read response.
Definition: ble_gattc.h:269
ble_gattc_read_by_uuid
uint16_t ble_gattc_read_by_uuid(uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl, const ble_uuid_t *p_char_uuid)
Read Attribute by UUID.
ble_gattc_char_desc_disc_t::count
uint16_t count
Descriptor count.
Definition: ble_gattc.h:254
gattc_read_multiple_t::handle_count
uint16_t handle_count
Handle count of the multiple attributes to be read.
Definition: ble_gattc.h:138
gattc_browse_inc_srvc_t::uuid_len
uint8_t uuid_len
Included Service UUID length.
Definition: ble_gattc.h:157
ble_gattc_include_t::start_hdl
uint16_t start_hdl
Start handle.
Definition: ble_gattc.h:206
ble_gattc_desc_t::attr_hdl
uint16_t attr_hdl
Attribute handle.
Definition: ble_gattc.h:225
ble_gattc_include_t::attr_hdl
uint16_t attr_hdl
Attribute handle.
Definition: ble_gattc.h:205
gattc_browse_attr_char_t::handle
uint16_t handle
Value handle.
Definition: ble_gattc.h:148
ble_gattc_read_value_t::length
uint16_t length
Attribute value length.
Definition: ble_gattc.h:263
ble_gattc_read_value_t::handle
uint16_t handle
Attribute handle.
Definition: ble_gattc.h:261
ble_gattc_ntf_ind_t::p_value
uint8_t * p_value
Pointer to the attribute value data.
Definition: ble_gattc.h:288
ble_gattc_write_execute
uint16_t ble_gattc_write_execute(uint8_t conn_idx, bool execute)
Execute Reliable/Long Write to remote GATT server.
ble_gattc_read_rsp_t::count
uint16_t count
Value Count.
Definition: ble_gattc.h:270
ble_gattc_service_t::start_hdl
uint16_t start_hdl
Start handle.
Definition: ble_gattc.h:196