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. */
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. */
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. */
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. */
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. */
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  */
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
Definition: ans.h:150
ANS_EVT_INVALID
@ ANS_EVT_INVALID
Definition: ans.h:133
ans_unread_alert_t::cat_id
ans_alert_cat_id_t cat_id
Definition: ans.h:159
ANS_CAT_ID_SCHEDULE
@ ANS_CAT_ID_SCHEDULE
Definition: ans.h:112
ANS_CTRL_PT_EN_UNREAD_CAT_STA_NTF
@ ANS_CTRL_PT_EN_UNREAD_CAT_STA_NTF
Definition: ans.h:123
ANS_CAT_ID_EMAIL
@ ANS_CAT_ID_EMAIL
Definition: ans.h:106
ANS_CTRL_PT_NTF_UNREAD_CAT_STA_IMME
@ ANS_CTRL_PT_NTF_UNREAD_CAT_STA_IMME
Definition: ans.h:127
ans_new_alert_t::alert_num
uint8_t alert_num
Definition: ans.h:151
ANS_CAT_ID_CALL
@ ANS_CAT_ID_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
Definition: ans.h:160
ans_evt_t::cat_ids
uint16_t cat_ids
Definition: ans.h:175
ANS_CAT_ID_NB
@ ANS_CAT_ID_NB
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
Definition: ans.h:113
ANS_CAT_ID_SMS_MMS
@ ANS_CAT_ID_SMS_MMS
Definition: ans.h:110
ANS_EVT_UNREAD_ALERT_STA_NTF_ENABLE
@ ANS_EVT_UNREAD_ALERT_STA_NTF_ENABLE
Definition: ans.h:136
ANS_CAT_ID_INSTANT_MES
@ ANS_CAT_ID_INSTANT_MES
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
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
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
Definition: ans.h:138
ANS_EVT_Unread_ALERT_IMME_NTF_REQ
@ ANS_EVT_Unread_ALERT_IMME_NTF_REQ
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
Definition: ans.h:153
ANS_CAT_ID_VOICE_MAIL
@ ANS_CAT_ID_VOICE_MAIL
Definition: ans.h:111
ans_ctrl_pt_t::cat_id
ans_alert_cat_id_t cat_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
Definition: ans.h:116
ans_evt_t::evt_type
ans_evt_type_t evt_type
Definition: ans.h:174
ANS_CTRL_PT_NTF_NEW_INC_ALERT_IMME
@ ANS_CTRL_PT_NTF_NEW_INC_ALERT_IMME
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
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. This contains all options and data needed for initializatio...
Definition: ans.h:193
ANS_CAT_ID_NEWS
@ ANS_CAT_ID_NEWS
Definition: ans.h:107
ans_init_t::evt_handler
ans_evt_handler_t evt_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
Definition: ans.h:122
ANS_CAT_ID_SMPL_ALERT
@ ANS_CAT_ID_SMPL_ALERT
Definition: ans.h:105
ANS_EVT_NEW_ALERT_NTF_DISABLE
@ ANS_EVT_NEW_ALERT_NTF_DISABLE
Definition: ans.h:135
ANS_EVT_UNREAD_ALERT_STA_NTF_DISABLE
@ ANS_EVT_UNREAD_ALERT_STA_NTF_DISABLE
Definition: ans.h:137
ANS_CTRL_PT_DIS_NEW_INC_ALERT_NTF
@ ANS_CTRL_PT_DIS_NEW_INC_ALERT_NTF
Definition: ans.h:124
ans_init_t::sup_new_alert_cat
uint16_t sup_new_alert_cat
Definition: ans.h:195
ans_evt_t::conn_idx
uint8_t conn_idx
Definition: ans.h:173
ans_ctrl_pt_t::cmd_id
ans_ctrl_pt_id_t cmd_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
Definition: ans.h:134
ans_init_t::sup_unread_alert_sta
uint16_t sup_unread_alert_sta
Definition: ans.h:196