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 "gr55xx_sys.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 < CFG_MAX_CONNECTIONS ?\
69  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Phone Alert Status Service connections. */
70 #define PASS_ALERT_STATUS_VAL_LEN 1 /**< Length of Alert Status value. */
71 #define PASS_RINGER_SET_VAL_LEN 1 /**< Length of Ringer Setting value. */
72 #define PASS_RINGER_CTRL_PT_VAL_LEN 1 /**< Length of Ringer Control Point value. */
73 
74 /**
75  * @defgroup PASS_CHAR_MASK Characteristics Mask
76  * @{
77  * @brief Bit masks for the initialization of \ref pass_init_t.char_mask.
78  */
79 #define PASS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in PASS. */
80 #define PASS_CHAR_RING_CTRL_PT_SUP 0x0180 /**< Bit mask for Ringer Control Point characteristic in PASS. */
81 #define PASS_CHAR_FULL 0x01ff /**< Bit mask of the full characteristic. */
82 /** @} */
83 
84 /**
85  * @defgroup PASS_ALERT_STATUES_BIT Alert Status BIT
86  * @{
87  * @brief PASS Alert Status bits.
88  */
89 #define PASS_NO_STATE_ACTIVE (0x00) /**< Bit for no state active. */
90 #define PASS_RINGER_ACTIVE (0x01 << 0) /**< Bit for ringer State active. */
91 #define PASS_VIBRATE_ACTIVE (0x01 << 1) /**< Bit for vibrate State active. */
92 #define PASS_DISPLAY_ALERT_ACTIVE (0x01 << 2) /**< Bit for display Alert Status State active. */
93 #define PASS_ALL_STATE_ACTIVE (0x07) /**< Bit for no state active. */
94 /** @} */
95 
96 /**
97  * @defgroup PASS_RINGER_SETTING Ringer Setting
98  * @{
99  * @brief The Ringer Setting characteristic defines the setting of the ringer.
100  */
101 #define PASS_RINGER_SET_SILENT 0 /**< Ringer Silent. */
102 #define PASS_RINGER_SET_NORMAL 1 /**< Ringer Normal. */
103 /** @} */
104 /** @} */
105 
106 /**
107  * @defgroup PASS_ENUM Enumerations
108  * @{
109  */
110 /**@brief Phone Alert Status Service Ringer Control Point. */
111 typedef enum
112 {
113  PASS_CTRL_PT_SILENT_MODE = 0x01, /**< Silent Mode. */
114  PASS_CTRL_PT_MUTE_ONCE, /**< Mute Once. */
115  PASS_CTRL_PT_CANCEL_SLIENT_MODE, /**< Cancel Silent Mode. */
117 
118 /**@brief Phone Alert Status Service event type. */
119 typedef enum
120 {
121  PASS_EVT_INVALID, /**< Invalid PASS event type. */
122  PASS_EVT_ALERT_STATUS_NTF_ENABLE, /**< Alert Status notification is enabled. */
123  PASS_EVT_ALERT_STATUS_NTF_DISABLE, /**< Alert Status notification is disabled. */
124  PASS_EVT_RINGER_SET_NTF_ENABLE, /**< Ringer Setting notification is enabled. */
125  PASS_EVT_RINGER_SET_NTF_DISABLE, /**< Ringer Setting notification is disabled. */
126  PASS_EVT_SILENT_MODE_SET, /**< Set silent mode. */
127  PASS_EVT_MUTE_ONCE_SET, /**< Set mute once. */
128  PASS_EVT_SILENT_MODE_CANCEL, /**< Cancel silent mode. */
130 /** @} */
131 
132 /**
133  * @defgroup PASS_STRUCT Structures
134  * @{
135  */
136 /**@brief Phone Alert Status Service event. */
137 typedef struct
138 {
139  uint8_t conn_idx; /**< The index of the connection. */
140  pass_evt_type_t evt_type; /**< The CTS event type. */
141 } pass_evt_t;
142 /** @} */
143 
144 /**
145  * @defgroup PASS_TYPEDEF Typedefs
146  * @{
147  */
148 /**@brief Phone Alert Status Service event handler type.*/
149 typedef void (*pass_evt_handler_t)(pass_evt_t *p_evt);
150 /** @} */
151 
152 /**
153  * @defgroup PASS_STRUCT Structures
154  * @{
155  */
156 /**@brief Phone Alert Status Service init stucture. This contains all option and data needed for initialization of the service. */
157 typedef struct
158 {
159  pass_evt_handler_t evt_handler; /**< Phone Alert Status Service event handler. */
160  uint16_t char_mask; /**< Initial mask of supported characteristics, and configured with \ref PASS_CHAR_MASK. */
161  uint8_t alert_status; /**< Initial alert status. */
162  uint8_t ringer_setting; /**< Initial ringer setting. */
163 } pass_init_t;
164 /** @} */
165 
166 /**
167  * @defgroup PASS_FUNCTION Functions
168  * @{
169  */
170 /**
171  *****************************************************************************************
172  * @brief Initialize a Phone Alert Status Service instance and add in the DB.
173  *
174  * @param[in] p_pass_init: Pointer to PASS Service initialization variable.
175  *
176  * @return Result of service initialization.
177  *****************************************************************************************
178  */
180 
181 /**
182  *****************************************************************************************
183  * @brief Get Ringer Setting value.
184  *
185  * @return Current Ringer Setting value.
186  *****************************************************************************************
187  */
189 
190 /**
191  *****************************************************************************************
192  * @brief Set Ringer Setting value.
193  *
194  * @param[in] conn_idx: Connnection index.
195  * @param[in] new_setting: New Ringer Setting value.
196  *****************************************************************************************
197  */
198 void pass_ringer_setting_set(uint8_t conn_idx, uint8_t new_setting);
199 
200 /**
201  *****************************************************************************************
202  * @brief Set Alert Status value.
203  *
204  * @param[in] conn_idx: Connnection index.
205  * @param[in] new_status: New Alert Status value.
206  *****************************************************************************************
207  */
208 void pass_alert_status_set(uint8_t conn_idx, uint8_t new_status);
209 /** @} */
210 
211 #endif
212 /** @} */
213 /** @} */
214 
pass_ringer_ctrl_pt_t
pass_ringer_ctrl_pt_t
Phone Alert Status Service Ringer Control Point.
Definition: pass.h:112
PASS_EVT_RINGER_SET_NTF_ENABLE
@ PASS_EVT_RINGER_SET_NTF_ENABLE
Ringer Setting notification is enabled.
Definition: pass.h:124
PASS_CTRL_PT_MUTE_ONCE
@ PASS_CTRL_PT_MUTE_ONCE
Mute Once.
Definition: pass.h:114
PASS_EVT_RINGER_SET_NTF_DISABLE
@ PASS_EVT_RINGER_SET_NTF_DISABLE
Ringer Setting notification is disabled.
Definition: pass.h:125
PASS_EVT_ALERT_STATUS_NTF_DISABLE
@ PASS_EVT_ALERT_STATUS_NTF_DISABLE
Alert Status notification is disabled.
Definition: pass.h:123
pass_init_t
Phone Alert Status Service init stucture.
Definition: pass.h:158
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:138
pass_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: pass.h:139
pass_init_t::alert_status
uint8_t alert_status
Initial alert status.
Definition: pass.h:161
gr55xx_sys.h
GR55XX System API.
PASS_EVT_INVALID
@ PASS_EVT_INVALID
Invalid PASS event type.
Definition: pass.h:121
PASS_CTRL_PT_CANCEL_SLIENT_MODE
@ PASS_CTRL_PT_CANCEL_SLIENT_MODE
Cancel Silent Mode.
Definition: pass.h:115
pass_evt_handler_t
void(* pass_evt_handler_t)(pass_evt_t *p_evt)
Phone Alert Status Service event handler type.
Definition: pass.h:149
pass_evt_t::evt_type
pass_evt_type_t evt_type
The CTS event type.
Definition: pass.h:140
PASS_EVT_MUTE_ONCE_SET
@ PASS_EVT_MUTE_ONCE_SET
Set mute once.
Definition: pass.h:127
PASS_EVT_SILENT_MODE_SET
@ PASS_EVT_SILENT_MODE_SET
Set silent mode.
Definition: pass.h:126
PASS_EVT_SILENT_MODE_CANCEL
@ PASS_EVT_SILENT_MODE_CANCEL
Cancel silent mode.
Definition: pass.h:128
pass_init_t::evt_handler
pass_evt_handler_t evt_handler
Phone Alert Status Service event handler.
Definition: pass.h:159
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:243
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:160
PASS_EVT_ALERT_STATUS_NTF_ENABLE
@ PASS_EVT_ALERT_STATUS_NTF_ENABLE
Alert Status notification is enabled.
Definition: pass.h:122
pass_evt_type_t
pass_evt_type_t
Phone Alert Status Service event type.
Definition: pass.h:120
pass_init_t::ringer_setting
uint8_t ringer_setting
Initial ringer setting.
Definition: pass.h:162
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:113