pass.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file pass.h
5 *
6 * @brief Phone Alert Status Service 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 * @addtogroup BLE_SRV BLE Services
39 * @{
40 * @brief Definitions and prototypes for the BLE Service interface.
41 */
42
43 /**
44 * @defgroup BLE_SDK_PASS Phone Alert Status Service (PASS)
45 * @{
46 * @brief Phone Alert Status Service module.
47 *
48 * @details The Phone Alert Status Service shall expose the Alert Status characteristic and the
49 * Ringer Setting characteristic, and may expose the Ringer Control Point characteristic.
50 *
51 * After \ref pass_init_t variable is intialized, the application must call \ref pass_service_init()
52 * to add Phone Alert Status Service and Alert Status, Ringer Setting and Ringer Control Point
53 * characteristics to the BLE Stack database according to \ref pass_init_t.char_mask.
54 */
55
56 #ifndef __PASS_H__
57 #define __PASS_H__
58
59 #include "gr_includes.h"
60 #include "custom_config.h"
61 #include <stdint.h>
62 #include <stdbool.h>
63
64 /**
65 * @defgroup PASS_MACRO Defines
66 * @{
67 */
68 #define PASS_CONNECTION_MAX 10 /**< Maximum number of Phone Alert Status Service connections. */
69 #define PASS_ALERT_STATUS_VAL_LEN 1 /**< Length of Alert Status value. */
70 #define PASS_RINGER_SET_VAL_LEN 1 /**< Length of Ringer Setting value. */
71 #define PASS_RINGER_CTRL_PT_VAL_LEN 1 /**< Length of Ringer Control Point value. */
72
73 /**
74 * @defgroup PASS_CHAR_MASK Characteristics Mask
75 * @{
76 * @brief Bit masks for the initialization of \ref pass_init_t.char_mask.
77 */
78 #define PASS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in PASS. */
79 #define PASS_CHAR_RING_CTRL_PT_SUP 0x0180 /**< Bit mask for Ringer Control Point characteristic in PASS. */
80 #define PASS_CHAR_FULL 0x01ff /**< Bit mask of the full characteristic. */
81 /** @} */
82
83 /**
84 * @defgroup PASS_ALERT_STATUES_BIT Alert Status BIT
85 * @{
86 * @brief PASS Alert Status bits.
87 */
88 #define PASS_NO_STATE_ACTIVE (0x00) /**< Bit for no state active. */
89 #define PASS_RINGER_ACTIVE (0x01 << 0) /**< Bit for ringer State active. */
90 #define PASS_VIBRATE_ACTIVE (0x01 << 1) /**< Bit for vibrate State active. */
91 #define PASS_DISPLAY_ALERT_ACTIVE (0x01 << 2) /**< Bit for display Alert Status State active. */
92 #define PASS_ALL_STATE_ACTIVE (0x07) /**< Bit for no state active. */
93 /** @} */
94
95 /**
96 * @defgroup PASS_RINGER_SETTING Ringer Setting
97 * @{
98 * @brief The Ringer Setting characteristic defines the setting of the ringer.
99 */
100 #define PASS_RINGER_SET_SILENT 0 /**< Ringer Silent. */
101 #define PASS_RINGER_SET_NORMAL 1 /**< Ringer Normal. */
102 /** @} */
103 /** @} */
104
105 /**
106 * @defgroup PASS_ENUM Enumerations
107 * @{
108 */
109 /**@brief Phone Alert Status Service Ringer Control Point. */
110 typedef enum
111 {
112 PASS_CTRL_PT_SILENT_MODE = 0x01, /**< Silent Mode. */
113 PASS_CTRL_PT_MUTE_ONCE, /**< Mute Once. */
114 PASS_CTRL_PT_CANCEL_SLIENT_MODE, /**< Cancel Silent Mode. */
115 } pass_ringer_ctrl_pt_t;
116
117 /**@brief Phone Alert Status Service event type. */
118 typedef enum
119 {
120 PASS_EVT_INVALID, /**< Invalid PASS event type. */
121 PASS_EVT_ALERT_STATUS_NTF_ENABLE, /**< Alert Status notification is enabled. */
122 PASS_EVT_ALERT_STATUS_NTF_DISABLE, /**< Alert Status notification is disabled. */
123 PASS_EVT_RINGER_SET_NTF_ENABLE, /**< Ringer Setting notification is enabled. */
124 PASS_EVT_RINGER_SET_NTF_DISABLE, /**< Ringer Setting notification is disabled. */
125 PASS_EVT_SILENT_MODE_SET, /**< Set silent mode. */
126 PASS_EVT_MUTE_ONCE_SET, /**< Set mute once. */
127 PASS_EVT_SILENT_MODE_CANCEL, /**< Cancel silent mode. */
128 } pass_evt_type_t;
129 /** @} */
130
131 /**
132 * @defgroup PASS_STRUCT Structures
133 * @{
134 */
135 /**@brief Phone Alert Status Service event. */
136 typedef struct
137 {
138 uint8_t conn_idx; /**< The index of the connection. */
139 pass_evt_type_t evt_type; /**< The CTS event type. */
140 } pass_evt_t;
141 /** @} */
142
143 /**
144 * @defgroup PASS_TYPEDEF Typedefs
145 * @{
146 */
147 /**@brief Phone Alert Status Service event handler type.*/
148 typedef void (*pass_evt_handler_t)(pass_evt_t *p_evt);
149 /** @} */
150
151 /**
152 * @defgroup PASS_STRUCT Structures
153 * @{
154 */
155 /**@brief Phone Alert Status Service init stucture. This contains all option and data needed for initialization of the service. */
156 typedef struct
157 {
158 pass_evt_handler_t evt_handler; /**< Phone Alert Status Service event handler. */
159 uint16_t char_mask; /**< Initial mask of supported characteristics, and configured with \ref PASS_CHAR_MASK. */
160 uint8_t alert_status; /**< Initial alert status. */
161 uint8_t ringer_setting; /**< Initial ringer setting. */
162 } pass_init_t;
163 /** @} */
164
165 /**
166 * @defgroup PASS_FUNCTION Functions
167 * @{
168 */
169 /**
170 *****************************************************************************************
171 * @brief Initialize a Phone Alert Status Service instance and add in the DB.
172 *
173 * @param[in] p_pass_init: Pointer to PASS Service initialization variable.
174 *
175 * @return Result of service initialization.
176 *****************************************************************************************
177 */
178 sdk_err_t pass_service_init(pass_init_t *p_pass_init);
179
180 /**
181 *****************************************************************************************
182 * @brief Get Ringer Setting value.
183 *
184 * @return Current Ringer Setting value.
185 *****************************************************************************************
186 */
187 uint8_t pass_ringer_setting_get(void);
188
189 /**
190 *****************************************************************************************
191 * @brief Set Ringer Setting value.
192 *
193 * @param[in] conn_idx: Connnection index.
194 * @param[in] new_setting: New Ringer Setting value.
195 *****************************************************************************************
196 */
197 void pass_ringer_setting_set(uint8_t conn_idx, uint8_t new_setting);
198
199 /**
200 *****************************************************************************************
201 * @brief Set Alert Status value.
202 *
203 * @param[in] conn_idx: Connnection index.
204 * @param[in] new_status: New Alert Status value.
205 *****************************************************************************************
206 */
207 void pass_alert_status_set(uint8_t conn_idx, uint8_t new_status);
208 /** @} */
209
210 #endif
211 /** @} */
212 /** @} */
213
pass_ringer_ctrl_pt_t
pass_ringer_ctrl_pt_t
Phone Alert Status Service Ringer Control Point.
Definition: pass.h:111
PASS_EVT_RINGER_SET_NTF_ENABLE
@ PASS_EVT_RINGER_SET_NTF_ENABLE
Ringer Setting notification is enabled.
Definition: pass.h:123
PASS_CTRL_PT_MUTE_ONCE
@ PASS_CTRL_PT_MUTE_ONCE
Mute Once.
Definition: pass.h:113
PASS_EVT_RINGER_SET_NTF_DISABLE
@ PASS_EVT_RINGER_SET_NTF_DISABLE
Ringer Setting notification is disabled.
Definition: pass.h:124
PASS_EVT_ALERT_STATUS_NTF_DISABLE
@ PASS_EVT_ALERT_STATUS_NTF_DISABLE
Alert Status notification is disabled.
Definition: pass.h:122
pass_init_t
Phone Alert Status Service init stucture.
Definition: pass.h:157
pass_ringer_setting_get
uint8_t pass_ringer_setting_get(void)
Get Ringer Setting value.
pass_evt_t
Phone Alert Status Service event.
Definition: pass.h:137
pass_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: pass.h:138
gr_includes.h
Include Files API.
pass_init_t::alert_status
uint8_t alert_status
Initial alert status.
Definition: pass.h:160
PASS_EVT_INVALID
@ PASS_EVT_INVALID
Invalid PASS event type.
Definition: pass.h:120
PASS_CTRL_PT_CANCEL_SLIENT_MODE
@ PASS_CTRL_PT_CANCEL_SLIENT_MODE
Cancel Silent Mode.
Definition: pass.h:114
pass_evt_handler_t
void(* pass_evt_handler_t)(pass_evt_t *p_evt)
Phone Alert Status Service event handler type.
Definition: pass.h:148
pass_evt_t::evt_type
pass_evt_type_t evt_type
The CTS event type.
Definition: pass.h:139
PASS_EVT_MUTE_ONCE_SET
@ PASS_EVT_MUTE_ONCE_SET
Set mute once.
Definition: pass.h:126
PASS_EVT_SILENT_MODE_SET
@ PASS_EVT_SILENT_MODE_SET
Set silent mode.
Definition: pass.h:125
PASS_EVT_SILENT_MODE_CANCEL
@ PASS_EVT_SILENT_MODE_CANCEL
Cancel silent mode.
Definition: pass.h:127
pass_init_t::evt_handler
pass_evt_handler_t evt_handler
Phone Alert Status Service event handler.
Definition: pass.h:158
pass_ringer_setting_set
void pass_ringer_setting_set(uint8_t conn_idx, uint8_t new_setting)
Set Ringer Setting value.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
pass_alert_status_set
void pass_alert_status_set(uint8_t conn_idx, uint8_t new_status)
Set Alert Status value.
pass_init_t::char_mask
uint16_t char_mask
Initial mask of supported characteristics, and configured with Characteristics Mask.
Definition: pass.h:159
PASS_EVT_ALERT_STATUS_NTF_ENABLE
@ PASS_EVT_ALERT_STATUS_NTF_ENABLE
Alert Status notification is enabled.
Definition: pass.h:121
pass_evt_type_t
pass_evt_type_t
Phone Alert Status Service event type.
Definition: pass.h:119
pass_init_t::ringer_setting
uint8_t ringer_setting
Initial ringer setting.
Definition: pass.h:161
pass_service_init
sdk_err_t pass_service_init(pass_init_t *p_pass_init)
Initialize a Phone Alert Status Service instance and add in the DB.
PASS_CTRL_PT_SILENT_MODE
@ PASS_CTRL_PT_SILENT_MODE
Silent Mode.
Definition: pass.h:112