ancs_c.h
Go to the documentation of this file.
1 /**
2  *****************************************************************************************
3  *
4  * @file ancs_c.h
5  *
6  * @brief ANCS 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 "gr55xx_sys.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 < CFG_MAX_CONNECTIONS ?\
82  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of ANCS Client connections. */
83 #define ANCS_SRVC_UUID 0xd0, 0x00, 0x2d, 0x12, 0x1e, 0x4b, 0x0f, 0xa4,\
84  0x99,0x4e, 0xce, 0xb5, 0x31, 0xf4, 0x05, 0x79 /**< UUID of Apple notification center service. */
85 #define ANCS_NTF_SOURCE_UUID 0xbd, 0x1d, 0xa2, 0x99, 0xe6, 0x25, 0x58, 0x8c,\
86  0xd9, 0x42, 0x01, 0x63, 0x0d, 0x12, 0xbf, 0x9f /**< UUID of notification source. */
87 #define ANCS_CONTROL_POINT_UUID 0xd9, 0xd9, 0xaa, 0xfd, 0xbd, 0x9b, 0x21, 0x98,\
88  0xa8, 0x49, 0xe1, 0x45, 0xf3, 0xd8, 0xd1, 0x69 /**< UUID of control point. */
89 #define ANCS_DATA_SOURCE_UUID 0xfb, 0x7b, 0x7c, 0xce, 0x6a, 0xb3, 0x44, 0xbe,\
90  0xb5, 0x4b, 0xd6, 0x24, 0xe9, 0xc6, 0xea, 0x22 /**< UUID of data source. */
91 
92 /** @} */
93 
94 /**
95  * @defgroup ANCS_ENUM Enumerations
96  * @{
97  */
98 /**@brief Event types that are passed from client to application on an event. */
99 typedef enum
100 {
101  BLE_ANCS_C_EVT_INVALID, /**< ANCS Client invalid event type. */
102  BLE_ANCS_C_EVT_DISCOVERY_CPLT, /**< ANCS Client has found ANCS service and its characteristics. */
103  BLE_ANCS_C_EVT_DISCOVERY_FAILED, /**< ANCS Client found ANCS service failed because of invalid operation or no found at the peer. */
104  BLE_ANCS_C_EVT_NTF_SOURCE_NTF_ENABLED, /**< ANCS Client has enable notification for notification source. */
105  BLE_ANCS_C_EVT_DATA_SOURCE_NTF_ENABLED, /**< ANCS Client has enable notification for data source. */
106  BLE_ANCS_C_EVT_NTF_SOURCE_RECEIVE, /**< ANCS Client has receive notification from notification source. */
107  BLE_ANCS_C_EVT_DATA_SOURCE_RECEIVE, /**< ANCS Client has receive notification from data source. */
110 /** @} */
111 
112 /**
113  * @defgroup ANCS_STRUCT Structures
114  * @{
115  */
116 /**@brief ancs handle structure. */
117 typedef struct
118 {
119  uint16_t ancs_service_handle; /**< Handle of ancs service as provided by a discovery. */
120  uint16_t ancs_ntf_source_handle; /**< Handle of ancs notification source characteristic as provided by a discovery. */
121  uint16_t ancs_ntf_source_cccd_handle; /**< Handle of CCCD of ancs control point characteristic as provided by a discovery. */
122  uint16_t ancs_control_point_handle; /**< Handle of ancs control point characteristic as provided by a discovery. */
123  uint16_t ancs_data_source_handle; /**< Handle of ancs data source characteristic as provided by a discovery. */
124  uint16_t ancs_data_source_cccd_handle; /**< Handle of CCCD of ancs data source characteristic as provided by a discovery. */
126 
127 /**@brief ANCS Client event. */
128 typedef struct
129 {
130  uint8_t conn_idx; /**< The index of the connection. */
131  ble_ancs_c_evt_type_t evt_type; /**< The ANCS event type. */
132 
133 } ancs_c_evt_t;
134 /** @} */
135 
136 /**
137  * @defgroup ANCS_TYPEDEF Typedefs
138  * @{
139  */
140 /**@brief Apple Notification Center Service event handler type.*/
141 typedef void (*ancs_c_evt_handler_t)(ancs_c_evt_t *p_evt);
142 /** @} */
143 
144 /**
145  * @defgroup ANCS_FUNCTION Functions
146  * @{
147  */
148 /**
149  *****************************************************************************************
150  * @brief Initialize ANCS structure of handle.
151  *****************************************************************************************
152  */
154 
155 /**
156  *****************************************************************************************
157  * @brief To access phone's all services about ANCS.
158  *
159  * @param[in] conn_idx: Connection index.
160  *****************************************************************************************
161 */
163 
164 /**
165  *****************************************************************************************
166  * @brief enable ancs notification source CCCD.
167  *
168  * @param[in] conn_idx: Connection index.
169  * @param[in] is_enable: Start or stop the notification.
170  * @return success or not.
171  *****************************************************************************************
172  */
173 sdk_err_t ancs_c_ntf_source_notify_set(uint8_t conn_idx, bool is_enable);
174 
175 /**
176  *****************************************************************************************
177  * @brief enable ancs data source CCCD.
178  *
179  * @param[in] conn_idx: Connection index.
180  * @param[in] is_enable: Start or stop the notification.
181  * @return success or not.
182  *****************************************************************************************
183  */
184 sdk_err_t ancs_c_data_source_notify_set(uint8_t conn_idx, bool is_enable);
185 
186 /**
187  *****************************************************************************************
188  * @brief This function implements writing commands to control points.
189  *
190  * @param[in] conn_idx: Connection index.
191  * @param[in] p_data: Pointer to send out data.
192  * @param[in] length: Length of data sent out.
193  *****************************************************************************************
194  */
195 sdk_err_t ancs_c_write_control_point(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
196 
197 /** @} */
198 
199 #endif
200 /** @} */
201 /** @} */
BLE_ANCS_C_EVT_INVALID
@ BLE_ANCS_C_EVT_INVALID
ANCS Client invalid event type.
Definition: ancs_c.h:101
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:122
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:141
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:103
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:106
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:100
gr55xx_sys.h
GR55XX System API.
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:102
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:108
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:124
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:123
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
ancs_c_att_handles_t
ancs handle structure.
Definition: ancs_c.h:118
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:119
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:121
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:107
ancs_c_evt_t::evt_type
ble_ancs_c_evt_type_t evt_type
The ANCS event type.
Definition: ancs_c.h:131
ancs_c_evt_t
ANCS Client event.
Definition: ancs_c.h:129
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:105
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:104
ancs_c_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: ancs_c.h:130
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:120