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. */
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. */
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  */
153 
154 /**
155  *****************************************************************************************
156  * @brief To access phone's all services about ANCS.
157  *
158  * @param[in] conn_idx: Connection index.
159  *****************************************************************************************
160 */
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
Definition: ancs_c.h:100
ancs_c_att_handles_t::ancs_control_point_handle
uint16_t ancs_control_point_handle
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
Definition: ancs_c.h:102
BLE_ANCS_C_EVT_NTF_SOURCE_RECEIVE
@ BLE_ANCS_C_EVT_NTF_SOURCE_RECEIVE
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
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
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
Definition: ancs_c.h:122
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:257
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
Definition: ancs_c.h:118
ancs_c_att_handles_t::ancs_ntf_source_cccd_handle
uint16_t ancs_ntf_source_cccd_handle
Definition: ancs_c.h:120
BLE_ANCS_C_EVT_DATA_SOURCE_RECEIVE
@ BLE_ANCS_C_EVT_DATA_SOURCE_RECEIVE
Definition: ancs_c.h:106
ancs_c_evt_t::evt_type
ble_ancs_c_evt_type_t evt_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
Definition: ancs_c.h:104
BLE_ANCS_C_EVT_NTF_SOURCE_NTF_ENABLED
@ BLE_ANCS_C_EVT_NTF_SOURCE_NTF_ENABLED
Definition: ancs_c.h:103
ancs_c_evt_t::conn_idx
uint8_t conn_idx
Definition: ancs_c.h:129
ancs_c_att_handles_t::ancs_ntf_source_handle
uint16_t ancs_ntf_source_handle
Definition: ancs_c.h:119