ancs_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file ancs_c.h
5 *
6 * @brief Apple Notification Center 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 /**
39 * @addtogroup BLE_SRV BLE Services
40 * @{
41 * @brief Definitions and prototypes for the BLE Service interface.
42 */
43
44 /**
45 * @defgroup BLE_SDK_ANCS Apple Notification Center Service (ANCS)
46 * @{
47 * @brief Definitions and prototypes for the ANCS interface.
48
49 * @details ANCS provides a way for BLE devices to receive IOS mobile phone notifications.
50 * The service consists of three eigenvalues, including notification source,
51 * data source, control point.
52 *
53 * The application needs to call \ref ancs_c_client_init() to initialize, and then
54 * use \ref ancs_c_discovery_service() to discover ANCS-related services on IOS devices.
55 * After discovery, ancs_c_on_browse_svc_evt function is called to parse and save
56 * the handle corresponding to each service. These handles are used for data
57 * transmission.
58 *
59 * Secondly, use \ref ancs_c_ntf_source_notify_set() and \ref ancs_c_data_source_notify_set()
60 * to enable notification source & data source's CCD. The IOS notification is then sent to the
61 * BLE device side immediately.
62 *
63 * Finally, the application can use \ref ancs_decode_notification_source() and
64 * \ref ancs_decode_data_source() to parse the ANCS message and \ref ancs_c_write_control_point()
65 * to command the control point. For specific commands, please refer to the ANCS protocol specification.
66 *
67 */
68
69 #ifndef _ANCS_H_
70 #define _ANCS_H_
71
72 #include "gr_includes.h"
73 #include "ble_prf_types.h"
74 #include "custom_config.h"
75 #include <stdint.h>
76
77 /**
78 * @defgroup ANCS_C_MACRO Defines
79 * @{
80 */
81 #define ANCS_C_CONNECTION_MAX 10 /**< Maximum number of ANCS Client connections. */
82 #define ANCS_SRVC_UUID 0xd0, 0x00, 0x2d, 0x12, 0x1e, 0x4b, 0x0f, 0xa4,\
83 0x99,0x4e, 0xce, 0xb5, 0x31, 0xf4, 0x05, 0x79 /**< UUID of Apple notification center service. */
84 #define ANCS_NTF_SOURCE_UUID 0xbd, 0x1d, 0xa2, 0x99, 0xe6, 0x25, 0x58, 0x8c,\
85 0xd9, 0x42, 0x01, 0x63, 0x0d, 0x12, 0xbf, 0x9f /**< UUID of notification source. */
86 #define ANCS_CONTROL_POINT_UUID 0xd9, 0xd9, 0xaa, 0xfd, 0xbd, 0x9b, 0x21, 0x98,\
87 0xa8, 0x49, 0xe1, 0x45, 0xf3, 0xd8, 0xd1, 0x69 /**< UUID of control point. */
88 #define ANCS_DATA_SOURCE_UUID 0xfb, 0x7b, 0x7c, 0xce, 0x6a, 0xb3, 0x44, 0xbe,\
89 0xb5, 0x4b, 0xd6, 0x24, 0xe9, 0xc6, 0xea, 0x22 /**< UUID of data source. */
90
91 /** @} */
92
93 /**
94 * @defgroup ANCS_ENUM Enumerations
95 * @{
96 */
97 /**@brief Event types that are passed from client to application on an event. */
98 typedef enum
99 {
100 BLE_ANCS_C_EVT_INVALID, /**< ANCS Client invalid event type. */
101 BLE_ANCS_C_EVT_DISCOVERY_CPLT, /**< ANCS Client has found ANCS service and its characteristics. */
102 BLE_ANCS_C_EVT_DISCOVERY_FAILED, /**< ANCS Client found ANCS service failed because of invalid operation or no found at the peer. */
103 BLE_ANCS_C_EVT_NTF_SOURCE_NTF_ENABLED, /**< ANCS Client has enable notification for notification source. */
104 BLE_ANCS_C_EVT_DATA_SOURCE_NTF_ENABLED, /**< ANCS Client has enable notification for data source. */
105 BLE_ANCS_C_EVT_NTF_SOURCE_RECEIVE, /**< ANCS Client has receive notification from notification source. */
106 BLE_ANCS_C_EVT_DATA_SOURCE_RECEIVE, /**< ANCS Client has receive notification from data source. */
107 BLE_ANCS_C_EVT_WRITE_OP_ERR,
108 } ble_ancs_c_evt_type_t;
109 /** @} */
110
111 /**
112 * @defgroup ANCS_STRUCT Structures
113 * @{
114 */
115 /**@brief ancs handle structure. */
116 typedef struct
117 {
118 uint16_t ancs_service_handle; /**< Handle of ancs service as provided by a discovery. */
119 uint16_t ancs_ntf_source_handle; /**< Handle of ancs notification source characteristic as provided by a discovery. */
120 uint16_t ancs_ntf_source_cccd_handle; /**< Handle of CCCD of ancs control point characteristic as provided by a discovery. */
121 uint16_t ancs_control_point_handle; /**< Handle of ancs control point characteristic as provided by a discovery. */
122 uint16_t ancs_data_source_handle; /**< Handle of ancs data source characteristic as provided by a discovery. */
123 uint16_t ancs_data_source_cccd_handle; /**< Handle of CCCD of ancs data source characteristic as provided by a discovery. */
124 }ancs_c_att_handles_t;
125
126 /**@brief ANCS Client event. */
127 typedef struct
128 {
129 uint8_t conn_idx; /**< The index of the connection. */
130 ble_ancs_c_evt_type_t evt_type; /**< The ANCS event type. */
131
132 } ancs_c_evt_t;
133 /** @} */
134
135 /**
136 * @defgroup ANCS_TYPEDEF Typedefs
137 * @{
138 */
139 /**@brief Apple Notification Center Service event handler type.*/
140 typedef void (*ancs_c_evt_handler_t)(ancs_c_evt_t *p_evt);
141 /** @} */
142
143 /**
144 * @defgroup ANCS_FUNCTION Functions
145 * @{
146 */
147 /**
148 *****************************************************************************************
149 * @brief Initialize ANCS structure of handle.
150 *****************************************************************************************
151 */
152 sdk_err_t ancs_c_client_init(ancs_c_evt_handler_t evt_handler);
153
154 /**
155 *****************************************************************************************
156 * @brief To access phone's all services about ANCS.
157 *
158 * @param[in] conn_idx: Connection index.
159 *****************************************************************************************
160 */
161 sdk_err_t ancs_c_discovery_service(uint8_t conn_idx);
162
163 /**
164 *****************************************************************************************
165 * @brief enable ancs notification source CCCD.
166 *
167 * @param[in] conn_idx: Connection index.
168 * @param[in] is_enable: Start or stop the notification.
169 * @return success or not.
170 *****************************************************************************************
171 */
172 sdk_err_t ancs_c_ntf_source_notify_set(uint8_t conn_idx, bool is_enable);
173
174 /**
175 *****************************************************************************************
176 * @brief enable ancs data source CCCD.
177 *
178 * @param[in] conn_idx: Connection index.
179 * @param[in] is_enable: Start or stop the notification.
180 * @return success or not.
181 *****************************************************************************************
182 */
183 sdk_err_t ancs_c_data_source_notify_set(uint8_t conn_idx, bool is_enable);
184
185 /**
186 *****************************************************************************************
187 * @brief This function implements writing commands to control points.
188 *
189 * @param[in] conn_idx: Connection index.
190 * @param[in] p_data: Pointer to send out data.
191 * @param[in] length: Length of data sent out.
192 *****************************************************************************************
193 */
194 sdk_err_t ancs_c_write_control_point(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
195
196 /** @} */
197
198 #endif
199 /** @} */
200 /** @} */
BLE_ANCS_C_EVT_INVALID
@ BLE_ANCS_C_EVT_INVALID
ANCS Client invalid event type.
Definition: ancs_c.h:100
ancs_c_att_handles_t::ancs_control_point_handle
uint16_t ancs_control_point_handle
Handle of ancs control point characteristic as provided by a discovery.
Definition: ancs_c.h:121
ancs_c_evt_handler_t
void(* ancs_c_evt_handler_t)(ancs_c_evt_t *p_evt)
Apple Notification Center Service event handler type.
Definition: ancs_c.h:140
ancs_c_write_control_point
sdk_err_t ancs_c_write_control_point(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
This function implements writing commands to control points.
BLE_ANCS_C_EVT_DISCOVERY_FAILED
@ BLE_ANCS_C_EVT_DISCOVERY_FAILED
ANCS Client found ANCS service failed because of invalid operation or no found at the peer.
Definition: ancs_c.h:102
BLE_ANCS_C_EVT_NTF_SOURCE_RECEIVE
@ BLE_ANCS_C_EVT_NTF_SOURCE_RECEIVE
ANCS Client has receive notification from notification source.
Definition: ancs_c.h:105
gr_includes.h
Include Files API.
ble_ancs_c_evt_type_t
ble_ancs_c_evt_type_t
Event types that are passed from client to application on an event.
Definition: ancs_c.h:99
BLE_ANCS_C_EVT_DISCOVERY_CPLT
@ BLE_ANCS_C_EVT_DISCOVERY_CPLT
ANCS Client has found ANCS service and its characteristics.
Definition: ancs_c.h:101
ancs_c_data_source_notify_set
sdk_err_t ancs_c_data_source_notify_set(uint8_t conn_idx, bool is_enable)
enable ancs data source CCCD.
BLE_ANCS_C_EVT_WRITE_OP_ERR
@ BLE_ANCS_C_EVT_WRITE_OP_ERR
Definition: ancs_c.h:107
ancs_c_discovery_service
sdk_err_t ancs_c_discovery_service(uint8_t conn_idx)
To access phone's all services about ANCS.
ble_prf_types.h
Profile/Service Common Types.
ancs_c_att_handles_t::ancs_data_source_cccd_handle
uint16_t ancs_data_source_cccd_handle
Handle of CCCD of ancs data source characteristic as provided by a discovery.
Definition: ancs_c.h:123
ancs_c_client_init
sdk_err_t ancs_c_client_init(ancs_c_evt_handler_t evt_handler)
Initialize ANCS structure of handle.
ancs_c_att_handles_t::ancs_data_source_handle
uint16_t ancs_data_source_handle
Handle of ancs data source characteristic as provided by a discovery.
Definition: ancs_c.h:122
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
ancs_c_att_handles_t
ancs handle structure.
Definition: ancs_c.h:117
ancs_c_ntf_source_notify_set
sdk_err_t ancs_c_ntf_source_notify_set(uint8_t conn_idx, bool is_enable)
enable ancs notification source CCCD.
ancs_c_att_handles_t::ancs_service_handle
uint16_t ancs_service_handle
Handle of ancs service as provided by a discovery.
Definition: ancs_c.h:118
ancs_c_att_handles_t::ancs_ntf_source_cccd_handle
uint16_t ancs_ntf_source_cccd_handle
Handle of CCCD of ancs control point characteristic as provided by a discovery.
Definition: ancs_c.h:120
BLE_ANCS_C_EVT_DATA_SOURCE_RECEIVE
@ BLE_ANCS_C_EVT_DATA_SOURCE_RECEIVE
ANCS Client has receive notification from data source.
Definition: ancs_c.h:106
ancs_c_evt_t::evt_type
ble_ancs_c_evt_type_t evt_type
The ANCS event type.
Definition: ancs_c.h:130
ancs_c_evt_t
ANCS Client event.
Definition: ancs_c.h:128
BLE_ANCS_C_EVT_DATA_SOURCE_NTF_ENABLED
@ BLE_ANCS_C_EVT_DATA_SOURCE_NTF_ENABLED
ANCS Client has enable notification for data source.
Definition: ancs_c.h:104
BLE_ANCS_C_EVT_NTF_SOURCE_NTF_ENABLED
@ BLE_ANCS_C_EVT_NTF_SOURCE_NTF_ENABLED
ANCS Client has enable notification for notification source.
Definition: ancs_c.h:103
ancs_c_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: ancs_c.h:129
ancs_c_att_handles_t::ancs_ntf_source_handle
uint16_t ancs_ntf_source_handle
Handle of ancs notification source characteristic as provided by a discovery.
Definition: ancs_c.h:119