ancs_protocol.h
Go to the documentation of this file.
1 /**
2  *******************************************************************************
3  *
4  * @file ancs_protocol.h
5  *
6  * @brief Apple Notification Center Service Protocol 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 #ifndef _ANCS_PROTOCOL_H_
38 #define _ANCS_PROTOCOL_H_
39 
40 #include "gr_includes.h"
41 #include <stdint.h>
42 
43 /** Maximum allowed value for attribute length */
44 #ifndef CFG_ANCS_ATTRIBUTE_MAXLEN
45 #define CFG_ANCS_ATTRIBUTE_MAXLEN 500
46 #endif
47 
48 /** Attribute ID element without maximum length */
49 #define ANCS_ATTR(ID) ((uint32_t) 0x80000000 | ((uint8_t) ID))
50 
51 /** Attribute ID element with maximum length */
52 #define ANCS_ATTR_MAXLEN(ID, LEN) ((uint32_t) 0x80000000 | ((uint8_t) ID) | ((uint16_t) LEN << 8))
53 
54 /**
55  * @defgroup ANCS_ENUM Enumerations
56  * @{
57  */
58 
59 /**@brief IDs for iOS notification attributes. */
60 typedef enum
61 {
62  ANCS_NOTIF_ATTR_ID_APP_IDENTIFIER = 0, /**< Identify that the attribute data is of an "App Identifier" type. */
63  ANCS_NOTIF_ATTR_ID_TITLE, /**< Identify that the attribute data is a "Title". */
64  ANCS_NOTIF_ATTR_ID_SUBTITLE, /**< Identify that the attribute data is a "Subtitle". */
65  ANCS_NOTIF_ATTR_ID_MESSAGE, /**< Identify that the attribute data is a "Message". */
66  ANCS_NOTIF_ATTR_ID_MESSAGE_SIZE, /**< Identify that the attribute data is a "Message Size". */
67  ANCS_NOTIF_ATTR_ID_DATE, /**< Identify that the attribute data is a "Date". */
68  ANCS_NOTIF_ATTR_ID_POSITIVE_ACTION_LABEL, /**< The notification has a "Positive action" that can be executed associated with it. */
69  ANCS_NOTIF_ATTR_ID_NEGATIVE_ACTION_LABEL, /**< The notification has a "Negative action" that can be executed associated with it. */
71 
72 /**@brief Category IDs for iOS notifications. */
73 typedef enum
74 {
75  ANCS_CATEGORY_ID_OTHER, /**< The iOS notification belongs to the "other" category. */
76  ANCS_CATEGORY_ID_INCOMING_CALL, /**< The iOS notification belongs to the "Incoming Call" category. */
77  ANCS_CATEGORY_ID_MISSED_CALL, /**< The iOS notification belongs to the "Missed Call" category. */
78  ANCS_CATEGORY_ID_VOICE_MAIL, /**< The iOS notification belongs to the "Voice Mail" category. */
79  ANCS_CATEGORY_ID_SOCIAL, /**< The iOS notification belongs to the "Social" category. */
80  ANCS_CATEGORY_ID_SCHEDULE, /**< The iOS notification belongs to the "Schedule" category. */
81  ANCS_CATEGORY_ID_EMAIL, /**< The iOS notification belongs to the "E-mail" category. */
82  ANCS_CATEGORY_ID_NEWS, /**< The iOS notification belongs to the "News" category. */
83  ANCS_CATEGORY_ID_HEALTH_AND_FITNESS, /**< The iOS notification belongs to the "Health and Fitness" category. */
84  ANCS_CATEGORY_ID_BUSINESS_AND_FINANCE, /**< The iOS notification belongs to the "Buisness and Finance" category. */
85  ANCS_CATEGORY_ID_LOCATION, /**< The iOS notification belongs to the "Location" category. */
86  ANCS_CATEGORY_ID_ENTERTAINMENT /**< The iOS notification belongs to the "Entertainment" category. */
88 
89 /**@brief Event IDs for iOS notifications. */
90 typedef enum
91 {
92  ANCS_EVENT_ID_NOTIFICATION_ADDED, /**< The iOS notification was added. */
93  ANCS_EVENT_ID_NOTIFICATION_MODIFIED, /**< The iOS notification was modified. */
94  ANCS_EVENT_ID_NOTIFICATION_REMOVED /**< The iOS notification was removed. */
96 
97 /**@brief ID for actions that can be performed for iOS notifications. */
98 typedef enum
99 {
100  ACTION_ID_POSITIVE = 0, /**< Positive action. */
101  ACTION_ID_NEGATIVE /**< Negative action. */
103 
104 /**@brief ctrl point command that can be performed for iOS notifications. */
105 typedef enum
106 {
107  CTRL_POINT_GET_NTF_ATTRIBUTE = 0, /**< Request attributes to be sent from the NP to the NC for a given notification. */
108  CTRL_POINT_GET_APP_ATTRIBUTE, /**< Request attributes to be sent from the NP to the NC for a given iOS app. */
109  CTRL_POINT_PERFORM_NTF_ACTION, /**< Request an action to be performed on a given notification, for example, dismiss an alarm. */
111 
112 /** @} */
113 
114 /**
115  * @defgroup ANCS_STRUCT Structures
116  * @{
117  */
118 
119 /**@brief notification flags that can be performed for iOS notifications. */
120 typedef struct
121 {
122  uint8_t silent : 1; /**< If this flag is set, the notification has a low priority. */
123  uint8_t important : 1; /**< If this flag is set, the notification has a high priority. */
124  uint8_t pre_existing : 1; /**< If this flag is set, the notification is pre-existing. */
125  uint8_t positive_action : 1; /**< If this flag is set, the notification has a positive action that can be taken. */
126  uint8_t negative_action : 1; /**< If this flag is set, the notification has a negative action that can be taken. */
128 
129 /**@brief iOS notification structure. */
130 typedef struct
131 {
132  ancs_evt_id_t event_id; /**< Whether the notification was added, removed, or modified. */
133  ancs_ntf_flags_t event_flags; /**< Whether the notification was added, removed, or modified. */
134  ancs_category_id_t category_id; /**< Classification of the notification type, for example, email or location. */
135  uint8_t category_count; /**< Current number of active notifications for this category ID. */
136  uint32_t notification_uid; /**< Notification UID. */
138 
139 /** @} */
140 
141 /**
142  * @defgroup ANCS_FUNCTION Functions
143  * @{
144  */
145 /**
146  *****************************************************************************************
147  * @brief Get notification attribute
148  *
149  * @param[in] uid: The UID of notify message
150  * @param[in] noti_attr: The notification attribute
151  *
152  *****************************************************************************************
153  */
154 void ancs_notify_attr_get(int uid, char noti_attr);
155 
156 /**
157  *****************************************************************************************
158  * @brief ancs perform action
159  *
160  * @param[in] uid: The UID of notify message
161  * @param[in] action: The action status defined by specification
162  *
163  *****************************************************************************************
164  */
165 void ancs_action_perform(int uid, int action);
166 
167 /**
168  *****************************************************************************************
169  * @brief get ancs phone call UID
170  *
171  * @return phone call notify message UID
172  *****************************************************************************************
173  */
174 int ancs_get_uid(void);
175 
176 /**
177  *****************************************************************************************
178  * @brief Decode notification source message.
179  *
180  * @param[in] p_data: Pointer to the parameters of the read request.
181  * @param[in] length: The Length of read value
182  *****************************************************************************************
183  */
184 void ancs_decode_notification_source(uint8_t *p_data, uint16_t length);
185 
186 /**
187  *****************************************************************************************
188  * @brief Decode data source message.
189  *
190  * @param[in] p_data: Pointer to the parameters of the read request.
191  * @param[in] length: Length of read data
192  *****************************************************************************************
193  */
194 void ancs_decode_data_source(uint8_t *p_data, uint16_t length);
195 /** @} */
196 #endif
197 
198 
ANCS_NOTIF_ATTR_ID_SUBTITLE
@ ANCS_NOTIF_ATTR_ID_SUBTITLE
Identify that the attribute data is a "Subtitle".
Definition: ancs_protocol.h:64
ANCS_CATEGORY_ID_OTHER
@ ANCS_CATEGORY_ID_OTHER
The iOS notification belongs to the "other" category.
Definition: ancs_protocol.h:75
ANCS_CATEGORY_ID_SCHEDULE
@ ANCS_CATEGORY_ID_SCHEDULE
The iOS notification belongs to the "Schedule" category.
Definition: ancs_protocol.h:80
CTRL_POINT_GET_APP_ATTRIBUTE
@ CTRL_POINT_GET_APP_ATTRIBUTE
Request attributes to be sent from the NP to the NC for a given iOS app.
Definition: ancs_protocol.h:108
ANCS_NOTIF_ATTR_ID_MESSAGE_SIZE
@ ANCS_NOTIF_ATTR_ID_MESSAGE_SIZE
Identify that the attribute data is a "Message Size".
Definition: ancs_protocol.h:66
ntf_source_pdu_t
iOS notification structure.
Definition: ancs_protocol.h:131
ACTION_ID_NEGATIVE
@ ACTION_ID_NEGATIVE
Negative action.
Definition: ancs_protocol.h:101
ntf_source_pdu_t::event_flags
ancs_ntf_flags_t event_flags
Whether the notification was added, removed, or modified.
Definition: ancs_protocol.h:133
ancs_ntf_flags_t::pre_existing
uint8_t pre_existing
If this flag is set, the notification is pre-existing.
Definition: ancs_protocol.h:124
ancs_ntf_flags_t::silent
uint8_t silent
If this flag is set, the notification has a low priority.
Definition: ancs_protocol.h:122
ANCS_NOTIF_ATTR_ID_POSITIVE_ACTION_LABEL
@ ANCS_NOTIF_ATTR_ID_POSITIVE_ACTION_LABEL
The notification has a "Positive action" that can be executed associated with it.
Definition: ancs_protocol.h:68
ancs_ntf_flags_t::important
uint8_t important
If this flag is set, the notification has a high priority.
Definition: ancs_protocol.h:123
ntf_source_pdu_t::event_id
ancs_evt_id_t event_id
Whether the notification was added, removed, or modified.
Definition: ancs_protocol.h:132
ANCS_CATEGORY_ID_ENTERTAINMENT
@ ANCS_CATEGORY_ID_ENTERTAINMENT
The iOS notification belongs to the "Entertainment" category.
Definition: ancs_protocol.h:86
ancs_decode_data_source
void ancs_decode_data_source(uint8_t *p_data, uint16_t length)
Decode data source message.
ANCS_NOTIF_ATTR_ID_MESSAGE
@ ANCS_NOTIF_ATTR_ID_MESSAGE
Identify that the attribute data is a "Message".
Definition: ancs_protocol.h:65
gr_includes.h
Include Files API.
ANCS_EVENT_ID_NOTIFICATION_MODIFIED
@ ANCS_EVENT_ID_NOTIFICATION_MODIFIED
The iOS notification was modified.
Definition: ancs_protocol.h:93
ancs_evt_id_t
ancs_evt_id_t
Event IDs for iOS notifications.
Definition: ancs_protocol.h:91
ancs_category_id_t
ancs_category_id_t
Category IDs for iOS notifications.
Definition: ancs_protocol.h:74
ancs_notification_attr_t
ancs_notification_attr_t
IDs for iOS notification attributes.
Definition: ancs_protocol.h:61
ntf_source_pdu_t::category_count
uint8_t category_count
Current number of active notifications for this category ID.
Definition: ancs_protocol.h:135
ancs_decode_notification_source
void ancs_decode_notification_source(uint8_t *p_data, uint16_t length)
Decode notification source message.
CTRL_POINT_PERFORM_NTF_ACTION
@ CTRL_POINT_PERFORM_NTF_ACTION
Request an action to be performed on a given notification, for example, dismiss an alarm.
Definition: ancs_protocol.h:109
ancs_c_ctrl_point_t
ancs_c_ctrl_point_t
ctrl point command that can be performed for iOS notifications.
Definition: ancs_protocol.h:106
ANCS_CATEGORY_ID_BUSINESS_AND_FINANCE
@ ANCS_CATEGORY_ID_BUSINESS_AND_FINANCE
The iOS notification belongs to the "Buisness and Finance" category.
Definition: ancs_protocol.h:84
ancs_notify_attr_get
void ancs_notify_attr_get(int uid, char noti_attr)
Get notification attribute.
ntf_source_pdu_t::category_id
ancs_category_id_t category_id
Classification of the notification type, for example, email or location.
Definition: ancs_protocol.h:134
ANCS_NOTIF_ATTR_ID_APP_IDENTIFIER
@ ANCS_NOTIF_ATTR_ID_APP_IDENTIFIER
Identify that the attribute data is of an "App Identifier" type.
Definition: ancs_protocol.h:62
ANCS_NOTIF_ATTR_ID_NEGATIVE_ACTION_LABEL
@ ANCS_NOTIF_ATTR_ID_NEGATIVE_ACTION_LABEL
The notification has a "Negative action" that can be executed associated with it.
Definition: ancs_protocol.h:69
ANCS_CATEGORY_ID_VOICE_MAIL
@ ANCS_CATEGORY_ID_VOICE_MAIL
The iOS notification belongs to the "Voice Mail" category.
Definition: ancs_protocol.h:78
ANCS_CATEGORY_ID_LOCATION
@ ANCS_CATEGORY_ID_LOCATION
The iOS notification belongs to the "Location" category.
Definition: ancs_protocol.h:85
CTRL_POINT_GET_NTF_ATTRIBUTE
@ CTRL_POINT_GET_NTF_ATTRIBUTE
Request attributes to be sent from the NP to the NC for a given notification.
Definition: ancs_protocol.h:107
ancs_ntf_flags_t
notification flags that can be performed for iOS notifications.
Definition: ancs_protocol.h:121
ancs_ntf_flags_t::negative_action
uint8_t negative_action
If this flag is set, the notification has a negative action that can be taken.
Definition: ancs_protocol.h:126
ancs_c_action_id_t
ancs_c_action_id_t
ID for actions that can be performed for iOS notifications.
Definition: ancs_protocol.h:99
ANCS_CATEGORY_ID_EMAIL
@ ANCS_CATEGORY_ID_EMAIL
The iOS notification belongs to the "E-mail" category.
Definition: ancs_protocol.h:81
ANCS_CATEGORY_ID_HEALTH_AND_FITNESS
@ ANCS_CATEGORY_ID_HEALTH_AND_FITNESS
The iOS notification belongs to the "Health and Fitness" category.
Definition: ancs_protocol.h:83
ancs_ntf_flags_t::positive_action
uint8_t positive_action
If this flag is set, the notification has a positive action that can be taken.
Definition: ancs_protocol.h:125
ANCS_CATEGORY_ID_MISSED_CALL
@ ANCS_CATEGORY_ID_MISSED_CALL
The iOS notification belongs to the "Missed Call" category.
Definition: ancs_protocol.h:77
ANCS_CATEGORY_ID_SOCIAL
@ ANCS_CATEGORY_ID_SOCIAL
The iOS notification belongs to the "Social" category.
Definition: ancs_protocol.h:79
ACTION_ID_POSITIVE
@ ACTION_ID_POSITIVE
Positive action.
Definition: ancs_protocol.h:100
ancs_get_uid
int ancs_get_uid(void)
get ancs phone call UID
ANCS_NOTIF_ATTR_ID_DATE
@ ANCS_NOTIF_ATTR_ID_DATE
Identify that the attribute data is a "Date".
Definition: ancs_protocol.h:67
ANCS_CATEGORY_ID_NEWS
@ ANCS_CATEGORY_ID_NEWS
The iOS notification belongs to the "News" category.
Definition: ancs_protocol.h:82
ancs_action_perform
void ancs_action_perform(int uid, int action)
ancs perform action
ntf_source_pdu_t::notification_uid
uint32_t notification_uid
Notification UID.
Definition: ancs_protocol.h:136
ANCS_CATEGORY_ID_INCOMING_CALL
@ ANCS_CATEGORY_ID_INCOMING_CALL
The iOS notification belongs to the "Incoming Call" category.
Definition: ancs_protocol.h:76
ANCS_EVENT_ID_NOTIFICATION_ADDED
@ ANCS_EVENT_ID_NOTIFICATION_ADDED
The iOS notification was added.
Definition: ancs_protocol.h:92
ANCS_EVENT_ID_NOTIFICATION_REMOVED
@ ANCS_EVENT_ID_NOTIFICATION_REMOVED
The iOS notification was removed.
Definition: ancs_protocol.h:94
ANCS_NOTIF_ATTR_ID_TITLE
@ ANCS_NOTIF_ATTR_ID_TITLE
Identify that the attribute data is a "Title".
Definition: ancs_protocol.h:63