ble_prf.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file ble_prf.h
5  *
6  * @brief BLE PRF 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_PRF Profile
45  @{
46  @brief Definitions and prototypes for the profile interface.
47  */
48 
49 #ifndef __BLE_PRF_H__
50 #define __BLE_PRF_H__
51 
52 #include "ble_error.h"
53 #include "ble_att.h"
54 #include "ble_gatts.h"
55 #include "ble_gattc.h"
56 #include "ble_gatt.h"
57 #include "ble_gapc.h"
58 #include "ble_event.h"
59 
60 /**
61  @addtogroup BLE_PRF_COMMON Profile Common
62  @{
63  @brief Definitions and prototypes for Profile Common interface.
64  */
65 
66 /** @addtogroup BLE_PRF_MANAGER_TYPEDEFS Typedefs
67  * @{ */
68 /**
69 ****************************************************************************************
70 * @brief Initialization of the Profile module.
71 * @note This function performs all the initializations of the Profile module, and it will be automatically called after the ble_server_prf_add() or ble_client_prf_add() function.
72 * - Creation of database (if it's a service) and ble_gatts_srvc_db_create should be called.
73 * - Allocation of profile-required memory.
74 *
75 * @retval status code to know if profile initialization succeeds or not.
76  ****************************************************************************************
77  */
78 typedef uint8_t (*prf_init_func_t)(void);
79 
80 /**
81 ****************************************************************************************
82 * @brief Handles Connection creation. There is no need to recovery CCCD because stack will do that.
83 *
84 * @param[in] conn_idx: Connection index.
85 * @param[in] p_peer_bd_addr: The pointer for the peer identity address.
86  ****************************************************************************************
87  */
88 typedef void (*prf_on_connect_func_t)(uint8_t conn_idx, const ble_gap_bdaddr_t *p_peer_bd_addr);
89 
90 /**
91 ****************************************************************************************
92 * @brief Handles Disconnection. There is no need to recovery CCCD because stack will do that.
93 *
94 * @param[in] conn_idx: Connection index.
95 * @param[in] reason: Disconnection reason.
96  ****************************************************************************************
97  */
98 typedef void (*prf_on_disconnect_func_t)(uint8_t conn_idx, uint8_t reason);
99 
100  /** @addtogroup BLE_PRF_MANAGER_STRUCTURES Structures
101  * @{ */
102  /**
103  * @brief Profile manager callbacks.
104  */
105 /** @} */
106 typedef struct
107 {
108  prf_init_func_t init; /**< Initialization callback. See @ref prf_init_func_t. */
109  prf_on_connect_func_t on_connect; /**< Connection callback. See @ref prf_on_connect_func_t. */
110  prf_on_disconnect_func_t on_disconnect; /**< Disconnection callback. See @ref prf_on_disconnect_func_t. */
112 
113 /** @} */
114 
115 /** @} */
116 
117 
118 /**
119  @addtogroup BLE_PRF_SERVER Profile Server
120  @{
121  @brief Definitions and prototypes for Profile Server interface.
122  */
123 
124 /** @addtogroup BLE_PRF_SERVER_STRUCTURES Structures
125  * @{ */
126 /**
127  * @brief GATT read request struct.
128  */
129 typedef struct
130 {
131  uint16_t handle; /**< Handle of the attribute to be read. */
133 
134 /**
135  * @brief GATT write request struct.
136  */
137 typedef struct
138 {
139  uint16_t handle; /**< Handle of the attribute to be written. */
140  uint16_t offset; /**< Offset at which the data has to be written. */
141  uint16_t length; /**< Data length to be written. */
142  uint8_t value[__ARRAY_EMPTY]; /**< Data to be written to characteristic value. */
144 
145 /**
146  * @brief GATT prepare write request struct.
147  */
148 typedef struct
149 {
150  uint16_t handle; /**< Handle of the attribute for whose value is requested. */
152 
153 /**
154  * @brief GATTS Operation Complete event structure.
155  */
156 typedef struct
157 {
158  ble_gatt_evt_type_t type; /**< Notification or indication event type. */
159  uint16_t handle; /**< Handle of the write operation, or notification/indication operation. */
161 
162 /**
163  * @brief GATTS Multiple Variable Length Notification Operation Complete event structure.
164  */
165 typedef struct
166 {
167  uint16_t handle_count; /**< The count of handle to be notificated. */
169 
170 /**
171  * @brief GATT server callback function in relation to a profile.
172  */
173 typedef struct
174 {
175  void (*app_gatts_read_cb)(uint8_t conidx, const gatts_read_req_cb_t *p_read_req); /**< Read attribute value callback which is used when value is present in user space.
176  Function @ref ble_gatts_read_cfm should be called to send attribute value to stack.*/
177  void (*app_gatts_write_cb)(uint8_t conidx, const gatts_write_req_cb_t *p_write_req); /**< Write attribute value callback.
178  Function @ref ble_gatts_write_cfm should be called to send write attribute value status to stack no matter the value is in user's zone or BLE stack.*/
179  void (*app_gatts_prep_write_cb)(uint8_t conidx, const gatts_prep_write_req_cb_t *p_prep_req); /**< Prepare write value callback function.
180  Function @ref ble_gatts_prepare_write_cfm should be called to send prepare write attribute value status to stack no matter the value is in user's zone or BLE stack.*/
181  void (*app_gatts_ntf_ind_cb)(uint8_t conidx, uint8_t status, const ble_gatts_ntf_ind_t *p_ntf_ind); /**< Notification or indication callback function. */
182  void (*app_gatts_cccd_set_cb)(uint8_t conidx, const ble_gap_bdaddr_t *p_peer_bd_addr, uint16_t handle, uint16_t cccd_val); /**< Set CCCD value callback is called when connected with peer device. If bonded, recovery CCCD; otherwise, set default value(0x0000) for CCCD. */
183  void (*app_gatts_mult_ntf_cb)(uint8_t conidx, uint8_t status, const ble_gatts_mult_ntf_t *p_mult_ntf); /**< Multiple Variable Length Notification callback function. */
185 
186 /**
187  * @brief Profile server register information structure.
188  */
189 typedef struct
190 {
191  uint16_t max_connection_nb; /**< Maximum connections the profile supports. */
192  ble_prf_manager_cbs_t* manager_cbs; /**< Profile manager callbacks. */
193  gatts_prf_cbs_t *gatts_prf_cbs; /**< GATT server callback function in relation to the specific profile. */
194  ble_evt_handler_t gatts_evt_handler; /**< GATT server event handler in relation to the specific profile. */
196 
197 /** @} */
198 
199 /** @addtogroup BLE_PRF_FUNCTIONS Functions
200 * @{ */
201 
202 /**
203  ****************************************************************************************
204  * @brief Add a server profile by providing its detailed information..
205  *
206  * @param[in] p_gatts_db: Pointer to the prf_info. See @ref ble_gatts_create_db_t.
207  * @param[in] evt_handler: Pointer to ble events handler.
208  *
209  * @retval ::SDK_SUCCESS: The profile info is recorded successfully, and the database will be created in profile initialization callback function.
210  * @retval ::SDK_ERR_POINTER_NULL: The parameter p_gatts_db or evt_handler is NULL.
211  * @retval ::SDK_ERR_NO_RESOURCES: The profile number is up to the maximum number the system can support.
212  ****************************************************************************************
213  */
215 
216 /** @} */
217 
218 /** @} */
219 
220 
221 
222 /**
223  @addtogroup BLE_PRF_CLIENT Profile Client
224  @{
225  @brief Definitions and prototypes for Profile Client interface.
226  */
227 
228 /** @addtogroup BLE_PRF_CLIENT_STRUCTURES Structures
229  * @{ */
230 
231 /**
232  * @brief GATTC profile register to peer event info structure.
233  */
234 typedef struct
235 {
236  uint16_t start_hdl; /**< Attribute start handle. */
237  uint16_t end_hdl; /**< Attribute end handle. */
239 
240 /**
241  * @brief GATTC profile register enumeration.
242  */
243 typedef enum
244 {
245  GATTC_EVT_REGISTER, /**< GATT client event register. */
246  GATTC_EVT_UNREGISTER, /**< GATT client event unregister. */
248 
249 
250 /**@brief GATTC Profile callback Structures. */
251 typedef struct
252 {
253  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. */
254  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. */
255  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. */
256  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. */
257  void (*app_gattc_read_cb)(uint8_t conn_idx, uint8_t status, const ble_gattc_read_rsp_t *p_read_rsp); /**< Read Response callback. */
258  void (*app_gattc_write_cb)(uint8_t conn_idx, uint8_t status, uint16_t handle); /**< Write complete callback. */
259  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. */
260  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. */
261  void (*app_gattc_prf_reg_cb)(uint8_t conn_idx, uint8_t status, gattc_prf_reg_evt_t reg_evt); /**< GATT client event register complete callback. */
263 
264 /**
265  * @brief Profile client register information structure.
266  */
267 typedef struct
268 {
269  uint16_t max_connection_nb; /**< Maximum connections the profile supports. */
270  ble_prf_manager_cbs_t *manager_cbs; /**< Profile manager callbacks. */
271  gattc_prf_cbs_t *gattc_prf_cbs; /**< GATT client callback function in relation to the specific profile. */
272  ble_evt_handler_t gattc_evt_handler; /**< GATT client event handler in relation to the specific profile. */
274 
275 /** @} */
276 
277 
278 /**
279  @addtogroup BLE_PRF_CLIENT_FUNCTIONS Functions
280  @{
281  @brief Definitions and prototypes for Profile Client interface.
282  */
283 /**
284  ****************************************************************************************
285  * @brief Add a client profile by providing its detail information.
286  *
287  * @param[in] p_uuid: Pointer to the target service uuid. See @ref ble_uuid_t.
288  * @param[out] evt_handler: Pointer to ble events handler..
289  *
290  * @retval ::SDK_SUCCESS: The profile info is recorded successfully, and the profile ENV will be initialized in profile initialization callback function.
291  * @retval ::SDK_ERR_POINTER_NULL: The parameter p_uuid or evt_handler is NULL, or input parameters that prf_info points to are invalid.
292  * @retval ::SDK_ERR_NO_RESOURCES: The profile number is up to the maximum number the system can support.
293  ****************************************************************************************
294  */
295 uint16_t ble_gattc_prf_add(ble_uuid_t *p_uuid, ble_evt_handler_t evt_handler);
296 
297 
298 
299 /**
300  ****************************************************************************************
301  * @brief Profile client Browse Specific Primary Service information on remote GATT server.
302  *
303  * @note This discovery automatically searches for Primary Services, Included Services, Characteristics and Descriptors of each service.
304  * To discover one or more services only, use ble_gattc_primary_services_discover() instead.
305  * This discovery is able to search a specific Primary Service.
306  * If srvc_uuid is NULL, all services are returned.
307  *
308  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_srvc_browse_cb will be called for all attributes of each service found.
309  * After completed service handle range registeration for receiving peer device indication/notification will be executed internally.
310  * Because secondary service can't be browsed, so handle range registeration for receiving peer device indication/notification to this client
311  * profile may be necessary. App can call function ble_gattc_prf_evt_handle_register for registeration, it depends on user app.
312  * If user don't call this function, user shall call ble_gattc_prf_evt_handle_register to register handle range for receiving
313  * peer device indication/notification in specific client profile callback.
314  *
315  *
316  * @param[in] prf_id: Profile id.
317  * @param[in] conn_idx: Current connection index.
318  * @param[in] p_srvc_uuid: Pointer to Service UUID.
319  *
320  * @retval ::SDK_SUCCESS: Successfully start the Browse Service(s) procedure.
321  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
322  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
323  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
324  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
325  ****************************************************************************************
326  */
327 uint16_t ble_gattc_prf_services_browse(uint8_t prf_id, uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid);
328 
329 /**
330  ****************************************************************************************
331  * @brief Profile client Discover Primary Services on remote GATT server.
332  *
333  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_srvc_disc_cb will be called for service(s) found.
334  *
335  * @param[in] prf_id: Profile id.
336  * @param[in] conn_idx: Current connection index.
337  * @param[in] p_srvc_uuid: Pointer to Service UUID. If it is NULL, all Primary Services will be returned.
338  *
339  * @retval ::SDK_SUCCESS Successfully start the Primary Service Discovery procedure.
340  * @retval ::SDK_ERR_INVALID_PARAM Invalid parameter(s) supplied.
341  * @retval ::SDK_ERR_INVALID_CONN_IDX Invalid connection index supplied.
342  * @retval ::SDK_ERR_POINTER_NULL Invalid pointer supplied.
343  * @retval ::SDK_ERR_NO_RESOURCES Not enough resources.
344  ****************************************************************************************
345  */
346 uint16_t ble_gattc_prf_primary_services_discover(uint8_t prf_id, uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid);
347 
348 /**
349  ****************************************************************************************
350  * @brief Profile client Discover Included Services on remote GATT server.
351  *
352  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_inc_srvc_disc_cb will be called for Included Service(s) found.
353  *
354  * @param[in] prf_id: Profile id.
355  * @param[in] conn_idx: Current connection index.
356  * @param[in] start_hdl: Start handle.
357  * @param[in] end_hdl: End handle.
358  *
359  * @retval ::SDK_SUCCESS Successfully start the Relationship Discovery procedure.
360  * @retval ::SDK_ERR_INVALID_PARAM Invalid parameter(s) supplied.
361  * @retval ::SDK_ERR_INVALID_CONN_IDX Invalid connection index supplied.
362  * @retval ::SDK_ERR_INVALID_HANDLE Invalid handle supplied.
363  * @retval ::SDK_ERR_NO_RESOURCES Not enough resources.
364  ****************************************************************************************
365  */
366 uint16_t ble_gattc_prf_included_services_discover(uint8_t prf_id, uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl);
367 
368 /**
369  ****************************************************************************************
370  * @brief Profile client Discover Characteristics on remote GATT server.
371  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_char_disc_cb will be called for Characteristic Declaration(s) found.
372  * If p_disc_char is NULL, the invalid pointer error code will be returned immediately.
373  *
374  * @param[in] prf_id: Profile id.
375  * @param[in] conn_idx: Current connection index.
376  * @param[in] p_disc_char: Pointer to discover by characteristic UUID info. If it's p_uuid member is NULL, all characteristics are returned.
377  *
378  * @retval ::SDK_SUCCESS: Successfully start the Characteristic Discovery procedure.
379  * @retval ::SDK_ERR_INVALID_PARAM Invalid parameter(s) supplied.
380  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
381  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
382  * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied.
383  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
384  ****************************************************************************************
385  */
386 uint16_t ble_gattc_prf_char_discover(uint8_t prf_id, uint8_t conn_idx, ble_gattc_disc_char_t *p_disc_char);
387 
388 /**
389  ****************************************************************************************
390  * @brief Profile client Discover Characteristics Descriptors on remote GATT server.
391  *
392  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_char_desc_disc_cb will be called for Characteristic Descriptor(s) found.
393  * If the last Descriptor has not been reached, this function must be called again with an updated handle range to continue the discovery.
394  *
395  * @param[in] prf_id: Profile id.
396  * @param[in] conn_idx: Current connection index.
397  * @param[in] start_hdl: Start handle.
398  * @param[in] end_hdl: End handle.
399  *
400  * @retval ::SDK_SUCCESS: Successfully start the Descriptor Discovery procedure.
401  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
402  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
403  * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied.
404  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
405  ****************************************************************************************
406  */
407 uint16_t ble_gattc_prf_char_desc_discover(uint8_t prf_id, uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl);
408 
409 /**
410  ****************************************************************************************
411  * @brief Profile client Read Attribute from remote GATT server.
412  *
413  * @note This uses either the "Read Characteristic Value" procedure or the "Read Characteristic Descriptor"
414  * procedure, depending on the attribute pointed by handle. If offset is non-zero or the
415  * attribute length is larger than the MTU, the "Read Long Characteristic Value" procedure or the
416  * "Read Long Characteristic Descriptor" procedure will be used respectively.
417  *
418  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_read_cb will be called when Read is finished.
419  *
420  * @param[in] prf_id: Profile id.
421  * @param[in] conn_idx: Current connection index.
422  * @param[in] handle: Attribute handle.
423  * @param[in] offset: Value offset to start with.
424  *
425  * @retval ::SDK_SUCCESS: Successfully start the Read (Long) procedure.
426  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
427  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
428  * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied.
429  * @retval ::SDK_ERR_INVALID_OFFSET: Offset exceeds the current attribute value length.
430  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
431  ****************************************************************************************
432  */
433 uint16_t ble_gattc_prf_read(uint8_t prf_id, uint8_t conn_idx, uint16_t handle, uint16_t offset);
434 
435 /**
436  ****************************************************************************************
437  * @brief Profile client Read Attribute by UUID.
438  *
439  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_read_cb will be called when Read is finished.
440  *
441  * @param[in] prf_id: Profile id.
442  * @param[in] conn_idx: Current connection index.
443  * @param[in] p_read_by_uuid: Pointer to Read by Characteristic UUID info.
444  *
445  * @retval ::SDK_SUCCESS: Successfully start the Read Using Characteristic UUID procedure.
446  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
447  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
448  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
449  * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied.
450  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
451  ****************************************************************************************
452  */
453 uint16_t ble_gattc_prf_read_by_uuid(uint8_t prf_id, uint8_t conn_idx, ble_gattc_read_by_uuid_t *p_read_by_uuid);
454 
455 /**
456  ****************************************************************************************
457  * @brief Profile client Initiate a Read Multiple Characteristic Values procedure
458  *
459  * @note Function callback @ref gattc_prf_cbs_t::app_gattc_read_cb will be called for each handle value which is read.
460  * If set handle len 0, a Read Multiple Variable Length Characteristic Values procedure will be Initiated, this procesure is only
461  * support on version >= 5.2.
462  *
463  * @param[in] prf_id: Profile id.
464  * @param[in] conn_idx: Current connection index.
465  * @param[in] p_param: Pointer to the parameters of the value.
466  *
467  * @retval ::SDK_SUCCESS: Successfully start the Read Multiple Characteristic Values procedure.
468  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
469  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
470  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
471  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
472  ****************************************************************************************
473  */
474 uint16_t ble_gattc_prf_read_multiple(uint8_t prf_id, uint8_t conn_idx, const ble_gattc_read_multiple_t *p_param);
475 
476 /**
477  ****************************************************************************************
478  * @brief Profile client Write (Long) Characteristic (Descriptor) Value.
479  *
480  * @note This uses either the "Write Characteristic Value" procedure or the "Write Characteristic
481  * Descriptor" procedure, depending on the attribute pointed by handle. If offset is non-zero
482  * or the attribute length is larger than the MTU, the "Write Long Characteristic Value" procedure
483  * or the "Write Long Characteristic Descriptor" procedure will be used respectively.
484  *
485  * @note Once completed @ref gattc_prf_cbs_t::app_gattc_write_cb will be called.
486  *
487  * @param[in] prf_id: Profile id.
488  * @param[in] conn_idx: Current connection index.
489  * @param[in] p_write_attr_value: Pointer to the write attribue value info.
490  *
491  * @retval ::SDK_SUCCESS: Successfully start the Write procedure.
492  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
493  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
494  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
495  * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied.
496  * @retval ::SDK_ERR_INVALID_OFFSET: Offset exceeds the current attribute value length.
497  * @retval ::SDK_ERR_INVALID_DATA_LENGTH: Invalid data length supplied.
498  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
499  ****************************************************************************************
500  */
501 uint16_t ble_gattc_prf_write(uint8_t prf_id, uint8_t conn_idx, ble_gattc_write_attr_value_t *p_write_attr_value);
502 
503 /**
504  ****************************************************************************************
505  * @brief Profile client Prepare Long/Reliable Write to remote GATT server.
506  * @note Once completed @ref gattc_prf_cbs_t::app_gattc_write_cb will be called.
507  *
508  * @param[in] prf_id: Profile id.
509  * @param[in] conn_idx: Current connection index.
510  * @param[in] p_write_attr_value: Pointer to the write attribue value info.
511  *
512  * @retval ::SDK_SUCCESS: Successfully start the Write procedure.
513  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
514  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
515  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
516  * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied.
517  * @retval ::SDK_ERR_INVALID_OFFSET: Offset exceeds the current attribute value length.
518  * @retval ::SDK_ERR_INVALID_DATA_LENGTH: Invalid data length supplied.
519  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
520  ****************************************************************************************
521  */
522  uint16_t ble_gattc_prf_write_prepare(uint8_t prf_id, uint8_t conn_idx, ble_gattc_write_attr_value_t *p_write_attr_value);
523 
524 /**
525  ****************************************************************************************
526  * @brief Profile client Execute Reliable/Long Write to remote GATT server.
527  *
528  * @note Once completed @ref gattc_prf_cbs_t::app_gattc_write_cb will be called.
529  *
530  * @param[in] prf_id: Profile id.
531  * @param[in] conn_idx: Current connection index.
532  * @param[in] execute: True if data shall be written; False if cancel all prepared writes.
533  *
534  * @retval ::SDK_SUCCESS: Successfully send an Execute Write request.
535  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
536  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
537  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
538  ****************************************************************************************
539  */
540 uint16_t ble_gattc_prf_write_execute(uint8_t prf_id, uint8_t conn_idx, bool execute);
541 
542 /**
543  ****************************************************************************************
544  * @brief Profile client Write Attribute to remote GATT server (without response).
545  *
546  * @note If signed_write is set to false, the "Write Without Response" procedure will be used.
547  * If signed_write is set to true, the "Signed Write Without Response" procedure will be used on
548  * a link which is not encrypted.
549  * If a link is already encrypted, "Write Without Response" procedure shall be used instead of "Signed Write Without Response".
550  * @note Once completed @ref gattc_prf_cbs_t::app_gattc_write_cb will be called.
551  *
552  * @param[in] prf_id: Profile id.
553  * @param[in] conn_idx: Current connection index.
554  * @param[in] p_write_no_resp: Pointer to the write without response info.
555  *
556  * @retval ::SDK_SUCCESS Successfully start the (Signed) Write Without Response procedure.
557  * @retval ::SDK_ERR_INVALID_PARAM Invalid parameter(s) supplied.
558  * @retval ::SDK_ERR_INVALID_CONN_IDX Invalid connection index supplied.
559  * @retval ::SDK_ERR_POINTER_NULL Invalid pointer supplied.
560  * @retval ::SDK_ERR_INVALID_HANDLE Invalid handle supplied.
561  * @retval ::SDK_ERR_NO_RESOURCES Not enough resources.
562  ****************************************************************************************
563  */
564 uint16_t ble_gattc_prf_write_no_resp(uint8_t prf_id, uint8_t conn_idx, ble_gattc_write_no_resp_t *p_write_no_resp);
565 
566 /**
567  ****************************************************************************************
568  * @brief Profile client Confirm Reception of Indication.
569  *
570  * @note Confirm indication which has been correctly received from the peer.
571  *
572  * @param[in] prf_id Profile id.
573  * @param[in] conn_idx: Current connection index.
574  * @param[in] handle: Value handle.
575  *
576  * @retval ::SDK_SUCCESS: Successfully send a Confirm Reception of Indication request.
577  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter(s) supplied.
578  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
579  * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied.
580  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
581  ****************************************************************************************
582  */
583 uint16_t ble_gattc_prf_indicate_cfm(uint8_t prf_id, uint8_t conn_idx, uint16_t handle);
584 
585 
586 /**
587  ****************************************************************************************
588  * @brief Profile client Register Indication/Notification event.
589  *
590  * @note Registration to peer device events (Indication/Notification) for specific client profile.
591  * Once completed @ref gattc_prf_cbs_t::app_gattc_prf_reg_cb with type: @ref GATTC_EVT_UNREGISTER will be called.
592  * If user don't call ble_gattc_prf_services_browse, user shall call this function to register handle range for receiving
593  * peer device indication/notification in specific client profile callback.
594  *
595  * @param[in] prf_id: Profile id.
596  * @param[in] conn_idx: Current connection index.
597  * @param[in] env: Pointer to the profile registeration event info.
598  *
599  * @retval ::SDK_SUCCESS Successfully register Indication/Notification event.
600  * @retval ::SDK_ERR_INVALID_PARAM Invalid parameter(s) supplied.
601  * @retval ::SDK_ERR_INVALID_CONN_IDX Invalid connection index supplied.
602  * @retval ::SDK_ERR_POINTER_NULL Invalid pointer supplied.
603  * @retval ::SDK_ERR_INVALID_HANDLE Invalid handle supplied.
604  * @retval ::SDK_ERR_NO_RESOURCES Not enough resources.
605  ****************************************************************************************
606  */
607 uint16_t ble_gattc_prf_evt_handle_register(uint8_t prf_id, uint8_t conn_idx, gattc_prf_reg_peer_evt_t *env);
608 
609 /**
610  ****************************************************************************************
611  * @brief Profile client Unregister Indication/Notification event.
612  *
613  * @note Unregistration to peer device events (Indication/Notification) for specific client profile.
614  * Once completed @ref gattc_prf_cbs_t::app_gattc_prf_reg_cb with type: @ref GATTC_EVT_UNREGISTER will be called.
615  *
616  * @param[in] prf_id: Profile id.
617  * @param[in] conn_idx: Current connection index.
618  * @param[in] env: Pointer to the profile registeration event info.
619  *
620  * @retval ::SDK_SUCCESS Successfully register Indication/Notification event.
621  * @retval ::SDK_ERR_INVALID_PARAM Invalid parameter(s) supplied.
622  * @retval ::SDK_ERR_INVALID_CONN_IDX Invalid connection index supplied.
623  * @retval ::SDK_ERR_POINTER_NULL Invalid pointer supplied.
624  * @retval ::SDK_ERR_INVALID_HANDLE Invalid handle supplied.
625  * @retval ::SDK_ERR_NO_RESOURCES Not enough resources.
626  ****************************************************************************************
627  */
628 uint16_t ble_gattc_prf_evt_handle_unregister(uint8_t prf_id, uint8_t conn_idx, gattc_prf_reg_peer_evt_t *env);
629 
630 /** @} */
631 /** @} */
632 
633 #endif
634 
635 /** @} */
636 /** @} */
ble_gattc_prf_read
uint16_t ble_gattc_prf_read(uint8_t prf_id, uint8_t conn_idx, uint16_t handle, uint16_t offset)
Profile client Read Attribute from remote GATT server.
ble_gatts_ntf_ind_t
GATTS Operation Complete event structure.
Definition: ble_prf.h:157
ble_gattc_ntf_ind_t
GATTC Notification and Indication value indication.
Definition: ble_gattc.h:295
prf_server_info_t::max_connection_nb
uint16_t max_connection_nb
Definition: ble_prf.h:191
prf_client_info_t::max_connection_nb
uint16_t max_connection_nb
Definition: ble_prf.h:269
gatts_read_req_cb_t::handle
uint16_t handle
Definition: ble_prf.h:131
ble_gattc_srvc_disc_t
GATT service discovery.
Definition: ble_gattc.h:243
ble_prf_manager_cbs_t
Profile manager callbacks.
Definition: ble_prf.h:107
prf_client_info_t
Profile client register information structure.
Definition: ble_prf.h:268
ble_gap_bdaddr_t
The struct of broadcast address with broadcast type.
Definition: ble_gapc.h:304
ble_gattc_prf_evt_handle_unregister
uint16_t ble_gattc_prf_evt_handle_unregister(uint8_t prf_id, uint8_t conn_idx, gattc_prf_reg_peer_evt_t *env)
Profile client Unregister Indication/Notification event.
ble_gattc_char_disc_t
GATT characteristic discovery.
Definition: ble_gattc.h:257
prf_on_disconnect_func_t
void(* prf_on_disconnect_func_t)(uint8_t conn_idx, uint8_t reason)
Handles Disconnection. There is no need to recovery CCCD because stack will do that.
Definition: ble_prf.h:98
prf_server_info_t::manager_cbs
ble_prf_manager_cbs_t * manager_cbs
Definition: ble_prf.h:192
GATTC_EVT_REGISTER
@ GATTC_EVT_REGISTER
Definition: ble_prf.h:245
ble_gattc_prf_primary_services_discover
uint16_t ble_gattc_prf_primary_services_discover(uint8_t prf_id, uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid)
Profile client Discover Primary Services on remote GATT server.
ble_prf_manager_cbs_t::on_connect
prf_on_connect_func_t on_connect
Definition: ble_prf.h:109
ble_gatts_create_db_t
Parameter of Added service description.
Definition: ble_gatts.h:282
ble_gatts.h
BLE GATTS API.
ble_prf_manager_cbs_t::on_disconnect
prf_on_disconnect_func_t on_disconnect
Definition: ble_prf.h:110
prf_on_connect_func_t
void(* prf_on_connect_func_t)(uint8_t conn_idx, const ble_gap_bdaddr_t *p_peer_bd_addr)
Handles Connection creation. There is no need to recovery CCCD because stack will do that.
Definition: ble_prf.h:88
prf_client_info_t::gattc_prf_cbs
gattc_prf_cbs_t * gattc_prf_cbs
Definition: ble_prf.h:271
ble_gattc_prf_indicate_cfm
uint16_t ble_gattc_prf_indicate_cfm(uint8_t prf_id, uint8_t conn_idx, uint16_t handle)
Profile client Confirm Reception of Indication.
ble_gatt.h
BLE GATT.
GATTC_EVT_UNREGISTER
@ GATTC_EVT_UNREGISTER
Definition: ble_prf.h:246
gatts_read_req_cb_t
GATT read request struct.
Definition: ble_prf.h:130
ble_gatts_mult_ntf_t
GATTS Multiple Variable Length Notification Operation Complete event structure.
Definition: ble_prf.h:166
prf_init_func_t
uint8_t(* prf_init_func_t)(void)
Initialization of the Profile module.
Definition: ble_prf.h:78
ble_gattc_browse_srvc_t
GATTC Browse service(s) indication.
Definition: ble_gattc.h:192
prf_server_info_t
Profile server register information structure.
Definition: ble_prf.h:190
ble_gattc_prf_included_services_discover
uint16_t ble_gattc_prf_included_services_discover(uint8_t prf_id, uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl)
Profile client Discover Included Services on remote GATT server.
ble_gattc_prf_add
uint16_t ble_gattc_prf_add(ble_uuid_t *p_uuid, ble_evt_handler_t evt_handler)
Add a client profile by providing its detail information.
ble_gattc_write_no_resp_t
GATTC write without response structure.
Definition: ble_gattc.h:132
ble_gatts_mult_ntf_t::handle_count
uint16_t handle_count
Definition: ble_prf.h:167
ble_gattc_incl_disc_t
GATT include discovery.
Definition: ble_gattc.h:250
ble_gattc_prf_read_by_uuid
uint16_t ble_gattc_prf_read_by_uuid(uint8_t prf_id, uint8_t conn_idx, ble_gattc_read_by_uuid_t *p_read_by_uuid)
Profile client Read Attribute by UUID.
ble_gattc_char_desc_disc_t
GATT characteristic descriptor discovery.
Definition: ble_gattc.h:264
ble_gatts_prf_add
sdk_err_t ble_gatts_prf_add(ble_gatts_create_db_t *p_gatts_db, ble_evt_handler_t evt_handler)
Add a server profile by providing its detailed information..
ble_error.h
File that contains error codes.
ble_gapc.h
BLE GAPC API.
gattc_prf_reg_peer_evt_t::start_hdl
uint16_t start_hdl
Definition: ble_prf.h:236
ble_gattc_prf_evt_handle_register
uint16_t ble_gattc_prf_evt_handle_register(uint8_t prf_id, uint8_t conn_idx, gattc_prf_reg_peer_evt_t *env)
Profile client Register Indication/Notification event.
gattc_prf_reg_peer_evt_t
GATTC profile register to peer event info structure.
Definition: ble_prf.h:235
gatts_write_req_cb_t::handle
uint16_t handle
Definition: ble_prf.h:139
__ARRAY_EMPTY
#define __ARRAY_EMPTY
Definition: gr533x_sys_cfg.h:53
gatts_write_req_cb_t::offset
uint16_t offset
Definition: ble_prf.h:140
ble_gattc_prf_read_multiple
uint16_t ble_gattc_prf_read_multiple(uint8_t prf_id, uint8_t conn_idx, const ble_gattc_read_multiple_t *p_param)
Profile client Initiate a Read Multiple Characteristic Values procedure.
gatts_prep_write_req_cb_t
GATT prepare write request struct.
Definition: ble_prf.h:149
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:257
prf_server_info_t::gatts_prf_cbs
gatts_prf_cbs_t * gatts_prf_cbs
Definition: ble_prf.h:193
gattc_prf_reg_peer_evt_t::end_hdl
uint16_t end_hdl
Definition: ble_prf.h:237
ble_gatt_evt_type_t
ble_gatt_evt_type_t
GATT common events.
Definition: ble_gatt.h:67
ble_event.h
BLE event header files.
ble_gattc_prf_write
uint16_t ble_gattc_prf_write(uint8_t prf_id, uint8_t conn_idx, ble_gattc_write_attr_value_t *p_write_attr_value)
Profile client Write (Long) Characteristic (Descriptor) Value.
gatts_prep_write_req_cb_t::handle
uint16_t handle
Definition: ble_prf.h:150
gattc_prf_reg_evt_t
gattc_prf_reg_evt_t
GATTC profile register enumeration.
Definition: ble_prf.h:244
ble_prf_manager_cbs_t::init
prf_init_func_t init
Definition: ble_prf.h:108
ble_gattc_write_attr_value_t
GATTC write attribute value structure.
Definition: ble_gattc.h:121
ble_gattc_prf_write_execute
uint16_t ble_gattc_prf_write_execute(uint8_t prf_id, uint8_t conn_idx, bool execute)
Profile client Execute Reliable/Long Write to remote GATT server.
ble_gattc_prf_write_prepare
uint16_t ble_gattc_prf_write_prepare(uint8_t prf_id, uint8_t conn_idx, ble_gattc_write_attr_value_t *p_write_attr_value)
Profile client Prepare Long/Reliable Write to remote GATT server.
ble_gattc_read_by_uuid_t
GATTC read by characteristic UUID structure.
Definition: ble_gattc.h:111
gatts_write_req_cb_t::length
uint16_t length
Definition: ble_prf.h:141
ble_att.h
Attribute Protocol.
prf_server_info_t::gatts_evt_handler
ble_evt_handler_t gatts_evt_handler
Definition: ble_prf.h:194
ble_evt_handler_t
void(* ble_evt_handler_t)(const ble_evt_t *p_evt)
The BLE event handler type.
Definition: ble_event.h:226
ble_gatts_ntf_ind_t::handle
uint16_t handle
Definition: ble_prf.h:159
gatts_prf_cbs_t
GATT server callback function in relation to a profile.
Definition: ble_prf.h:174
ble_gattc.h
BLE GATTC API.
prf_client_info_t::manager_cbs
ble_prf_manager_cbs_t * manager_cbs
Definition: ble_prf.h:270
ble_uuid_t
GATT UUID structure.
Definition: ble_gatt.h:81
ble_gattc_prf_char_desc_discover
uint16_t ble_gattc_prf_char_desc_discover(uint8_t prf_id, uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl)
Profile client Discover Characteristics Descriptors on remote GATT server.
ble_gattc_read_rsp_t
GATT value Read response.
Definition: ble_gattc.h:280
ble_gattc_prf_char_discover
uint16_t ble_gattc_prf_char_discover(uint8_t prf_id, uint8_t conn_idx, ble_gattc_disc_char_t *p_disc_char)
Profile client Discover Characteristics on remote GATT server.
ble_gattc_read_multiple_t
GATTC Read Multiple.
Definition: ble_gattc.h:148
ble_gattc_prf_services_browse
uint16_t ble_gattc_prf_services_browse(uint8_t prf_id, uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid)
Profile client Browse Specific Primary Service information on remote GATT server.
gattc_prf_cbs_t
GATTC Profile callback Structures.
Definition: ble_prf.h:252
ble_gattc_prf_write_no_resp
uint16_t ble_gattc_prf_write_no_resp(uint8_t prf_id, uint8_t conn_idx, ble_gattc_write_no_resp_t *p_write_no_resp)
Profile client Write Attribute to remote GATT server (without response).
prf_client_info_t::gattc_evt_handler
ble_evt_handler_t gattc_evt_handler
Definition: ble_prf.h:272
gatts_write_req_cb_t
GATT write request struct.
Definition: ble_prf.h:138
ble_gatts_ntf_ind_t::type
ble_gatt_evt_type_t type
Definition: ble_prf.h:158
ble_gattc_disc_char_t
GATTC discovery characteristic structure.
Definition: ble_gattc.h:101