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 <stdint.h> 62 #include <stdbool.h> 63 #include "gr55xx_sys.h" 64 #include "custom_config.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 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 ANS_CTRL_PT_EN_NEW_INC_ALERT_NTF, /**< Enable New Incoming Alert Notification. */ 122 ANS_CTRL_PT_EN_UNREAD_CAT_STA_NTF, /**< Enable Unread Category Status Notification. */ 123 ANS_CTRL_PT_DIS_NEW_INC_ALERT_NTF, /**< Disable New Incoming Alert Notification. */ 124 ANS_CTRL_PT_DIS_UNREAD_CAT_STA_NTF, /**< Disable Unread Category Status Notification. */ 125 ANS_CTRL_PT_NTF_NEW_INC_ALERT_IMME, /**< Notify New Incoming Alert immediately. */ 126 ANS_CTRL_PT_NTF_UNREAD_CAT_STA_IMME, /**< Notify Unread Category Status immediately. */ 127 } ans_ctrl_pt_id_t; 128 129 /**@brief Alert Notification Service Event type. */ 130 typedef enum { 131 ANS_EVT_INVALID, /**< Invalid ANS event type. */ 132 ANS_EVT_NEW_ALERT_NTF_ENABLE, /**< NEW Alert notification is enabled. */ 133 ANS_EVT_NEW_ALERT_NTF_DISABLE, /**< NEW Alert notification is disabled. */ 134 ANS_EVT_UNREAD_ALERT_STA_NTF_ENABLE, /**< Unread Alert Status notification is enabled. */ 135 ANS_EVT_UNREAD_ALERT_STA_NTF_DISABLE, /**< Unread Alert Status notification is disabled. */ 136 ANS_EVT_NEW_ALERT_IMME_NTF_REQ, /**< Request: notify the New Alert characteristic \ 137 to the client immediately. */ 138 ANS_EVT_Unread_ALERT_IMME_NTF_REQ, /**< Request: notify the Unread Alert Status characteristic \ 139 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 ans_alert_cat_id_t cat_id; /**< Category ID. */ 150 uint8_t alert_num; /**< Number of new alert. */ 151 uint8_t str_info[ANS_UTF_8_STR_LEN_MAX]; /**< Text String Information. */ 152 uint8_t length; /**< Length of Text String. */ 153 } ans_new_alert_t; 154 155 /**@brief Alert Notification Service Unread Alert Status value. */ 156 typedef struct { 157 ans_alert_cat_id_t cat_id; /**< Category ID. */ 158 uint8_t unread_num; /**< Number of unread alert. */ 159 } ans_unread_alert_t; 160 161 /**@brief Alert Notification Service Control Point value. */ 162 typedef struct { 163 ans_ctrl_pt_id_t cmd_id; /**< Command ID. */ 164 ans_alert_cat_id_t cat_id; /**< Category ID. */ 165 } ans_ctrl_pt_t; 166 167 /**@brief Alert Notification Service event. */ 168 typedef struct { 169 uint8_t conn_idx; /**< The index of the connection. */ 170 ans_evt_type_t evt_type; /**< The ANS event type. */ 171 uint16_t cat_ids; /**< Category IDs. */ 172 } ans_evt_t; 173 /** @} */ 174 175 /** 176 * @defgroup ANS_TYPEDEF Typedefs 177 * @{ 178 */ 179 /**@brief Alert Notification Service event handler type.*/ 180 typedef void (*ans_evt_handler_t)(ans_evt_t *p_evt); 181 /** @} */ 182 183 /** 184 * @defgroup ANS_STRUCT Structures 185 * @{ 186 */ 187 /**@brief Alert Notification Service init stucture. \ 188 * This contains all options and data needed for initialization of the service. */ 189 typedef struct { 190 ans_evt_handler_t evt_handler; /**< Phone Alert Status Service event handler. */ 191 uint16_t sup_new_alert_cat; /**< Initial mask of Supported New Alert Category. */ 192 uint16_t sup_unread_alert_sta; /**< Initial mask of Unread Alert Status. */ 193 } ans_init_t; 194 /** @} */ 195 196 /** 197 * @defgroup ANS_FUNCTION Functions 198 * @{ 199 */ 200 /** 201 ***************************************************************************************** 202 * @brief Initialize an Alert Notification Service instance and add to the DB. 203 * 204 * @param[in] p_ans_init: Pointer to ANS Service initialization variable. 205 * 206 * @return Result of service initialization. 207 ***************************************************************************************** 208 */ 209 sdk_err_t ans_service_init(ans_init_t *p_ans_init); 210 211 /** 212 ***************************************************************************************** 213 * @brief Send New Alert if its notification has been enabled. 214 * 215 * @param[in] conn_idx: Connnection index. 216 * @param[in] p_new_alert: Pointer to New Alert information. 217 * 218 * @return Result of notify value 219 ***************************************************************************************** 220 */ 221 sdk_err_t ans_new_alert_send(uint8_t conn_idx, ans_new_alert_t *p_new_alert); 222 223 /** 224 ***************************************************************************************** 225 * @brief Send Unread Alert Status if its notification has been enabled. 226 * 227 * @param[in] conn_idx: Connnection index. 228 * @param[in] p_unread_alert: Pointer to Unread Alert Status information. 229 * 230 * @return Result of notify value 231 ***************************************************************************************** 232 */ 233 sdk_err_t ans_unread_alert_send(uint8_t conn_idx, ans_unread_alert_t *p_unread_alert); 234 /** @} */ 235 236 #endif 237 /** @} */ 238 /** @} */ 239 240