pass_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file pass_c.h
5 *
6 * @brief Phone Alert Status Service Client 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 "gr_includes.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 /**< Maximum number of HRS Client connections. */
78 #define PASS_C_NO_STATE_ACTIVE (0x00) /**< Bit for no state active. */
79 #define PASS_C_RINGER_ACTIVE (0x01 << 0) /**< Bit for ringer State active. */
80 #define PASS_C_VIBRATE_ACTIVE (0x01 << 1) /**< Bit for vibrate State active. */
81 #define PASS_C_DISPLAY_ALERT_ACTIVE (0x01 << 2) /**< Bit for display Alert Status State active. */
82 #define PASS_C_ALL_STATE_ACTIVE (0x07) /**< Bit for no state active. */
83 /** @} */
84
85 #define PASS_C_RINGER_CTRL_PT_VAL_LEN 1 /**< Length of Ringer Control Point value. */
86
87 /**
88 * @defgroup PASS_C_RINGER_SETTING Ringer Setting
89 * @{
90 * @brief The Ringer Setting characteristic defines the setting of the ringer.
91 */
92 #define PASS_C_RINGER_SET_SILENT 0 /**< Ringer Silent. */
93 #define PASS_C_RINGER_SET_NORMAL 1 /**< Ringer Normal. */
94 /** @} */
95 /** @} */
96
97 /**
98 * @defgroup PASS_C_ENUM Enumerations
99 * @{
100 */
101 /**@brief Phone Alert Status Service Client Ringer Control Point. */
102 typedef enum
103 {
104 PASS_C_CTRL_PT_SILENT_MODE = 0x01, /**< Silent Mode. */
105 PASS_C_CTRL_PT_MUTE_ONCE, /**< Mute Once. */
106 PASS_C_CTRL_PT_CANCEL_SLIENT_MODE, /**< Cancel Silent Mode. */
107 } pass_c_ringer_ctrl_pt_t;
108
109 /**@brief Phone Alert Status Service Client event type. */
110 typedef enum
111 {
112 PASS_C_EVT_INVALID, /*<* PASS Client invalid event. */
113 PASS_C_EVT_DISCOVERY_COMPLETE, /**< PASS Client has found PASS service and its characteristics. */
114 PASS_C_EVT_DISCOVERY_FAIL, /**< PASS Client found PASS service failed because of invalid operation or no found at the peer. */
115 PASS_C_EVT_ALERT_STATUS_NTF_SET_SUCCESS, /**< PASS Client has set Notification of Alert Status characteristic. */
116 PASS_C_EVT_RINGER_SET_NTF_SET_SUCCESS, /**< PASS Client has set Notification of Ringer Setting characteristic. */
117 PASS_C_EVT_ALERT_STATUS_RECEIVE, /**< PASS Client has received Alert Status value (Read or Notification from peer). */
118 PASS_C_EVT_RINGER_SET_RECEIVE, /**< PASS Client has received Ringer Setting Value (Read or Notification from peer). */
119 PASS_C_EVT_CTRL_POINT_SET_SUCCESS, /**< PASS Client has writen Control Point completely. */
120 PASS_C_EVT_WRITE_OP_ERR, /**< Error occured when PASS Client writen to peer. */
121 } pass_c_evt_type_t;
122
123 /** @} */
124
125 /**
126 * @defgroup PASS_C_STRUCT Structures
127 * @{
128 */
129 /**@brief Handles on the connected peer device needed to interact with it. */
130 typedef struct
131 {
132 uint16_t pass_srvc_start_handle; /**< PASS Service start handle. */
133 uint16_t pass_srvc_end_handle; /**< PASS Service end handle. */
134 uint16_t pass_alert_status_handle; /**< PASS Alert Status characteristic Value handle which has been got from peer. */
135 uint16_t pass_alert_status_cccd_handle; /**< PASS CCCD handle of Alert Status characteristic which has been got from peer. */
136 uint16_t pass_ringer_set_handle; /**< PASS Ringer Setting characteristic Value handle which has been got from peer. */
137 uint16_t pass_ringer_set_cccd_handle; /**< PASS CCCD handle of Ringer Setting characteristic which has been got from peer. */
138 uint16_t pass_ringer_ctrl_pt_handle; /**< PASS Ringer Control Point characteristic Value handle which has been got from peer. */
139 } pass_c_handles_t;
140
141 /**@brief Phone Alert Status Client Service event. */
142 typedef struct
143 {
144 uint8_t conn_idx; /**< The index of the connection. */
145 pass_c_evt_type_t evt_type; /**< The PASS event type. */
146 union
147 {
148 uint8_t alert_status; /**< Alert status received. */
149 uint8_t ringer_set; /**< Ringer setting received. */
150 } value; /**< Value received. */
151 } pass_c_evt_t;
152 /** @} */
153
154 /**
155 * @defgroup PASS_C_TYPEDEF Typedefs
156 * @{
157 */
158 /**@brief Phone Alert Status Service Client event handler type. */
159 typedef void (*pass_c_evt_handler_t)(pass_c_evt_t *p_evt);
160 /** @} */
161
162 /**
163 * @defgroup PASS_C_FUNCTION Functions
164 * @{
165 */
166 /**
167 *****************************************************************************************
168 * @brief Register PASS Client event handler.
169 *
170 * @param[in] evt_handler: Phone Alert Status Service Client event handler.
171 *
172 * @return Result of initialization.
173 *****************************************************************************************
174 */
175 sdk_err_t pass_client_init(pass_c_evt_handler_t evt_handler);
176
177 /**
178 *****************************************************************************************
179 * @brief Discovery Phone Alert Status Service on peer.
180 *
181 * @param[in] conn_idx: Index of connection.
182 *
183 * @return Operation result.
184 *****************************************************************************************
185 */
186 sdk_err_t pass_c_disc_srvc_start(uint8_t conn_idx);
187
188 /**
189 *****************************************************************************************
190 * @brief Enable or disable peer Alert Status characteristic notify.
191 *
192 * @param[in] conn_idx: Index of connection.
193 * @param[in] is_enable: True or false.
194 *
195 * @return Operation result.
196 *****************************************************************************************
197 */
198 sdk_err_t pass_c_alert_status_notify_set(uint8_t conn_idx, bool is_enable);
199
200 /**
201 *****************************************************************************************
202 * @brief Enable or disable peer Ringer Setting characteristic notify.
203 *
204 * @param[in] conn_idx: Index of connection.
205 * @param[in] is_enable: True or false.
206 *
207 * @return Operation result.
208 *****************************************************************************************
209 */
210 sdk_err_t pass_c_ringer_set_notify_set(uint8_t conn_idx, bool is_enable);
211
212 /**
213 *****************************************************************************************
214 * @brief Read Alert Status characteristic value.
215 *
216 * @param[in] conn_idx: Index of connection.
217 *
218 * @return Operation result.
219 *****************************************************************************************
220 */
221 sdk_err_t pass_c_alert_status_read(uint8_t conn_idx);
222
223 /**
224 *****************************************************************************************
225 * @brief Read Ringer Setting characteristic value.
226 *
227 * @param[in] conn_idx: Index of connection.
228 *
229 * @return Operation result.
230 *****************************************************************************************
231 */
232 sdk_err_t pass_c_ringer_set_read(uint8_t conn_idx);
233
234 /**
235 *****************************************************************************************
236 * @brief Set Control Point characteristic value.
237 *
238 * @param[in] conn_idx: Index of connection.
239 * @param[in] ctrl_value: Value of control point.
240 *
241 * @return Operation result.
242 *****************************************************************************************
243 */
244 sdk_err_t pass_c_ctrl_point_set(uint8_t conn_idx, uint8_t ctrl_value);
245 /** @} */
246
247 #endif
248 /** @} */
249 /** @} */
250
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:116
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:117
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:114
pass_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: pass_c.h:131
pass_c_evt_t::alert_status
uint8_t alert_status
Alert status received.
Definition: pass_c.h:148
PASS_C_EVT_WRITE_OP_ERR
@ PASS_C_EVT_WRITE_OP_ERR
Error occured when PASS Client writen to peer.
Definition: pass_c.h:120
pass_c_ringer_ctrl_pt_t
pass_c_ringer_ctrl_pt_t
Phone Alert Status Service Client Ringer Control Point.
Definition: pass_c.h:103
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:119
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:136
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:135
gr_includes.h
Include Files API.
pass_c_handles_t::pass_srvc_start_handle
uint16_t pass_srvc_start_handle
PASS Service start handle.
Definition: pass_c.h:132
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:144
pass_c_evt_t::evt_type
pass_c_evt_type_t evt_type
The PASS event type.
Definition: pass_c.h:145
PASS_C_EVT_INVALID
@ PASS_C_EVT_INVALID
Definition: pass_c.h:112
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:137
PASS_C_CTRL_PT_SILENT_MODE
@ PASS_C_CTRL_PT_SILENT_MODE
Silent Mode.
Definition: pass_c.h:104
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:138
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:118
PASS_C_CTRL_PT_MUTE_ONCE
@ PASS_C_CTRL_PT_MUTE_ONCE
Mute Once.
Definition: pass_c.h:105
PASS_C_CTRL_PT_CANCEL_SLIENT_MODE
@ PASS_C_CTRL_PT_CANCEL_SLIENT_MODE
Cancel Silent Mode.
Definition: pass_c.h:106
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:274
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:159
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:113
pass_c_evt_t
Phone Alert Status Client Service event.
Definition: pass_c.h:143
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:134
pass_c_evt_type_t
pass_c_evt_type_t
Phone Alert Status Service Client event type.
Definition: pass_c.h:111
pass_c_evt_t::ringer_set
uint8_t ringer_set
Ringer setting received.
Definition: pass_c.h:149
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:115
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:133