ble_ans_c.h 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418
  1. /**
  2. * Copyright (c) 2012 - 2020, Nordic Semiconductor ASA
  3. *
  4. * All rights reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. * 1. Redistributions of source code must retain the above copyright notice, this
  10. * list of conditions and the following disclaimer.
  11. *
  12. * 2. Redistributions in binary form, except as embedded into a Nordic
  13. * Semiconductor ASA integrated circuit in a product or a software update for
  14. * such product, must reproduce the above copyright notice, this list of
  15. * conditions and the following disclaimer in the documentation and/or other
  16. * materials provided with the distribution.
  17. *
  18. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  19. * contributors may be used to endorse or promote products derived from this
  20. * software without specific prior written permission.
  21. *
  22. * 4. This software, with or without modification, must only be used with a
  23. * Nordic Semiconductor ASA integrated circuit.
  24. *
  25. * 5. Any software provided in binary form under this license must not be reverse
  26. * engineered, decompiled, modified and/or disassembled.
  27. *
  28. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  29. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  32. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  37. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38. *
  39. */
  40. /** @file
  41. *
  42. * @defgroup ble_ans_c Alert Notification Service Client
  43. * @{
  44. * @ingroup ble_sdk_srv
  45. * @brief Alert Notification module.
  46. *
  47. * @details This module implements the Alert Notification Client according to the
  48. * Alert Notification Profile.
  49. *
  50. * @note The application must register this module as the BLE event observer by using the
  51. * NRF_SDH_BLE_OBSERVER macro. Example:
  52. * @code
  53. * ble_ans_c_t instance;
  54. * NRF_SDH_BLE_OBSERVER(anything, BLE_ANS_C_BLE_OBSERVER_PRIO,
  55. * ble_ans_c_on_ble_evt, &instance);
  56. * @endcode
  57. *
  58. * @note Attention!
  59. * To maintain compliance with Nordic Semiconductor ASA Bluetooth profile
  60. * qualification listings, this section of source code must not be modified.
  61. */
  62. #ifndef BLE_ANS_C_H__
  63. #define BLE_ANS_C_H__
  64. #include "ble.h"
  65. #include "ble_gatts.h"
  66. #include "ble_types.h"
  67. #include "sdk_common.h"
  68. #include "ble_srv_common.h"
  69. #include "ble_db_discovery.h"
  70. #include "nrf_ble_gq.h"
  71. #include "nrf_sdh_ble.h"
  72. #ifdef __cplusplus
  73. extern "C" {
  74. #endif
  75. /**@brief Macro for defining a ble_ans_c instance.
  76. *
  77. * @param _name Name of the instance.
  78. * @hideinitializer
  79. */
  80. #define BLE_ANS_C_DEF(_name) \
  81. static ble_ans_c_t _name; \
  82. NRF_SDH_BLE_OBSERVER(_name ## _obs, \
  83. BLE_ANS_C_BLE_OBSERVER_PRIO, \
  84. ble_ans_c_on_ble_evt, &_name)
  85. /** @brief Macro for defining multiple ble_ans_c instances.
  86. *
  87. * @param _name Name of the array of instances.
  88. * @param _cnt Number of instances to define.
  89. * @hideinitializer
  90. */
  91. #define BLE_ANS_C_ARRAY_DEF(_name, _cnt) \
  92. static ble_ans_c_t _name[_cnt]; \
  93. NRF_SDH_BLE_OBSERVERS(_name ## _obs, \
  94. BLE_ANS_C_BLE_OBSERVER_PRIO, \
  95. ble_ans_c_on_ble_evt, &_name, _cnt)
  96. // Forward declaration of the ble_ans_c_t type.
  97. typedef struct ble_ans_c_s ble_ans_c_t;
  98. /** Alert types, as defined in the alert category ID. UUID: 0x2A43. */
  99. typedef enum
  100. {
  101. ANS_TYPE_SIMPLE_ALERT = 0, /**< General text alert or non-text alert.*/
  102. ANS_TYPE_EMAIL = 1, /**< Email message arrives.*/
  103. ANS_TYPE_NEWS = 2, /**< News feeds such as RSS, Atom.*/
  104. ANS_TYPE_NOTIFICATION_CALL = 3, /**< Incoming call.*/
  105. ANS_TYPE_MISSED_CALL = 4, /**< Missed call.*/
  106. ANS_TYPE_SMS_MMS = 5, /**< SMS or MMS message arrives.*/
  107. ANS_TYPE_VOICE_MAIL = 6, /**< Voice mail.*/
  108. ANS_TYPE_SCHEDULE = 7, /**< Alert that occurs on calendar, planner.*/
  109. ANS_TYPE_HIGH_PRIORITIZED_ALERT = 8, /**< Alert to be handled as high priority.*/
  110. ANS_TYPE_INSTANT_MESSAGE = 9, /**< Alert for incoming instant messages.*/
  111. ANS_TYPE_ALL_ALERTS = 0xFF /**< Identifies all alerts. */
  112. } ble_ans_category_id_t;
  113. /** Alert notification control point commands, as defined in the Alert Notification Specification.
  114. * UUID: 0x2A44.
  115. */
  116. typedef enum
  117. {
  118. ANS_ENABLE_NEW_INCOMING_ALERT_NOTIFICATION = 0, /**< Enable New Incoming Alert Notification.*/
  119. ANS_ENABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION = 1, /**< Enable Unread Category Status Notification.*/
  120. ANS_DISABLE_NEW_INCOMING_ALERT_NOTIFICATION = 2, /**< Disable New Incoming Alert Notification.*/
  121. ANS_DISABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION = 3, /**< Disable Unread Category Status Notification.*/
  122. ANS_NOTIFY_NEW_INCOMING_ALERT_IMMEDIATELY = 4, /**< Notify New Incoming Alert immediately.*/
  123. ANS_NOTIFY_UNREAD_CATEGORY_STATUS_IMMEDIATELY = 5, /**< Notify Unread Category Status immediately.*/
  124. } ble_ans_command_id_t;
  125. /**@brief Alert Notification Event types that are passed from client to the application on an event. */
  126. typedef enum
  127. {
  128. BLE_ANS_C_EVT_DISCOVERY_COMPLETE, /**< A successful connection is established and the characteristics of the server were fetched. */
  129. BLE_ANS_C_EVT_DISCOVERY_FAILED, /**< It was not possible to discover service or characteristics of the connected peer. */
  130. BLE_ANS_C_EVT_DISCONN_COMPLETE, /**< The connection is taken down. */
  131. BLE_ANS_C_EVT_NOTIFICATION, /**< A valid notification was received from the server.*/
  132. BLE_ANS_C_EVT_READ_RESP, /**< A read response was received from the server.*/
  133. BLE_ANS_C_EVT_WRITE_RESP /**< A write response was received from the server.*/
  134. } ble_ans_c_evt_type_t;
  135. /**@brief Alert Notification Control Point structure. */
  136. typedef struct
  137. {
  138. ble_ans_command_id_t command; /**< The command to be written to the control point. See @ref ble_ans_command_id_t. */
  139. ble_ans_category_id_t category; /**< The category for the control point for which the command applies. See @ref ble_ans_category_id_t. */
  140. } ble_ans_control_point_t;
  141. /**@brief Alert Notification Setting structure containing the supported alerts in the service.
  142. *
  143. *@details
  144. * The structure contains bit fields that describe which alerts are supported:
  145. * - 0 = Unsupported
  146. * - 1 = Supported
  147. */
  148. typedef struct
  149. {
  150. uint8_t ans_simple_alert_support : 1; /**< Support for general text alert or non-text alert.*/
  151. uint8_t ans_email_support : 1; /**< Support for alert when an email message arrives.*/
  152. uint8_t ans_news_support : 1; /**< Support for news feeds such as RSS, Atom.*/
  153. uint8_t ans_notification_call_support : 1; /**< Support for incoming call.*/
  154. uint8_t ans_missed_call_support : 1; /**< Support for missed call.*/
  155. uint8_t ans_sms_mms_support : 1; /**< Support for SMS or MMS message arrival.*/
  156. uint8_t ans_voice_mail_support : 1; /**< Support for voice mail.*/
  157. uint8_t ans_schedule_support : 1; /**< Support for alert that occurs on calendar or planner.*/
  158. uint8_t ans_high_prioritized_alert_support : 1; /**< Support for alert that should be handled as high priority.*/
  159. uint8_t ans_instant_message_support : 1; /**< Support for alert for incoming instant messages.*/
  160. uint8_t reserved : 6; /**< Reserved for future use. */
  161. } ble_ans_alert_settings_t;
  162. /**@brief Alert Notification structure
  163. */
  164. typedef struct
  165. {
  166. uint8_t alert_category; /**< Alert category to which this alert belongs.*/
  167. uint8_t alert_category_count; /**< Number of alerts in the category. */
  168. uint32_t alert_msg_length; /**< Length of the optional text message sent by the server. */
  169. uint8_t * p_alert_msg_buf; /**< Pointer to the buffer that contains the optional text message. */
  170. } ble_ans_alert_notification_t;
  171. /**@brief Structure for holding information on the Alert Notification Service, if found on the server. */
  172. typedef struct
  173. {
  174. ble_gattc_service_t service; /**< The GATT service that holds the discovered Alert Notification Service. */
  175. ble_gattc_char_t alert_notif_ctrl_point; /**< Characteristic for the Alert Notification Control Point. See @ref BLE_UUID_ALERT_NOTIFICATION_CONTROL_POINT_CHAR. */
  176. ble_gattc_char_t suported_new_alert_cat; /**< Characteristic for the Supported New Alert category. See @ref BLE_UUID_SUPPORTED_NEW_ALERT_CATEGORY_CHAR. */
  177. ble_gattc_char_t suported_unread_alert_cat; /**< Characteristic for the Unread Alert category. See @ref BLE_UUID_SUPPORTED_UNREAD_ALERT_CATEGORY_CHAR. */
  178. ble_gattc_char_t new_alert; /**< Characteristic for the New Alert Notification. See @ref BLE_UUID_NEW_ALERT_CHAR. */
  179. ble_gattc_desc_t new_alert_cccd; /**< Characteristic Descriptor for the New Alert category. Enables or disables GATT notifications. */
  180. ble_gattc_char_t unread_alert_status; /**< Characteristic for the Unread Alert Notification. See @ref BLE_UUID_UNREAD_ALERT_CHAR. */
  181. ble_gattc_desc_t unread_alert_cccd; /**< Characteristic Descriptor for the Unread Alert category. Enables or disables GATT notifications */
  182. } ble_ans_c_service_t;
  183. /**@brief Alert Notification Event structure
  184. *
  185. * @details Structure for holding information about the event that should be handled, as well as
  186. * additional information.
  187. */
  188. typedef struct
  189. {
  190. ble_ans_c_evt_type_t evt_type; /**< Type of event. */
  191. uint16_t conn_handle; /**< Connection handle on which the ANS service was discovered on the peer device. This is filled if the evt_type is @ref BLE_ANS_C_EVT_DISCOVERY_COMPLETE.*/
  192. ble_uuid_t uuid; /**< UUID of the event in case of an alert or notification. */
  193. union
  194. {
  195. ble_ans_alert_settings_t settings; /**< Setting returned from server on read request. */
  196. ble_ans_alert_notification_t alert; /**< Alert Notification data sent by the server. */
  197. uint32_t error_code; /**< Additional status or error code, if the event is caused by a stack error or GATT status, for example during service discovery. */
  198. ble_ans_c_service_t service; /**< Information on the discovered Alert Notification Service. This is filled if the evt_type is @ref BLE_ANS_C_EVT_DISCOVERY_COMPLETE.*/
  199. } data;
  200. } ble_ans_c_evt_t;
  201. /**@brief Alert Notification event handler type. */
  202. typedef void (*ble_ans_c_evt_handler_t) (ble_ans_c_evt_t * p_evt);
  203. /**@brief Alert Notification structure. Contains various status information for the client. */
  204. struct ble_ans_c_s
  205. {
  206. ble_ans_c_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Alert Notification Client Application. */
  207. ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
  208. uint16_t conn_handle; /**< Handle of the current connection (as provided by the BLE stack; if not in a connection, the handle is BLE_CONN_HANDLE_INVALID). */
  209. uint8_t central_handle; /**< Handle for the currently connected central, if peer is bonded. */
  210. uint8_t service_handle; /**< Handle for the service in the database to be used for this instance. */
  211. uint32_t message_buffer_size; /**< Size of the message buffer to hold the additional text messages received on notifications. */
  212. uint8_t * p_message_buffer; /**< Pointer to the buffer to be used for additional text message handling. */
  213. ble_ans_c_service_t service; /**< Struct to store different handles and UUIDs related to the service. */
  214. nrf_ble_gq_t * p_gatt_queue; /**< Pointer to the BLE GATT Queue instance. */
  215. };
  216. /**@brief Alert Notification init structure. Contains all options and data needed for
  217. * the initialization of the client.*/
  218. typedef struct
  219. {
  220. ble_ans_c_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Battery Service. */
  221. ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
  222. uint32_t message_buffer_size; /**< Size of the buffer to handle messages. */
  223. uint8_t * p_message_buffer; /**< Pointer to the buffer for passing messages. */
  224. nrf_ble_gq_t * p_gatt_queue; /**< Pointer to the BLE GATT Queue instance. */
  225. } ble_ans_c_init_t;
  226. /**@brief Function for handling events from the Database Discovery module.
  227. *
  228. * @details Call this function when you get a callback event from the Database Discovery module.
  229. * This function handles an event from the Database Discovery module and determines
  230. * whether it relates to the discovery of Heart Rate Service at the peer. If it does, this function
  231. * calls the application's event handler to indicate that the Heart Rate Service was
  232. * discovered at the peer. The function also populates the event with service-related
  233. * information before providing it to the application.
  234. *
  235. * @param[in] p_ans Pointer to the Alert Notification client structure instance that will handle
  236. * the discovery.
  237. * @param[in] p_evt Pointer to the event received from the Database Discovery module.
  238. */
  239. void ble_ans_c_on_db_disc_evt(ble_ans_c_t * p_ans, ble_db_discovery_evt_t const * p_evt);
  240. /**@brief Function for handling the application's BLE stack events.
  241. *
  242. * @details Handles all events from the BLE stack of interest to the Alert Notification Client.
  243. *
  244. * @param[in] p_ble_evt Event received from the BLE stack.
  245. * @param[in] p_context Alert Notification Client structure.
  246. */
  247. void ble_ans_c_on_ble_evt(ble_evt_t const * p_ble_evt, void * p_context);
  248. /**@brief Function for initializing the Alert Notification Client.
  249. *
  250. * @param[out] p_ans Alert Notification Client structure. This structure must be
  251. * supplied by the application. It is initialized by this function,
  252. * and is later used to identify this particular client instance.
  253. * @param[in] p_ans_init Information needed to initialize the client.
  254. *
  255. * @return NRF_SUCCESS on successful initialization of client. Otherwise, it returns an error code.
  256. */
  257. uint32_t ble_ans_c_init(ble_ans_c_t * p_ans, ble_ans_c_init_t const * p_ans_init);
  258. /**@brief Function for writing the to CCCD to enable new alert notifications from the Alert Notification Service.
  259. *
  260. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  261. * the application. It identifies the particular client instance to use.
  262. *
  263. * @return NRF_SUCCESS on successful writing of the CCCD. Otherwise, it returns an error code.
  264. */
  265. uint32_t ble_ans_c_enable_notif_new_alert(ble_ans_c_t const * p_ans);
  266. /**@brief Function for writing to the CCCD to enable unread alert notifications from the Alert Notification Service.
  267. *
  268. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  269. * the application. It identifies the particular client instance to use.
  270. *
  271. * @return NRF_SUCCESS on successful writing of the CCCD. Otherwise, it returns an error code.
  272. */
  273. uint32_t ble_ans_c_enable_notif_unread_alert(ble_ans_c_t const * p_ans);
  274. /**@brief Function for writing to the CCCD to disable new alert notifications from the Alert Notification Service.
  275. *
  276. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  277. * the application. It identifies the particular client instance to use.
  278. *
  279. * @return NRF_SUCCESS on successful writing of the CCCD. Otherwise, it returns an error code.
  280. */
  281. uint32_t ble_ans_c_disable_notif_new_alert(ble_ans_c_t const * p_ans);
  282. /**@brief Function for writing to the CCCD to disable unread alert notifications from the Alert Notification Service.
  283. *
  284. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  285. * the application. It identifies the particular client instance to use.
  286. *
  287. * @return NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
  288. */
  289. uint32_t ble_ans_c_disable_notif_unread_alert(ble_ans_c_t const * p_ans);
  290. /**@brief Function for writing to the Alert Notification Control Point to specify alert notification behavior in the
  291. * Alert Notification Service on the Central.
  292. *
  293. * @param[in] p_ans Alert Notification structure. This structure must be
  294. * supplied by the application. It identifies the particular client
  295. * instance to use.
  296. * @param[in] p_control_point Alert Notification Control Point structure. This structure
  297. * specifies the values to write to the Alert Notification Control
  298. * Point (UUID 0x2A44).
  299. *
  300. * @return NRF_SUCCESS on successful writing of the Control Point. Otherwise,
  301. * this API propagates the error code returned by function
  302. * @ref nrf_ble_gq_item_add.
  303. */
  304. uint32_t ble_ans_c_control_point_write(ble_ans_c_t const * p_ans,
  305. ble_ans_control_point_t const * p_control_point);
  306. /**@brief Function for reading the Supported New Alert characteristic value of the service.
  307. * The value describes the alerts supported in the central.
  308. *
  309. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  310. * the application. It identifies the particular client instance to use.
  311. *
  312. * @return NRF_SUCCESS on successful transmission of the read request. Otherwise,
  313. * this API propagates the error code returned by function
  314. * @ref nrf_ble_gq_item_add.
  315. */
  316. uint32_t ble_ans_c_new_alert_read(ble_ans_c_t const * p_ans);
  317. /**@brief Function for reading the Supported Unread Alert characteristic value of the service.
  318. * The value describes the alerts supported in the central.
  319. *
  320. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  321. * the application. It identifies the particular client instance to use.
  322. *
  323. * @return NRF_SUCCESS on successful transmission of the read request. Otherwise,
  324. * this API propagates the error code returned by function
  325. * @ref nrf_ble_gq_item_add.
  326. */
  327. uint32_t ble_ans_c_unread_alert_read(ble_ans_c_t const * p_ans);
  328. /**@brief Function for requesting the peer to notify the New Alert characteristics immediately.
  329. *
  330. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  331. * the application. It identifies the particular client instance to use.
  332. * @param[in] category The category ID for which the peer should notify the client.
  333. *
  334. * @return NRF_SUCCESS on successful transmission of the read request. Otherwise, it returns an error code.
  335. */
  336. uint32_t ble_ans_c_new_alert_notify(ble_ans_c_t const * p_ans, ble_ans_category_id_t category);
  337. /**@brief Function for requesting the peer to notify the Unread Alert characteristics immediately.
  338. *
  339. * @param[in] p_ans Alert Notification structure. This structure must be supplied by
  340. * the application. It identifies the particular client instance to use.
  341. * @param[in] category The category ID for which the peer should notify the client.
  342. *
  343. * @return NRF_SUCCESS on successful transmission of the read request. Otherwise, it returns an error code.
  344. */
  345. uint32_t ble_ans_c_unread_alert_notify(ble_ans_c_t const * p_ans, ble_ans_category_id_t category);
  346. /**@brief Function for assigning handles to an instance of ans_c.
  347. *
  348. * @details Call this function when a link has been established with a peer to
  349. * associate the link to an instance of the module. This makes it possible
  350. * to handle several links and associate each link to a particular
  351. * instance of the ans_c module. The connection handle and attribute handles
  352. * are provided from the discovery event @ref BLE_ANS_C_EVT_DISCOVERY_COMPLETE.
  353. *
  354. * @param[in] p_ans Pointer to the Alert Notification client structure instance to
  355. * associate with the handles.
  356. * @param[in] conn_handle Connection handle to associated with the given Alert Notification Client
  357. * Instance.
  358. * @param[in] p_peer_handles Attribute handles on the ANS server that you want this ANS client to
  359. * interact with.
  360. *
  361. */
  362. uint32_t ble_ans_c_handles_assign(ble_ans_c_t * p_ans,
  363. uint16_t const conn_handle,
  364. ble_ans_c_service_t const * p_peer_handles);
  365. #ifdef __cplusplus
  366. }
  367. #endif
  368. #endif // BLE_ANS_C_H__
  369. /** @} */