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. */
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. */
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. */
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  */
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  */
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  */
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  */
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
Definition: pass_c.h:116
PASS_C_EVT_ALERT_STATUS_RECEIVE
@ PASS_C_EVT_ALERT_STATUS_RECEIVE
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
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
Definition: pass_c.h:148
PASS_C_EVT_WRITE_OP_ERR
@ PASS_C_EVT_WRITE_OP_ERR
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
Definition: pass_c.h:119
pass_c_handles_t::pass_ringer_set_handle
uint16_t pass_ringer_set_handle
Definition: pass_c.h:136
pass_c_handles_t::pass_alert_status_cccd_handle
uint16_t pass_alert_status_cccd_handle
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
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
Definition: pass_c.h:144
pass_c_evt_t::evt_type
pass_c_evt_type_t evt_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
Definition: pass_c.h:137
PASS_C_CTRL_PT_SILENT_MODE
@ PASS_C_CTRL_PT_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
Definition: pass_c.h:138
PASS_C_EVT_RINGER_SET_RECEIVE
@ PASS_C_EVT_RINGER_SET_RECEIVE
Definition: pass_c.h:118
PASS_C_CTRL_PT_MUTE_ONCE
@ PASS_C_CTRL_PT_MUTE_ONCE
Definition: pass_c.h:105
PASS_C_CTRL_PT_CANCEL_SLIENT_MODE
@ PASS_C_CTRL_PT_CANCEL_SLIENT_MODE
Definition: pass_c.h:106
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
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
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
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
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
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
Definition: pass_c.h:133