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