pass_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file pass_c.h
5 *
6 * @brief 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_SRV BLE Services
40 * @{
41 */
42
43 /**
44 * @defgroup BLE_SDK_PASS_C Phone Alert Status Service Client (PASS_C)
45 * @{
46 * @brief Phone Alert Status Service Client module.
47 *
48 * @details The Phone Alert Status Service Client contains the APIs and types, which can be used
49 * by the application to discovery of Phone Alert Status Service of peer and interact with it.
50 *
51 * The application must provide an event handler to be register, then call \ref pass_client_init().
52 * After Phone Alert Status Service Client discoveries peer Phone Alert Statuse Service,
53 * application can call \ref pass_c_ctrl_point_set() to send ringer control point to peer,
54 * When ringer setting or alert status is changed, the module will receive notification from peer
55 * if notifications of them are enabled, application also can call \ref pass_c_ringer_set_read()
56 * and \ref pass_c_alert_status_read() to get new value of them on peer.
57 */
58
59 #ifndef __PASS_C_H__
60 #define __PASS_C_H__
61
62 #include "ble_prf_types.h"
63 #include "gr55xx_sys.h"
64 #include "custom_config.h"
65 #include <stdint.h>
66 #include <stdbool.h>
67
68 /**
69 * @defgroup PASS_C_MACRO Defines
70 * @{
71 */
72 /**
73 * @defgroup PASS_C_ALERT_STATUES_BIT Alert Status BIT
74 * @{
75 * @brief PASS Alert Status bits.
76 */
77 #define PASS_C_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
78 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of HRS Client connections. */
79 #define PASS_C_NO_STATE_ACTIVE (0x00) /**< Bit for no state active. */
80 #define PASS_C_RINGER_ACTIVE (0x01 << 0) /**< Bit for ringer State active. */
81 #define PASS_C_VIBRATE_ACTIVE (0x01 << 1) /**< Bit for vibrate State active. */
82 #define PASS_C_DISPLAY_ALERT_ACTIVE (0x01 << 2) /**< Bit for display Alert Status State active. */
83 #define PASS_C_ALL_STATE_ACTIVE (0x07) /**< Bit for no state active. */
84 /** @} */
85
86 #define PASS_C_RINGER_CTRL_PT_VAL_LEN 1 /**< Length of Ringer Control Point value. */
87
88 /**
89 * @defgroup PASS_C_RINGER_SETTING Ringer Setting
90 * @{
91 * @brief The Ringer Setting characteristic defines the setting of the ringer.
92 */
93 #define PASS_C_RINGER_SET_SILENT 0 /**< Ringer Silent. */
94 #define PASS_C_RINGER_SET_NORMAL 1 /**< Ringer Normal. */
95 /** @} */
96 /** @} */
97
98 /**
99 * @defgroup PASS_C_ENUM Enumerations
100 * @{
101 */
102 /**@brief Phone Alert Status Service Client Ringer Control Point. */
103 typedef enum
104 {
105 PASS_C_CTRL_PT_SILENT_MODE = 0x01, /**< Silent Mode. */
106 PASS_C_CTRL_PT_MUTE_ONCE, /**< Mute Once. */
107 PASS_C_CTRL_PT_CANCEL_SLIENT_MODE, /**< Cancel Silent Mode. */
108 } pass_c_ringer_ctrl_pt_t;
109
110 /**@brief Phone Alert Status Service Client event type. */
111 typedef enum
112 {
113 PASS_C_EVT_INVALID, /*<* PASS Client invalid event. */
114 PASS_C_EVT_DISCOVERY_COMPLETE, /**< PASS Client has found PASS service and its characteristics. */
115 PASS_C_EVT_DISCOVERY_FAIL, /**< PASS Client found PASS service failed because of invalid operation or no found at the peer. */
116 PASS_C_EVT_ALERT_STATUS_NTF_SET_SUCCESS, /**< PASS Client has set Notification of Alert Status characteristic. */
117 PASS_C_EVT_RINGER_SET_NTF_SET_SUCCESS, /**< PASS Client has set Notification of Ringer Setting characteristic. */
118 PASS_C_EVT_ALERT_STATUS_RECEIVE, /**< PASS Client has received Alert Status value (Read or Notification from peer). */
119 PASS_C_EVT_RINGER_SET_RECEIVE, /**< PASS Client has received Ringer Setting Value (Read or Notification from peer). */
120 PASS_C_EVT_CTRL_POINT_SET_SUCCESS, /**< PASS Client has writen Control Point completely. */
121 PASS_C_EVT_WRITE_OP_ERR, /**< Error occured when PASS Client writen to peer. */
122 } pass_c_evt_type_t;
123
124 /** @} */
125
126 /**
127 * @defgroup PASS_C_STRUCT Structures
128 * @{
129 */
130 /**@brief Handles on the connected peer device needed to interact with it. */
131 typedef struct
132 {
133 uint16_t pass_srvc_start_handle; /**< PASS Service start handle. */
134 uint16_t pass_srvc_end_handle; /**< PASS Service end handle. */
135 uint16_t pass_alert_status_handle; /**< PASS Alert Status characteristic Value handle which has been got from peer. */
136 uint16_t pass_alert_status_cccd_handle; /**< PASS CCCD handle of Alert Status characteristic which has been got from peer. */
137 uint16_t pass_ringer_set_handle; /**< PASS Ringer Setting characteristic Value handle which has been got from peer. */
138 uint16_t pass_ringer_set_cccd_handle; /**< PASS CCCD handle of Ringer Setting characteristic which has been got from peer. */
139 uint16_t pass_ringer_ctrl_pt_handle; /**< PASS Ringer Control Point characteristic Value handle which has been got from peer. */
140 } pass_c_handles_t;
141
142 /**@brief Phone Alert Status Client Service event. */
143 typedef struct
144 {
145 uint8_t conn_idx; /**< The index of the connection. */
146 pass_c_evt_type_t evt_type; /**< The PASS event type. */
147 union
148 {
149 uint8_t alert_status; /**< Alert status received. */
150 uint8_t ringer_set; /**< Ringer setting received. */
151 } value; /**< Value received. */
152 } pass_c_evt_t;
153 /** @} */
154
155 /**
156 * @defgroup PASS_C_TYPEDEF Typedefs
157 * @{
158 */
159 /**@brief Phone Alert Status Service Client event handler type. */
160 typedef void (*pass_c_evt_handler_t)(pass_c_evt_t *p_evt);
161 /** @} */
162
163 /**
164 * @defgroup PASS_C_FUNCTION Functions
165 * @{
166 */
167 /**
168 *****************************************************************************************
169 * @brief Register PASS Client event handler.
170 *
171 * @param[in] evt_handler: Phone Alert Status Service Client event handler.
172 *
173 * @return Result of initialization.
174 *****************************************************************************************
175 */
176 sdk_err_t pass_client_init(pass_c_evt_handler_t evt_handler);
177
178 /**
179 *****************************************************************************************
180 * @brief Discovery Phone Alert Status Service on peer.
181 *
182 * @param[in] conn_idx: Index of connection.
183 *
184 * @return Operation result.
185 *****************************************************************************************
186 */
187 sdk_err_t pass_c_disc_srvc_start(uint8_t conn_idx);
188
189 /**
190 *****************************************************************************************
191 * @brief Enable or disable peer Alert Status characteristic notify.
192 *
193 * @param[in] conn_idx: Index of connection.
194 * @param[in] is_enable: True or false.
195 *
196 * @return Operation result.
197 *****************************************************************************************
198 */
199 sdk_err_t pass_c_alert_status_notify_set(uint8_t conn_idx, bool is_enable);
200
201 /**
202 *****************************************************************************************
203 * @brief Enable or disable peer Ringer Setting characteristic notify.
204 *
205 * @param[in] conn_idx: Index of connection.
206 * @param[in] is_enable: True or false.
207 *
208 * @return Operation result.
209 *****************************************************************************************
210 */
211 sdk_err_t pass_c_ringer_set_notify_set(uint8_t conn_idx, bool is_enable);
212
213 /**
214 *****************************************************************************************
215 * @brief Read Alert Status characteristic value.
216 *
217 * @param[in] conn_idx: Index of connection.
218 *
219 * @return Operation result.
220 *****************************************************************************************
221 */
222 sdk_err_t pass_c_alert_status_read(uint8_t conn_idx);
223
224 /**
225 *****************************************************************************************
226 * @brief Read Ringer Setting characteristic value.
227 *
228 * @param[in] conn_idx: Index of connection.
229 *
230 * @return Operation result.
231 *****************************************************************************************
232 */
233 sdk_err_t pass_c_ringer_set_read(uint8_t conn_idx);
234
235 /**
236 *****************************************************************************************
237 * @brief Set Control Point characteristic value.
238 *
239 * @param[in] conn_idx: Index of connection.
240 * @param[in] ctrl_value: Value of control point.
241 *
242 * @return Operation result.
243 *****************************************************************************************
244 */
245 sdk_err_t pass_c_ctrl_point_set(uint8_t conn_idx, uint8_t ctrl_value);
246 /** @} */
247
248 #endif
249 /** @} */
250 /** @} */
251
PASS_C_EVT_RINGER_SET_NTF_SET_SUCCESS
@ PASS_C_EVT_RINGER_SET_NTF_SET_SUCCESS
PASS Client has set Notification of Ringer Setting characteristic.
Definition: pass_c.h:117
PASS_C_EVT_ALERT_STATUS_RECEIVE
@ PASS_C_EVT_ALERT_STATUS_RECEIVE
PASS Client has received Alert Status value (Read or Notification from peer).
Definition: pass_c.h:118
pass_c_alert_status_notify_set
sdk_err_t pass_c_alert_status_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer Alert Status characteristic notify.
PASS_C_EVT_DISCOVERY_FAIL
@ PASS_C_EVT_DISCOVERY_FAIL
PASS Client found PASS service failed because of invalid operation or no found at the peer.
Definition: pass_c.h:115
pass_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: pass_c.h:132
pass_c_evt_t::alert_status
uint8_t alert_status
Alert status received.
Definition: pass_c.h:149
PASS_C_EVT_WRITE_OP_ERR
@ PASS_C_EVT_WRITE_OP_ERR
Error occured when PASS Client writen to peer.
Definition: pass_c.h:121
pass_c_ringer_ctrl_pt_t
pass_c_ringer_ctrl_pt_t
Phone Alert Status Service Client Ringer Control Point.
Definition: pass_c.h:104
PASS_C_EVT_CTRL_POINT_SET_SUCCESS
@ PASS_C_EVT_CTRL_POINT_SET_SUCCESS
PASS Client has writen Control Point completely.
Definition: pass_c.h:120
pass_c_handles_t::pass_ringer_set_handle
uint16_t pass_ringer_set_handle
PASS Ringer Setting characteristic Value handle which has been got from peer.
Definition: pass_c.h:137
pass_c_handles_t::pass_alert_status_cccd_handle
uint16_t pass_alert_status_cccd_handle
PASS CCCD handle of Alert Status characteristic which has been got from peer.
Definition: pass_c.h:136
gr55xx_sys.h
GR55XX System API.
pass_c_handles_t::pass_srvc_start_handle
uint16_t pass_srvc_start_handle
PASS Service start handle.
Definition: pass_c.h:133
pass_c_alert_status_read
sdk_err_t pass_c_alert_status_read(uint8_t conn_idx)
Read Alert Status characteristic value.
pass_c_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: pass_c.h:145
pass_c_evt_t::evt_type
pass_c_evt_type_t evt_type
The PASS event type.
Definition: pass_c.h:146
PASS_C_EVT_INVALID
@ PASS_C_EVT_INVALID
Definition: pass_c.h:113
pass_client_init
sdk_err_t pass_client_init(pass_c_evt_handler_t evt_handler)
Register PASS Client event handler.
pass_c_handles_t::pass_ringer_set_cccd_handle
uint16_t pass_ringer_set_cccd_handle
PASS CCCD handle of Ringer Setting characteristic which has been got from peer.
Definition: pass_c.h:138
PASS_C_CTRL_PT_SILENT_MODE
@ PASS_C_CTRL_PT_SILENT_MODE
Silent Mode.
Definition: pass_c.h:105
pass_c_ringer_set_notify_set
sdk_err_t pass_c_ringer_set_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer Ringer Setting characteristic notify.
ble_prf_types.h
Profile/Service Common Types.
pass_c_handles_t::pass_ringer_ctrl_pt_handle
uint16_t pass_ringer_ctrl_pt_handle
PASS Ringer Control Point characteristic Value handle which has been got from peer.
Definition: pass_c.h:139
PASS_C_EVT_RINGER_SET_RECEIVE
@ PASS_C_EVT_RINGER_SET_RECEIVE
PASS Client has received Ringer Setting Value (Read or Notification from peer).
Definition: pass_c.h:119
PASS_C_CTRL_PT_MUTE_ONCE
@ PASS_C_CTRL_PT_MUTE_ONCE
Mute Once.
Definition: pass_c.h:106
PASS_C_CTRL_PT_CANCEL_SLIENT_MODE
@ PASS_C_CTRL_PT_CANCEL_SLIENT_MODE
Cancel Silent Mode.
Definition: pass_c.h:107
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
pass_c_evt_handler_t
void(* pass_c_evt_handler_t)(pass_c_evt_t *p_evt)
Phone Alert Status Service Client event handler type.
Definition: pass_c.h:160
pass_c_ctrl_point_set
sdk_err_t pass_c_ctrl_point_set(uint8_t conn_idx, uint8_t ctrl_value)
Set Control Point characteristic value.
PASS_C_EVT_DISCOVERY_COMPLETE
@ PASS_C_EVT_DISCOVERY_COMPLETE
PASS Client has found PASS service and its characteristics.
Definition: pass_c.h:114
pass_c_evt_t
Phone Alert Status Client Service event.
Definition: pass_c.h:144
pass_c_handles_t::pass_alert_status_handle
uint16_t pass_alert_status_handle
PASS Alert Status characteristic Value handle which has been got from peer.
Definition: pass_c.h:135
pass_c_evt_type_t
pass_c_evt_type_t
Phone Alert Status Service Client event type.
Definition: pass_c.h:112
pass_c_evt_t::ringer_set
uint8_t ringer_set
Ringer setting received.
Definition: pass_c.h:150
pass_c_ringer_set_read
sdk_err_t pass_c_ringer_set_read(uint8_t conn_idx)
Read Ringer Setting characteristic value.
PASS_C_EVT_ALERT_STATUS_NTF_SET_SUCCESS
@ PASS_C_EVT_ALERT_STATUS_NTF_SET_SUCCESS
PASS Client has set Notification of Alert Status characteristic.
Definition: pass_c.h:116
pass_c_disc_srvc_start
sdk_err_t pass_c_disc_srvc_start(uint8_t conn_idx)
Discovery Phone Alert Status Service on peer.
pass_c_handles_t::pass_srvc_end_handle
uint16_t pass_srvc_end_handle
PASS Service end handle.
Definition: pass_c.h:134