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. */
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. */
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  */
179 
180 /**
181  *****************************************************************************************
182  * @brief Get Ringer Setting value.
183  *
184  * @return Current Ringer Setting value.
185  *****************************************************************************************
186  */
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
Definition: pass.h:123
PASS_CTRL_PT_MUTE_ONCE
@ PASS_CTRL_PT_MUTE_ONCE
Definition: pass.h:113
PASS_EVT_RINGER_SET_NTF_DISABLE
@ PASS_EVT_RINGER_SET_NTF_DISABLE
Definition: pass.h:124
PASS_EVT_ALERT_STATUS_NTF_DISABLE
@ PASS_EVT_ALERT_STATUS_NTF_DISABLE
Definition: pass.h:122
pass_init_t
Phone Alert Status Service init stucture. This contains all option and data needed for initialization...
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
Definition: pass.h:138
gr_includes.h
Include Files API.
pass_init_t::alert_status
uint8_t alert_status
Definition: pass.h:160
PASS_EVT_INVALID
@ PASS_EVT_INVALID
Definition: pass.h:120
PASS_CTRL_PT_CANCEL_SLIENT_MODE
@ PASS_CTRL_PT_CANCEL_SLIENT_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
Definition: pass.h:139
PASS_EVT_MUTE_ONCE_SET
@ PASS_EVT_MUTE_ONCE_SET
Definition: pass.h:126
PASS_EVT_SILENT_MODE_SET
@ PASS_EVT_SILENT_MODE_SET
Definition: pass.h:125
PASS_EVT_SILENT_MODE_CANCEL
@ PASS_EVT_SILENT_MODE_CANCEL
Definition: pass.h:127
pass_init_t::evt_handler
pass_evt_handler_t evt_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
Definition: pass.h:159
PASS_EVT_ALERT_STATUS_NTF_ENABLE
@ PASS_EVT_ALERT_STATUS_NTF_ENABLE
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
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
Definition: pass.h:112