ans.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file ans.h
5 *
6 * @brief Alert Notification 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_ANS Alert Notification Service (ANS)
45 * @{
46 * @brief Alert Notification Service module.
47 *
48 * @details The Alert Notification Service exposes alert information in a device. This information
49 * includes the following:Type of alert occurring in a device, Additional text information
50 * such as caller ID or sender ID, Count of new alerts and Count of unread alert items.
51 *
52 * After \ref ans_init_t variable is intialized, the application must call \ref ans_service_init()
53 * to add Alert Notification Service and Supported New Alert Category, New Alert, Supported
54 * Unread Alert Category, Unread Alert Status and Alert Notification Control Point characteristics
55 * to the BLE Stack database.
56 */
57
58 #ifndef __ANS_H__
59 #define __ANS_H__
60
61 #include "gr55xx_sys.h"
62 #include "custom_config.h"
63 #include <stdint.h>
64 #include <stdbool.h>
65
66 /**
67 * @defgroup ANS_MACRO Defines
68 * @{
69 */
70 #define ANS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
71 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Alert Notification Service connections. */
72 #define ANS_ERROR_CMD_NOT_SUP 0xa0 /**< Command not supported. */
73 #define ANS_UTF_8_STR_LEN_MAX 18 /**< Maximum length of “UTF-8 string”. */
74 #define ANS_SUP_NEW_ALERT_CAT_VAL_LEN 2 /**< Length of Supported New Alert Category value. */
75 #define ANS_NEWS_ALERT_VAL_LEN (ANS_UTF_8_STR_LEN_MAX + 2) /**< Length of New Alert value. */
76 #define ANS_SUP_UNREAD_ALERT_CAT_VAL_LEN 2 /**< Length of Supported Unread Alert Category value. */
77 #define ANS_UNREAD_ALERT_STA_VAL_LEN 2 /**< Length of Unread Alert Status value. */
78 #define ANS_ALERT_NTF_CTRL_PT_VAL_LEN 2 /**< Length of Alert Notification Control Point value. */
79
80 /**
81 * @defgroup ANS_CAT_ID_BIT_MASK Category ID Bit Masks
82 * @{
83 * @brief Category ID Bit Masks.
84 */
85 #define ANS_SMPL_ALERT_SUP (0x01 << 0) /**< Bit for Simple Alert Supported. */
86 #define ANS_EMAIL_SUP (0x01 << 1) /**< Bit for Email Supported. */
87 #define ANS_NEWS_SUP (0x01 << 2) /**< Bit for News Supported. */
88 #define ANS_CALL_SUP (0x01 << 3) /**< Bit for Call Supported. */
89 #define ANS_MISSED_CALL_SUP (0x01 << 4) /**< Bit for Missed Call Supported. */
90 #define ANS_SMS_MMS_SUP (0x01 << 5) /**< Bit for SMS/MMS Supported. */
91 #define ANS_VOICE_MAIL_SUP (0x01 << 6) /**< Bit for Voice Mail Supported. */
92 #define ANS_SCHEDULE_SUP (0x01 << 7) /**< Bit for Schedule Supported. */
93 #define ANS_HG_PRIO_ALERT_SUP (0x01 << 8) /**< Bit for High Prioritized Alert Supported. */
94 #define ANS_INSTANT_MES (0x01 << 9) /**< Bit for Instant Message Supported. */
95 #define ANS_ALL_CAT_SUP (0x03ff) /**< Bit for All Category Supported. */
96 /** @} */
97 /** @} */
98
99 /**
100 * @defgroup ANS_ENUM Enumerations
101 * @{
102 */
103 /**@brief Alert Notification Service Categories of alerts/messages. */
104 typedef enum
105 {
106 ANS_CAT_ID_SMPL_ALERT, /**< Simple Alert: General text alert or non-text alert. */
107 ANS_CAT_ID_EMAIL, /**< Email: Alert when Email messages arrive. */
108 ANS_CAT_ID_NEWS, /**< News: News feeds such as RSS, Atom. */
109 ANS_CAT_ID_CALL, /**< Call: Incoming call. */
110 ANS_CAT_ID_MISSED_CALL, /**< Missed call: Missed Call. */
111 ANS_CAT_ID_SMS_MMS, /**< SMS/MMS: SMS/MMS message arrives. */
112 ANS_CAT_ID_VOICE_MAIL, /**< Voice mail: Voice mail.*/
113 ANS_CAT_ID_SCHEDULE, /**< Schedule: Alert occurred on calendar, planner. */
114 ANS_CAT_ID_HG_PRIO_ALERT, /**< High Prioritized Alert: Alert that should be handled as high priority. */
115 ANS_CAT_ID_INSTANT_MES, /**< Instant Message: Alert for incoming instant messages. */
116 ANS_CAT_ID_NB, /**< Number of all Categories of alerts/messages. */
117 ANS_CAT_ID_ALL = 0xff, /**< All Categories of alerts/messages. */
118 } ans_alert_cat_id_t;
119
120 /**@brief Alert Notification Service Control point. */
121 typedef enum
122 {
123 ANS_CTRL_PT_EN_NEW_INC_ALERT_NTF, /**< Enable New Incoming Alert Notification. */
124 ANS_CTRL_PT_EN_UNREAD_CAT_STA_NTF, /**< Enable Unread Category Status Notification. */
125 ANS_CTRL_PT_DIS_NEW_INC_ALERT_NTF, /**< Disable New Incoming Alert Notification. */
126 ANS_CTRL_PT_DIS_UNREAD_CAT_STA_NTF, /**< Disable Unread Category Status Notification. */
127 ANS_CTRL_PT_NTF_NEW_INC_ALERT_IMME, /**< Notify New Incoming Alert immediately. */
128 ANS_CTRL_PT_NTF_UNREAD_CAT_STA_IMME, /**< Notify Unread Category Status immediately. */
129 } ans_ctrl_pt_id_t;
130
131 /**@brief Alert Notification Service Event type. */
132 typedef enum
133 {
134 ANS_EVT_INVALID, /**< Invalid ANS event type. */
135 ANS_EVT_NEW_ALERT_NTF_ENABLE, /**< NEW Alert notification is enabled. */
136 ANS_EVT_NEW_ALERT_NTF_DISABLE, /**< NEW Alert notification is disabled. */
137 ANS_EVT_UNREAD_ALERT_STA_NTF_ENABLE, /**< Unread Alert Status notification is enabled. */
138 ANS_EVT_UNREAD_ALERT_STA_NTF_DISABLE, /**< Unread Alert Status notification is disabled. */
139 ANS_EVT_NEW_ALERT_IMME_NTF_REQ, /**< Request: notify the New Alert characteristic to the client immediately. */
140 ANS_EVT_Unread_ALERT_IMME_NTF_REQ, /**< Request: notify the Unread Alert Status characteristic to the client immediately. */
141 } ans_evt_type_t;
142 /** @} */
143
144 /**
145 * @defgroup ANS_STRUCT Structures
146 * @{
147 */
148 /**@brief Alert Notification Service New Alert value. */
149 typedef struct
150 {
151 ans_alert_cat_id_t cat_id; /**< Category ID. */
152 uint8_t alert_num; /**< Number of new alert. */
153 uint8_t str_info[ANS_UTF_8_STR_LEN_MAX]; /**< Text String Information. */
154 uint8_t length; /**< Length of Text String. */
155 } ans_new_alert_t;
156
157 /**@brief Alert Notification Service Unread Alert Status value. */
158 typedef struct
159 {
160 ans_alert_cat_id_t cat_id; /**< Category ID. */
161 uint8_t unread_num; /**< Number of unread alert. */
162 } ans_unread_alert_t;
163
164 /**@brief Alert Notification Service Control Point value. */
165 typedef struct
166 {
167 ans_ctrl_pt_id_t cmd_id; /**< Command ID. */
168 ans_alert_cat_id_t cat_id; /**< Category ID. */
169 } ans_ctrl_pt_t;
170
171 /**@brief Alert Notification Service event. */
172 typedef struct
173 {
174 uint8_t conn_idx; /**< The index of the connection. */
175 ans_evt_type_t evt_type; /**< The ANS event type. */
176 uint16_t cat_ids; /**< Category IDs. */
177 } ans_evt_t;
178 /** @} */
179
180 /**
181 * @defgroup ANS_TYPEDEF Typedefs
182 * @{
183 */
184 /**@brief Alert Notification Service event handler type.*/
185 typedef void (*ans_evt_handler_t)(ans_evt_t *p_evt);
186 /** @} */
187
188 /**
189 * @defgroup ANS_STRUCT Structures
190 * @{
191 */
192 /**@brief Alert Notification Service init stucture. This contains all options and data needed for initialization of the service. */
193 typedef struct
194 {
195 ans_evt_handler_t evt_handler; /**< Phone Alert Status Service event handler. */
196 uint16_t sup_new_alert_cat; /**< Initial mask of Supported New Alert Category. */
197 uint16_t sup_unread_alert_sta; /**< Initial mask of Unread Alert Status. */
198 } ans_init_t;
199 /** @} */
200
201 /**
202 * @defgroup ANS_FUNCTION Functions
203 * @{
204 */
205 /**
206 *****************************************************************************************
207 * @brief Initialize an Alert Notification Service instance and add to the DB.
208 *
209 * @param[in] p_ans_init: Pointer to ANS Service initialization variable.
210 *
211 * @return Result of service initialization.
212 *****************************************************************************************
213 */
214 sdk_err_t ans_service_init(ans_init_t *p_ans_init);
215
216 /**
217 *****************************************************************************************
218 * @brief Send New Alert if its notification has been enabled.
219 *
220 * @param[in] conn_idx: Connnection index.
221 * @param[in] p_new_alert: Pointer to New Alert information.
222 *
223 * @return Result of notify value
224 *****************************************************************************************
225 */
226 sdk_err_t ans_new_alert_send(uint8_t conn_idx, ans_new_alert_t *p_new_alert);
227
228 /**
229 *****************************************************************************************
230 * @brief Send Unread Alert Status if its notification has been enabled.
231 *
232 * @param[in] conn_idx: Connnection index.
233 * @param[in] p_unread_alert: Pointer to Unread Alert Status information.
234 *
235 * @return Result of notify value
236 *****************************************************************************************
237 */
238 sdk_err_t ans_unread_alert_send(uint8_t conn_idx, ans_unread_alert_t *p_unread_alert);
239 /** @} */
240
241 #endif
242 /** @} */
243 /** @} */
244
ans_new_alert_t::cat_id
ans_alert_cat_id_t cat_id
Category ID.
Definition: ans.h:151
ANS_EVT_INVALID
@ ANS_EVT_INVALID
Invalid ANS event type.
Definition: ans.h:134
ans_unread_alert_t::cat_id
ans_alert_cat_id_t cat_id
Category ID.
Definition: ans.h:160
ANS_CAT_ID_SCHEDULE
@ ANS_CAT_ID_SCHEDULE
Schedule: Alert occurred on calendar, planner.
Definition: ans.h:113
ANS_CTRL_PT_EN_UNREAD_CAT_STA_NTF
@ ANS_CTRL_PT_EN_UNREAD_CAT_STA_NTF
Enable Unread Category Status Notification.
Definition: ans.h:124
ANS_CAT_ID_EMAIL
@ ANS_CAT_ID_EMAIL
Email: Alert when Email messages arrive.
Definition: ans.h:107
ANS_CTRL_PT_NTF_UNREAD_CAT_STA_IMME
@ ANS_CTRL_PT_NTF_UNREAD_CAT_STA_IMME
Notify Unread Category Status immediately.
Definition: ans.h:128
ans_new_alert_t::alert_num
uint8_t alert_num
Number of new alert.
Definition: ans.h:152
ANS_CAT_ID_CALL
@ ANS_CAT_ID_CALL
Call: Incoming call.
Definition: ans.h:109
ans_ctrl_pt_id_t
ans_ctrl_pt_id_t
Alert Notification Service Control point.
Definition: ans.h:122
ans_evt_t
Alert Notification Service event.
Definition: ans.h:173
ans_unread_alert_t::unread_num
uint8_t unread_num
Number of unread alert.
Definition: ans.h:161
ans_evt_t::cat_ids
uint16_t cat_ids
Category IDs.
Definition: ans.h:176
ANS_CAT_ID_NB
@ ANS_CAT_ID_NB
Number of all Categories of alerts/messages.
Definition: ans.h:116
ans_service_init
sdk_err_t ans_service_init(ans_init_t *p_ans_init)
Initialize an Alert Notification Service instance and add to the DB.
ANS_CAT_ID_HG_PRIO_ALERT
@ ANS_CAT_ID_HG_PRIO_ALERT
High Prioritized Alert: Alert that should be handled as high priority.
Definition: ans.h:114
ANS_CAT_ID_SMS_MMS
@ ANS_CAT_ID_SMS_MMS
SMS/MMS: SMS/MMS message arrives.
Definition: ans.h:111
ANS_EVT_UNREAD_ALERT_STA_NTF_ENABLE
@ ANS_EVT_UNREAD_ALERT_STA_NTF_ENABLE
Unread Alert Status notification is enabled.
Definition: ans.h:137
ANS_CAT_ID_INSTANT_MES
@ ANS_CAT_ID_INSTANT_MES
Instant Message: Alert for incoming instant messages.
Definition: ans.h:115
ans_unread_alert_t
Alert Notification Service Unread Alert Status value.
Definition: ans.h:159
ANS_CAT_ID_MISSED_CALL
@ ANS_CAT_ID_MISSED_CALL
Missed call: Missed Call.
Definition: ans.h:110
ANS_CTRL_PT_DIS_UNREAD_CAT_STA_NTF
@ ANS_CTRL_PT_DIS_UNREAD_CAT_STA_NTF
Disable Unread Category Status Notification.
Definition: ans.h:126
gr55xx_sys.h
GR55XX System API.
ans_new_alert_send
sdk_err_t ans_new_alert_send(uint8_t conn_idx, ans_new_alert_t *p_new_alert)
Send New Alert if its notification has been enabled.
ANS_EVT_NEW_ALERT_IMME_NTF_REQ
@ ANS_EVT_NEW_ALERT_IMME_NTF_REQ
Request: notify the New Alert characteristic to the client immediately.
Definition: ans.h:139
ANS_EVT_Unread_ALERT_IMME_NTF_REQ
@ ANS_EVT_Unread_ALERT_IMME_NTF_REQ
Request: notify the Unread Alert Status characteristic to the client immediately.
Definition: ans.h:140
ans_evt_type_t
ans_evt_type_t
Alert Notification Service Event type.
Definition: ans.h:133
ans_new_alert_t::length
uint8_t length
Length of Text String.
Definition: ans.h:154
ANS_CAT_ID_VOICE_MAIL
@ ANS_CAT_ID_VOICE_MAIL
Voice mail: Voice mail.
Definition: ans.h:112
ans_ctrl_pt_t::cat_id
ans_alert_cat_id_t cat_id
Category ID.
Definition: ans.h:168
ans_unread_alert_send
sdk_err_t ans_unread_alert_send(uint8_t conn_idx, ans_unread_alert_t *p_unread_alert)
Send Unread Alert Status if its notification has been enabled.
ANS_CAT_ID_ALL
@ ANS_CAT_ID_ALL
All Categories of alerts/messages.
Definition: ans.h:117
ans_evt_t::evt_type
ans_evt_type_t evt_type
The ANS event type.
Definition: ans.h:175
ANS_CTRL_PT_NTF_NEW_INC_ALERT_IMME
@ ANS_CTRL_PT_NTF_NEW_INC_ALERT_IMME
Notify New Incoming Alert immediately.
Definition: ans.h:127
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
ANS_UTF_8_STR_LEN_MAX
#define ANS_UTF_8_STR_LEN_MAX
Maximum length of “UTF-8 string”.
Definition: ans.h:73
ans_ctrl_pt_t
Alert Notification Service Control Point value.
Definition: ans.h:166
ans_init_t
Alert Notification Service init stucture.
Definition: ans.h:194
ANS_CAT_ID_NEWS
@ ANS_CAT_ID_NEWS
News: News feeds such as RSS, Atom.
Definition: ans.h:108
ans_init_t::evt_handler
ans_evt_handler_t evt_handler
Phone Alert Status Service event handler.
Definition: ans.h:195
ans_new_alert_t
Alert Notification Service New Alert value.
Definition: ans.h:150
ans_alert_cat_id_t
ans_alert_cat_id_t
Alert Notification Service Categories of alerts/messages.
Definition: ans.h:105
ANS_CTRL_PT_EN_NEW_INC_ALERT_NTF
@ ANS_CTRL_PT_EN_NEW_INC_ALERT_NTF
Enable New Incoming Alert Notification.
Definition: ans.h:123
ANS_CAT_ID_SMPL_ALERT
@ ANS_CAT_ID_SMPL_ALERT
Simple Alert: General text alert or non-text alert.
Definition: ans.h:106
ANS_EVT_NEW_ALERT_NTF_DISABLE
@ ANS_EVT_NEW_ALERT_NTF_DISABLE
NEW Alert notification is disabled.
Definition: ans.h:136
ANS_EVT_UNREAD_ALERT_STA_NTF_DISABLE
@ ANS_EVT_UNREAD_ALERT_STA_NTF_DISABLE
Unread Alert Status notification is disabled.
Definition: ans.h:138
ANS_CTRL_PT_DIS_NEW_INC_ALERT_NTF
@ ANS_CTRL_PT_DIS_NEW_INC_ALERT_NTF
Disable New Incoming Alert Notification.
Definition: ans.h:125
ans_init_t::sup_new_alert_cat
uint16_t sup_new_alert_cat
Initial mask of Supported New Alert Category.
Definition: ans.h:196
ans_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: ans.h:174
ans_ctrl_pt_t::cmd_id
ans_ctrl_pt_id_t cmd_id
Command ID.
Definition: ans.h:167
ans_evt_handler_t
void(* ans_evt_handler_t)(ans_evt_t *p_evt)
Alert Notification Service event handler type.
Definition: ans.h:185
ANS_EVT_NEW_ALERT_NTF_ENABLE
@ ANS_EVT_NEW_ALERT_NTF_ENABLE
NEW Alert notification is enabled.
Definition: ans.h:135
ans_init_t::sup_unread_alert_sta
uint16_t sup_unread_alert_sta
Initial mask of Unread Alert Status.
Definition: ans.h:197