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  @addtogroup BLE_PRF_SERVER Profile Server
119  @{
120  @brief Definitions and prototypes for Profile Server interface.
121  */
122 
123 /** @addtogroup BLE_PRF_SERVER_STRUCTURES Structures
124  * @{ */
125 /**
126  * @brief GATT read request struct.
127  */
128 typedef struct
129 {
130  uint16_t handle; /**< Handle of the attribute to be read. */
132 
133 /**
134  * @brief GATT write request struct.
135  */
136 typedef struct
137 {
138  uint16_t handle; /**< Handle of the attribute to be written. */
139  uint16_t offset; /**< Offset at which the data has to be written. */
140  uint16_t length; /**< Data length to be written. */
141  uint8_t value[__ARRAY_EMPTY]; /**< Data to be written to characteristic value. */
143 
144 /**
145  * @brief GATT prepare write request struct.
146  */
147 typedef struct
148 {
149  uint16_t handle; /**< Handle of the attribute for whose value is requested. */
151 
152 /**
153  * @brief GATTS Operation Complete event structure.
154  */
155 typedef struct
156 {
157  ble_gatt_evt_type_t type; /**< Notification or indication event type. */
158  uint16_t handle; /**< Handle of the write operation, or notification/indication operation. */
160 
161 /**
162  * @brief Profile server register information structure.
163  */
164 typedef struct
165 {
166  uint16_t max_connection_nb; /**< Maximum connections the profile supports. */
167  ble_prf_manager_cbs_t* manager_cbs; /**< Profile manager callbacks. */
168  ble_evt_handler_t gatts_evt_handler; /**< GATT server event handler in relation to the specific profile. */
170 
171 /** @} */
172 
173 /** @addtogroup BLE_PRF_FUNCTIONS Functions
174 * @{ */
175 
176 /**
177  ****************************************************************************************
178  * @brief Add a server profile by providing its detailed information..
179  *
180  * @param[in] p_gatts_db: Pointer to the prf_info. See @ref ble_gatts_create_db_t.
181  * @param[in] evt_handler: Pointer to ble events handler.
182  *
183  * @retval ::SDK_SUCCESS: The profile info is recorded successfully, and the database will be created in profile initialization callback function.
184  * @retval ::SDK_ERR_POINTER_NULL: The parameter p_gatts_db or evt_handler is NULL.
185  * @retval ::SDK_ERR_NO_RESOURCES: The profile number is up to the maximum number the system can support.
186  ****************************************************************************************
187  */
189 
190 /** @} */
191 /** @} */
192 
193 
194 /**
195  @addtogroup BLE_PRF_CLIENT Profile Client
196  @{
197  @brief Definitions and prototypes for Profile Client interface.
198  */
199 
200 /**
201  @addtogroup BLE_PRF_CLIENT_FUNCTIONS Functions
202  @{
203  @brief Definitions and prototypes for Profile Client interface.
204  */
205 /**
206  ****************************************************************************************
207  * @brief Add a client profile by providing its detail information.
208  *
209  * @param[in] p_uuid: Pointer to the target service uuid. See @ref ble_uuid_t.
210  * @param[out] evt_handler: Pointer to ble events handler..
211  *
212  * @retval ::SDK_SUCCESS: The profile info is recorded successfully, and the profile ENV will be initialized in profile initialization callback function.
213  * @retval ::SDK_ERR_POINTER_NULL: The parameter p_uuid or evt_handler is NULL, or input parameters that prf_info points to are invalid.
214  * @retval ::SDK_ERR_NO_RESOURCES: The profile number is up to the maximum number the system can support.
215  ****************************************************************************************
216  */
217 uint16_t ble_gattc_prf_add(ble_uuid_t *p_uuid, ble_evt_handler_t evt_handler);
218 
219 /** @} */
220 /** @} */
221 
222 #endif
223 
224 /** @} */
225 /** @} */
ble_gatts_ntf_ind_t
GATTS Operation Complete event structure.
Definition: ble_prf.h:156
prf_server_info_t::max_connection_nb
uint16_t max_connection_nb
Definition: ble_prf.h:166
gatts_read_req_cb_t::handle
uint16_t handle
Definition: ble_prf.h:130
ble_prf_manager_cbs_t
Profile manager callbacks.
Definition: ble_prf.h:107
ble_gap_bdaddr_t
The struct of broadcast address with broadcast type.
Definition: ble_gapc.h:269
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:167
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
ble_gatt.h
BLE GATT.
gatts_read_req_cb_t
GATT read request struct.
Definition: ble_prf.h:129
prf_init_func_t
uint8_t(* prf_init_func_t)(void)
Initialization of the Profile module.
Definition: ble_prf.h:78
prf_server_info_t
Profile server register information structure.
Definition: ble_prf.h:165
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_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.
gatts_write_req_cb_t::handle
uint16_t handle
Definition: ble_prf.h:138
__ARRAY_EMPTY
#define __ARRAY_EMPTY
Definition: gr5405_sys_cfg.h:53
gatts_write_req_cb_t::offset
uint16_t offset
Definition: ble_prf.h:139
gatts_prep_write_req_cb_t
GATT prepare write request struct.
Definition: ble_prf.h:148
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
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.
gatts_prep_write_req_cb_t::handle
uint16_t handle
Definition: ble_prf.h:149
ble_prf_manager_cbs_t::init
prf_init_func_t init
Definition: ble_prf.h:108
gatts_write_req_cb_t::length
uint16_t length
Definition: ble_prf.h:140
ble_att.h
Attribute Protocol.
prf_server_info_t::gatts_evt_handler
ble_evt_handler_t gatts_evt_handler
Definition: ble_prf.h:168
ble_evt_handler_t
void(* ble_evt_handler_t)(const ble_evt_t *p_evt)
The BLE event handler type.
Definition: ble_event.h:228
ble_gatts_ntf_ind_t::handle
uint16_t handle
Definition: ble_prf.h:158
ble_gattc.h
BLE GATTC API.
ble_uuid_t
GATT UUID structure.
Definition: ble_gatt.h:81
gatts_write_req_cb_t
GATT write request struct.
Definition: ble_prf.h:137
ble_gatts_ntf_ind_t::type
ble_gatt_evt_type_t type
Definition: ble_prf.h:157