ans_c.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file ans_c.h
5  *
6  * @brief Alert Notification Service Client 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  */
41 
42 /**
43  * @defgroup BLE_SDK_ANS_C Alert Notification Service Client (ANS_C)
44  * @{
45  * @brief Alert Notification Service Client module.
46  *
47  * @details The Alert Notification Service Client contains the APIs and types, which can be used
48  * by the application to discovery of Alert Notification Service of peer and interact with it.
49  *
50  * The application must provide an event handler to be register, then call \ref ans_client_init().
51  * After Alert Notification Service Client discoveries peer Alert Notification Service,
52  * application can call \ref ans_c_ctrl_point_set() to send Alert Notification Control Point to peer.
53  * When number of New Alert or Unread Alert changes, the module will receive notification from peer
54  * if notifications of them are enabled.
55  */
56 
57 #ifndef __ANS_C_H__
58 #define __ANS_C_H__
59 
60 #include "gr_includes.h"
61 #include "ble_prf_types.h"
62 #include "custom_config.h"
63 #include <stdint.h>
64 #include <stdbool.h>
65 
66 /**
67  * @defgroup ANS_C_MACRO Defines
68  * @{
69  */
70 #define ANS_C_CONNECTION_MAX 10 /**< Maximum number of HRS Client connections. */
71 #define ANS_C_ERROR_CMD_NOT_SUP 0xa0 /**< Command not supported. */
72 #define ANS_C_UTF_8_STR_LEN_MAX 18 /**< Maximum length of “UTF-8 string”. */
73 #define ANS_C_ALERT_NTF_CTRL_PT_VAL_LEN 2 /**< Length of Alert Notification Control Point value. */
74 
75 /**
76  * @defgroup ANS_C_CAT_ID_BIT_MASK Category ID Bit Masks
77  * @{
78  * @brief Category ID Bit Masks.
79  */
80 #define ANS_C_SMPL_ALERT_SUP (0x01 << 0) /**< Bit for Simple Alert Supported. */
81 #define ANS_C_EMAIL_SUP (0x01 << 1) /**< Bit for Email Supported. */
82 #define ANS_C_NEWS_SUP (0x01 << 2) /**< Bit for News Supported. */
83 #define ANS_C_CALL_SUP (0x01 << 3) /**< Bit for Call Supported. */
84 #define ANS_C_MISSED_CALL_SUP (0x01 << 4) /**< Bit for Missed Call Supported. */
85 #define ANS_C_SMS_MMS_SUP (0x01 << 5) /**< Bit for SMS/MMS Supported. */
86 #define ANS_C_VOICE_MAIL_SUP (0x01 << 6) /**< Bit for Voice Mail Supported. */
87 #define ANS_C_SCHEDULE_SUP (0x01 << 7) /**< Bit for Schedule Supported. */
88 #define ANS_C_HG_PRIO_ALERT_SUP (0x01 << 8) /**< Bit for High Prioritized Alert Supported. */
89 #define ANS_C_INSTANT_MES (0x01 << 9) /**< Bit for Instant Message Supported. */
90 #define ANS_C_ALL_CAT_SUP (0x03ff) /**< Bit for All Category Supported. */
91 /** @} */
92 /** @} */
93 
94 /**
95  * @defgroup ANS_C_ENUM Enumerations
96  * @{
97  */
98 /**@brief Alert Notification Service Categories of alerts/messages. */
99 typedef enum
100 {
101  ANS_C_CAT_ID_SMPL_ALERT, /**< Simple Alert: General text alert or non-text alert. */
102  ANS_C_CAT_ID_EMAIL, /**< Email: Alert when Email messages arrives. */
103  ANS_C_CAT_ID_NEWS, /**< News: News feeds such as RSS, Atom. */
104  ANS_C_CAT_ID_CALL, /**< Call: Incoming call. */
105  ANS_C_CAT_ID_MISSED_CALL, /**< Missed call: Missed Call. */
106  ANS_C_CAT_ID_SMS_MMS, /**< SMS/MMS: SMS/MMS message arrives. */
107  ANS_C_CAT_ID_VOICE_MAIL, /**< Voice mail: Voice mail.*/
108  ANS_C_CAT_ID_SCHEDULE, /**< Schedule: Alert occurred on calendar, planner. */
109  ANS_C_CAT_ID_HG_PRIO_ALERT, /**< High Prioritized Alert: Alert that should be handled as high priority. */
110  ANS_C_CAT_ID_INSTANT_MES, /**< Instant Message: Alert for incoming instant messages. */
111  AANS_C_CAT_ID_NB, /**< Number of all Categories of alerts/messages. */
112  ANS_C_CAT_ID_ALL = 0xff, /**< All Categories of alerts/messages. */
114 
115 /**@brief Alert Notification Service Client Control point ID. */
116 typedef enum
117 {
118  ANS_C_CTRL_PT_EN_NEW_INC_ALERT_NTF, /**< Enable New Incoming Alert Notification. */
119  ANS_C_CTRL_PT_EN_UNREAD_CAT_STA_NTF, /**< Enable Unread Category Status Notification. */
120  ANS_C_CTRL_PT_DIS_NEW_INC_ALERT_NTF, /**< Disable New Incoming Alert Notification. */
121  ANS_C_CTRL_PT_DIS_UNREAD_CAT_STA_NTF, /**< Disable Unread Category Status Notification. */
122  ANS_C_CTRL_PT_NTF_NEW_INC_ALERT_IMME, /**< Notify New Incoming Alert immediately. */
123  ANS_C_CTRL_PT_NTF_UNREAD_CAT_STA_IMME, /**< Notify Unread Category Status immediately. */
125 
126 /**@brief Alert Notification Service Client Event type. */
127 typedef enum
128 {
129  ANS_C_EVT_INVALID, /**< ANS Client invalid event type. */
130  ANS_C_EVT_DISCOVERY_COMPLETE, /**< ANS Client has found ANS service and its characteristics. */
131  ANS_C_EVT_DISCOVERY_FAIL , /**< ANS Client found ANS service failed because of invalid operation or no found at the peer. */
132  ANS_C_EVT_NEW_ALERT_NTF_SET_SUCCESS, /**< ANS Client has set NEW Alert notification. */
133  ANS_C_EVT_UNREAD_ALERT_STA_NTF_SET_SUCCESS, /**< ANS Client has set Unread Alert Status notification. */
134  ANS_C_EVT_SUP_NEW_ALERT_CAT_RECEIV, /**< ANS Client has received Supported New Alert Category value (Read from peer). */
135  ANS_C_EVT_SUP_UNREAD_ALERT_CAT_REC, /**< ANS Client has received Supported Unread Alert Category value (Read from peer). */
136  ANS_C_EVT_NEW_ALERT_RECEIVE, /**< ANS Client has received New Alert value (Notification from peer). */
137  ANS_C_EVT_UNREAD_ALERT_RECEIVE, /**< ANS Client has received Unread Alert Status value (Notification from peer). */
138  ANS_C_EVT_CTRL_POINT_SET_SUCCESS, /**< ANS Client has written Control Point completely. */
139  ANS_C_EVT_WRITE_OP_ERR, /**< Error occured when ANS Client wrote to peer. */
141 /** @} */
142 
143 /**
144  * @defgroup ANS_C_STRUCT Structures
145  * @{
146  */
147 /**@brief Alert Notification Service Client decoded New Alert value. */
148 typedef struct
149 {
150  ans_c_alert_cat_id_t cat_id; /**< Category ID. */
151  uint8_t alert_num; /**< Number of new alert. */
152  uint8_t str_info[ANS_C_UTF_8_STR_LEN_MAX]; /**< Text String Information. */
153  uint8_t length; /**< Length of Text String. */
155 
156 /**@brief Alert Notification Service Client decoded Unread Alert Status value. */
157 typedef struct
158 {
159  ans_c_alert_cat_id_t cat_id; /**< Category ID. */
160  uint8_t unread_num; /**< Number of unread alert. */
162 
163 /**@brief Alert Notification Service Client Control Point value. */
164 typedef struct
165 {
166  ans_c_ctrl_pt_id_t cmd_id; /**< Command ID. */
167  ans_c_alert_cat_id_t cat_id; /**< Category ID. */
169 
170 /**@brief Handles on the connected peer device needed to interact with it. */
171 typedef struct
172 {
173  uint16_t ans_srvc_start_handle; /**< ANS Service start handle. */
174  uint16_t ans_srvc_end_handle; /**< ANS Service end handle. */
175  uint16_t ans_sup_new_alert_cat_handle; /**< ANS Supported New Alert Category characteristic Value handle which has been got from peer. */
176  uint16_t ans_new_alert_handle; /**< ANS New Alert characteristic Value handle which has been got from peer. */
177  uint16_t ans_new_alert_cccd_handle; /**< ANS CCCD handle of New Alert characteristic which has been got from peer. */
178  uint16_t ans_sup_unread_alert_cat_handle; /**< ANS Supported Unread Alert Category characteristic Value handle which has been got from peer. */
179  uint16_t ans_unread_alert_handle; /**< ANS Unread Alert characteristic Value handle which has been got from peer. */
180  uint16_t ans_unread_alert_cccd_handle; /**< ANS CCCD handle of Unread Alert characteristic which has been got from peer. */
181  uint16_t ans_ctrl_pt_handle; /**< ANS Control Point characteristic Value handle which has been got from peer. */
183 
184 /**@brief Alert Notification Service Client event. */
185 typedef struct
186 {
187  uint8_t conn_idx; /**< The index of the connection. */
188  ans_c_evt_type_t evt_type; /**< The ANS event type. */
189  union
190  {
191  uint16_t sup_new_alert_cat_ids; /**< Alert status received. */
192  uint16_t sup_unread_alert_cat_ids; /**< Ringer setting received. */
193  ans_c_new_alert_t new_alert; /**< New Alert value. */
194  ans_c_unread_alert_t unread_alert; /**< Unread Alert Status value. */
195  } value; /**< Value received. */
196 } ans_c_evt_t;
197 /** @} */
198 
199 /**
200  * @defgroup ANS_C_TYPEDEF Typedefs
201  * @{
202  */
203 /**@brief Alert Notification Service Client event handler type.*/
204 typedef void (*ans_c_evt_handler_t)(ans_c_evt_t *p_evt);
205 /** @} */
206 
207 /**
208  * @defgroup ANS_FUNCTION Functions
209  * @{
210  */
211 /**
212  *****************************************************************************************
213  * @brief Register ANS Client event handler.
214  *
215  * @param[in] evt_handler: Alert Notification Service Client event handler.
216  *
217  * @return Result of initialization.
218  *****************************************************************************************
219  */
221 
222 /**
223  *****************************************************************************************
224  * @brief Discover Alert Notification Service on peer.
225  *
226  * @param[in] conn_idx: Index of connection.
227  *
228  * @return Operation result.
229  *****************************************************************************************
230  */
232 
233 /**
234  *****************************************************************************************
235  * @brief Enable or disable peer New Alert characteristic notify.
236  *
237  * @param[in] conn_idx: Index of connection.
238  * @param[in] is_enable: True or false.
239  *
240  * @return Operation result.
241  *****************************************************************************************
242  */
243 sdk_err_t ans_c_new_alert_notify_set(uint8_t conn_idx, bool is_enable);
244 
245 /**
246  *****************************************************************************************
247  * @brief Enable or disable peer Unread Alert characteristic notify.
248  *
249  * @param[in] conn_idx: Index of connection.
250  * @param[in] is_enable: True or false.
251  *
252  * @return Operation result.
253  *****************************************************************************************
254  */
255 sdk_err_t ans_c_unread_alert_notify_set(uint8_t conn_idx, bool is_enable);
256 
257 /**
258  *****************************************************************************************
259  * @brief Read Supported New Alert Category characteristic value.
260  *
261  * @param[in] conn_idx: Index of connection.
262  *
263  * @return Operation result.
264  *****************************************************************************************
265  */
267 
268 /**
269  *****************************************************************************************
270  * @brief Read Supported Unread Alert Category characteristic value.
271  *
272  * @param[in] conn_idx: Index of connection.
273  *
274  * @return Operation result.
275  *****************************************************************************************
276  */
278 
279 /**
280  *****************************************************************************************
281  * @brief Set Control Point characteristic value.
282  *
283  * @param[in] conn_idx: Index of connection.
284  * @param[in] p_ctrl_pt: Pointer to control point.
285  *
286  * @return Operation result.
287  *****************************************************************************************
288  */
289 sdk_err_t ans_c_ctrl_point_set(uint8_t conn_idx, ans_c_ctrl_pt_t *p_ctrl_pt);
290 /** @} */
291 
292 #endif
293 /** @} */
294 /** @} */
295 
ANS_C_EVT_UNREAD_ALERT_RECEIVE
@ ANS_C_EVT_UNREAD_ALERT_RECEIVE
Definition: ans_c.h:137
ANS_C_CTRL_PT_DIS_NEW_INC_ALERT_NTF
@ ANS_C_CTRL_PT_DIS_NEW_INC_ALERT_NTF
Definition: ans_c.h:120
ans_c_handles_t::ans_new_alert_cccd_handle
uint16_t ans_new_alert_cccd_handle
Definition: ans_c.h:177
ans_c_evt_t
Alert Notification Service Client event.
Definition: ans_c.h:186
ans_c_handles_t::ans_ctrl_pt_handle
uint16_t ans_ctrl_pt_handle
Definition: ans_c.h:181
ANS_C_EVT_DISCOVERY_COMPLETE
@ ANS_C_EVT_DISCOVERY_COMPLETE
Definition: ans_c.h:130
ANS_C_EVT_INVALID
@ ANS_C_EVT_INVALID
Definition: ans_c.h:129
ans_c_new_alert_t::length
uint8_t length
Definition: ans_c.h:153
ANS_C_EVT_SUP_UNREAD_ALERT_CAT_REC
@ ANS_C_EVT_SUP_UNREAD_ALERT_CAT_REC
Definition: ans_c.h:135
ans_c_ctrl_pt_id_t
ans_c_ctrl_pt_id_t
Alert Notification Service Client Control point ID.
Definition: ans_c.h:117
ans_c_ctrl_pt_t::cat_id
ans_c_alert_cat_id_t cat_id
Definition: ans_c.h:167
ANS_C_CAT_ID_SMS_MMS
@ ANS_C_CAT_ID_SMS_MMS
Definition: ans_c.h:106
ANS_C_CAT_ID_INSTANT_MES
@ ANS_C_CAT_ID_INSTANT_MES
Definition: ans_c.h:110
ANS_C_EVT_DISCOVERY_FAIL
@ ANS_C_EVT_DISCOVERY_FAIL
Definition: ans_c.h:131
ANS_C_CAT_ID_ALL
@ ANS_C_CAT_ID_ALL
Definition: ans_c.h:112
ans_c_evt_t::unread_alert
ans_c_unread_alert_t unread_alert
Definition: ans_c.h:194
ANS_C_EVT_WRITE_OP_ERR
@ ANS_C_EVT_WRITE_OP_ERR
Definition: ans_c.h:139
ans_c_new_alert_t::alert_num
uint8_t alert_num
Definition: ans_c.h:151
ans_c_new_alert_notify_set
sdk_err_t ans_c_new_alert_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer New Alert characteristic notify.
ANS_C_CTRL_PT_NTF_NEW_INC_ALERT_IMME
@ ANS_C_CTRL_PT_NTF_NEW_INC_ALERT_IMME
Definition: ans_c.h:122
ans_c_alert_cat_id_t
ans_c_alert_cat_id_t
Alert Notification Service Categories of alerts/messages.
Definition: ans_c.h:100
gr_includes.h
Include Files API.
ANS_C_CAT_ID_EMAIL
@ ANS_C_CAT_ID_EMAIL
Definition: ans_c.h:102
ans_c_evt_t::evt_type
ans_c_evt_type_t evt_type
Definition: ans_c.h:188
ans_c_handles_t::ans_sup_new_alert_cat_handle
uint16_t ans_sup_new_alert_cat_handle
Definition: ans_c.h:175
ans_c_evt_t::sup_new_alert_cat_ids
uint16_t sup_new_alert_cat_ids
Definition: ans_c.h:191
ANS_C_EVT_UNREAD_ALERT_STA_NTF_SET_SUCCESS
@ ANS_C_EVT_UNREAD_ALERT_STA_NTF_SET_SUCCESS
Definition: ans_c.h:133
ans_c_handles_t::ans_unread_alert_handle
uint16_t ans_unread_alert_handle
Definition: ans_c.h:179
ANS_C_CTRL_PT_EN_UNREAD_CAT_STA_NTF
@ ANS_C_CTRL_PT_EN_UNREAD_CAT_STA_NTF
Definition: ans_c.h:119
ans_c_unread_alert_notify_set
sdk_err_t ans_c_unread_alert_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer Unread Alert characteristic notify.
ans_c_handles_t::ans_sup_unread_alert_cat_handle
uint16_t ans_sup_unread_alert_cat_handle
Definition: ans_c.h:178
ans_c_handles_t::ans_srvc_end_handle
uint16_t ans_srvc_end_handle
Definition: ans_c.h:174
ans_c_ctrl_pt_t
Alert Notification Service Client Control Point value.
Definition: ans_c.h:165
ANS_C_EVT_CTRL_POINT_SET_SUCCESS
@ ANS_C_EVT_CTRL_POINT_SET_SUCCESS
Definition: ans_c.h:138
ANS_C_EVT_NEW_ALERT_NTF_SET_SUCCESS
@ ANS_C_EVT_NEW_ALERT_NTF_SET_SUCCESS
Definition: ans_c.h:132
AANS_C_CAT_ID_NB
@ AANS_C_CAT_ID_NB
Definition: ans_c.h:111
ans_c_unread_alert_t
Alert Notification Service Client decoded Unread Alert Status value.
Definition: ans_c.h:158
ANS_C_CTRL_PT_EN_NEW_INC_ALERT_NTF
@ ANS_C_CTRL_PT_EN_NEW_INC_ALERT_NTF
Definition: ans_c.h:118
ANS_C_CAT_ID_SCHEDULE
@ ANS_C_CAT_ID_SCHEDULE
Definition: ans_c.h:108
ans_c_evt_t::conn_idx
uint8_t conn_idx
Definition: ans_c.h:187
ANS_C_CAT_ID_MISSED_CALL
@ ANS_C_CAT_ID_MISSED_CALL
Definition: ans_c.h:105
ans_c_handles_t::ans_new_alert_handle
uint16_t ans_new_alert_handle
Definition: ans_c.h:176
ANS_C_CAT_ID_CALL
@ ANS_C_CAT_ID_CALL
Definition: ans_c.h:104
ANS_C_CAT_ID_SMPL_ALERT
@ ANS_C_CAT_ID_SMPL_ALERT
Definition: ans_c.h:101
ans_c_sup_new_alert_cat_read
sdk_err_t ans_c_sup_new_alert_cat_read(uint8_t conn_idx)
Read Supported New Alert Category characteristic value.
ans_c_handles_t::ans_srvc_start_handle
uint16_t ans_srvc_start_handle
Definition: ans_c.h:173
ans_client_init
sdk_err_t ans_client_init(ans_c_evt_handler_t evt_handler)
Register ANS Client event handler.
ans_c_new_alert_t::cat_id
ans_c_alert_cat_id_t cat_id
Definition: ans_c.h:150
ble_prf_types.h
Profile/Service Common Types.
ans_c_evt_t::sup_unread_alert_cat_ids
uint16_t sup_unread_alert_cat_ids
Definition: ans_c.h:192
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
ANS_C_CAT_ID_HG_PRIO_ALERT
@ ANS_C_CAT_ID_HG_PRIO_ALERT
Definition: ans_c.h:109
ans_c_evt_handler_t
void(* ans_c_evt_handler_t)(ans_c_evt_t *p_evt)
Alert Notification Service Client event handler type.
Definition: ans_c.h:204
ans_c_handles_t::ans_unread_alert_cccd_handle
uint16_t ans_unread_alert_cccd_handle
Definition: ans_c.h:180
ans_c_sup_unread_alert_cat_read
sdk_err_t ans_c_sup_unread_alert_cat_read(uint8_t conn_idx)
Read Supported Unread Alert Category characteristic value.
ans_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: ans_c.h:172
ANS_C_EVT_SUP_NEW_ALERT_CAT_RECEIV
@ ANS_C_EVT_SUP_NEW_ALERT_CAT_RECEIV
Definition: ans_c.h:134
ans_c_unread_alert_t::cat_id
ans_c_alert_cat_id_t cat_id
Definition: ans_c.h:159
ANS_C_CTRL_PT_DIS_UNREAD_CAT_STA_NTF
@ ANS_C_CTRL_PT_DIS_UNREAD_CAT_STA_NTF
Definition: ans_c.h:121
ans_c_evt_type_t
ans_c_evt_type_t
Alert Notification Service Client Event type.
Definition: ans_c.h:128
ans_c_disc_srvc_start
sdk_err_t ans_c_disc_srvc_start(uint8_t conn_idx)
Discover Alert Notification Service on peer.
ANS_C_CAT_ID_VOICE_MAIL
@ ANS_C_CAT_ID_VOICE_MAIL
Definition: ans_c.h:107
ANS_C_CTRL_PT_NTF_UNREAD_CAT_STA_IMME
@ ANS_C_CTRL_PT_NTF_UNREAD_CAT_STA_IMME
Definition: ans_c.h:123
ans_c_ctrl_point_set
sdk_err_t ans_c_ctrl_point_set(uint8_t conn_idx, ans_c_ctrl_pt_t *p_ctrl_pt)
Set Control Point characteristic value.
ANS_C_EVT_NEW_ALERT_RECEIVE
@ ANS_C_EVT_NEW_ALERT_RECEIVE
Definition: ans_c.h:136
ans_c_new_alert_t
Alert Notification Service Client decoded New Alert value.
Definition: ans_c.h:149
ans_c_unread_alert_t::unread_num
uint8_t unread_num
Definition: ans_c.h:160
ANS_C_CAT_ID_NEWS
@ ANS_C_CAT_ID_NEWS
Definition: ans_c.h:103
ans_c_evt_t::new_alert
ans_c_new_alert_t new_alert
Definition: ans_c.h:193
ans_c_ctrl_pt_t::cmd_id
ans_c_ctrl_pt_id_t cmd_id
Definition: ans_c.h:166
ANS_C_UTF_8_STR_LEN_MAX
#define ANS_C_UTF_8_STR_LEN_MAX
Definition: ans_c.h:72