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. */
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. */
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. */
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. */
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. */
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  */
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