123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418 |
- /**
- * Copyright (c) 2012 - 2020, Nordic Semiconductor ASA
- *
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without modification,
- * are permitted provided that the following conditions are met:
- *
- * 1. Redistributions of source code must retain the above copyright notice, this
- * list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form, except as embedded into a Nordic
- * Semiconductor ASA integrated circuit in a product or a software update for
- * such product, must reproduce the above copyright notice, this list of
- * conditions and the following disclaimer in the documentation and/or other
- * materials provided with the distribution.
- *
- * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
- * contributors may be used to endorse or promote products derived from this
- * software without specific prior written permission.
- *
- * 4. This software, with or without modification, must only be used with a
- * Nordic Semiconductor ASA integrated circuit.
- *
- * 5. Any software provided in binary form under this license must not be reverse
- * engineered, decompiled, modified and/or disassembled.
- *
- * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
- * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
- * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
- * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- */
- /** @file
- *
- * @defgroup ble_ans_c Alert Notification Service Client
- * @{
- * @ingroup ble_sdk_srv
- * @brief Alert Notification module.
- *
- * @details This module implements the Alert Notification Client according to the
- * Alert Notification Profile.
- *
- * @note The application must register this module as the BLE event observer by using the
- * NRF_SDH_BLE_OBSERVER macro. Example:
- * @code
- * ble_ans_c_t instance;
- * NRF_SDH_BLE_OBSERVER(anything, BLE_ANS_C_BLE_OBSERVER_PRIO,
- * ble_ans_c_on_ble_evt, &instance);
- * @endcode
- *
- * @note Attention!
- * To maintain compliance with Nordic Semiconductor ASA Bluetooth profile
- * qualification listings, this section of source code must not be modified.
- */
- #ifndef BLE_ANS_C_H__
- #define BLE_ANS_C_H__
- #include "ble.h"
- #include "ble_gatts.h"
- #include "ble_types.h"
- #include "sdk_common.h"
- #include "ble_srv_common.h"
- #include "ble_db_discovery.h"
- #include "nrf_ble_gq.h"
- #include "nrf_sdh_ble.h"
- #ifdef __cplusplus
- extern "C" {
- #endif
- /**@brief Macro for defining a ble_ans_c instance.
- *
- * @param _name Name of the instance.
- * @hideinitializer
- */
- #define BLE_ANS_C_DEF(_name) \
- static ble_ans_c_t _name; \
- NRF_SDH_BLE_OBSERVER(_name ## _obs, \
- BLE_ANS_C_BLE_OBSERVER_PRIO, \
- ble_ans_c_on_ble_evt, &_name)
- /** @brief Macro for defining multiple ble_ans_c instances.
- *
- * @param _name Name of the array of instances.
- * @param _cnt Number of instances to define.
- * @hideinitializer
- */
- #define BLE_ANS_C_ARRAY_DEF(_name, _cnt) \
- static ble_ans_c_t _name[_cnt]; \
- NRF_SDH_BLE_OBSERVERS(_name ## _obs, \
- BLE_ANS_C_BLE_OBSERVER_PRIO, \
- ble_ans_c_on_ble_evt, &_name, _cnt)
- // Forward declaration of the ble_ans_c_t type.
- typedef struct ble_ans_c_s ble_ans_c_t;
- /** Alert types, as defined in the alert category ID. UUID: 0x2A43. */
- typedef enum
- {
- ANS_TYPE_SIMPLE_ALERT = 0, /**< General text alert or non-text alert.*/
- ANS_TYPE_EMAIL = 1, /**< Email message arrives.*/
- ANS_TYPE_NEWS = 2, /**< News feeds such as RSS, Atom.*/
- ANS_TYPE_NOTIFICATION_CALL = 3, /**< Incoming call.*/
- ANS_TYPE_MISSED_CALL = 4, /**< Missed call.*/
- ANS_TYPE_SMS_MMS = 5, /**< SMS or MMS message arrives.*/
- ANS_TYPE_VOICE_MAIL = 6, /**< Voice mail.*/
- ANS_TYPE_SCHEDULE = 7, /**< Alert that occurs on calendar, planner.*/
- ANS_TYPE_HIGH_PRIORITIZED_ALERT = 8, /**< Alert to be handled as high priority.*/
- ANS_TYPE_INSTANT_MESSAGE = 9, /**< Alert for incoming instant messages.*/
- ANS_TYPE_ALL_ALERTS = 0xFF /**< Identifies all alerts. */
- } ble_ans_category_id_t;
- /** Alert notification control point commands, as defined in the Alert Notification Specification.
- * UUID: 0x2A44.
- */
- typedef enum
- {
- ANS_ENABLE_NEW_INCOMING_ALERT_NOTIFICATION = 0, /**< Enable New Incoming Alert Notification.*/
- ANS_ENABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION = 1, /**< Enable Unread Category Status Notification.*/
- ANS_DISABLE_NEW_INCOMING_ALERT_NOTIFICATION = 2, /**< Disable New Incoming Alert Notification.*/
- ANS_DISABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION = 3, /**< Disable Unread Category Status Notification.*/
- ANS_NOTIFY_NEW_INCOMING_ALERT_IMMEDIATELY = 4, /**< Notify New Incoming Alert immediately.*/
- ANS_NOTIFY_UNREAD_CATEGORY_STATUS_IMMEDIATELY = 5, /**< Notify Unread Category Status immediately.*/
- } ble_ans_command_id_t;
- /**@brief Alert Notification Event types that are passed from client to the application on an event. */
- typedef enum
- {
- BLE_ANS_C_EVT_DISCOVERY_COMPLETE, /**< A successful connection is established and the characteristics of the server were fetched. */
- BLE_ANS_C_EVT_DISCOVERY_FAILED, /**< It was not possible to discover service or characteristics of the connected peer. */
- BLE_ANS_C_EVT_DISCONN_COMPLETE, /**< The connection is taken down. */
- BLE_ANS_C_EVT_NOTIFICATION, /**< A valid notification was received from the server.*/
- BLE_ANS_C_EVT_READ_RESP, /**< A read response was received from the server.*/
- BLE_ANS_C_EVT_WRITE_RESP /**< A write response was received from the server.*/
- } ble_ans_c_evt_type_t;
- /**@brief Alert Notification Control Point structure. */
- typedef struct
- {
- ble_ans_command_id_t command; /**< The command to be written to the control point. See @ref ble_ans_command_id_t. */
- ble_ans_category_id_t category; /**< The category for the control point for which the command applies. See @ref ble_ans_category_id_t. */
- } ble_ans_control_point_t;
- /**@brief Alert Notification Setting structure containing the supported alerts in the service.
- *
- *@details
- * The structure contains bit fields that describe which alerts are supported:
- * - 0 = Unsupported
- * - 1 = Supported
- */
- typedef struct
- {
- uint8_t ans_simple_alert_support : 1; /**< Support for general text alert or non-text alert.*/
- uint8_t ans_email_support : 1; /**< Support for alert when an email message arrives.*/
- uint8_t ans_news_support : 1; /**< Support for news feeds such as RSS, Atom.*/
- uint8_t ans_notification_call_support : 1; /**< Support for incoming call.*/
- uint8_t ans_missed_call_support : 1; /**< Support for missed call.*/
- uint8_t ans_sms_mms_support : 1; /**< Support for SMS or MMS message arrival.*/
- uint8_t ans_voice_mail_support : 1; /**< Support for voice mail.*/
- uint8_t ans_schedule_support : 1; /**< Support for alert that occurs on calendar or planner.*/
- uint8_t ans_high_prioritized_alert_support : 1; /**< Support for alert that should be handled as high priority.*/
- uint8_t ans_instant_message_support : 1; /**< Support for alert for incoming instant messages.*/
- uint8_t reserved : 6; /**< Reserved for future use. */
- } ble_ans_alert_settings_t;
- /**@brief Alert Notification structure
- */
- typedef struct
- {
- uint8_t alert_category; /**< Alert category to which this alert belongs.*/
- uint8_t alert_category_count; /**< Number of alerts in the category. */
- uint32_t alert_msg_length; /**< Length of the optional text message sent by the server. */
- uint8_t * p_alert_msg_buf; /**< Pointer to the buffer that contains the optional text message. */
- } ble_ans_alert_notification_t;
- /**@brief Structure for holding information on the Alert Notification Service, if found on the server. */
- typedef struct
- {
- ble_gattc_service_t service; /**< The GATT service that holds the discovered Alert Notification Service. */
- ble_gattc_char_t alert_notif_ctrl_point; /**< Characteristic for the Alert Notification Control Point. See @ref BLE_UUID_ALERT_NOTIFICATION_CONTROL_POINT_CHAR. */
- ble_gattc_char_t suported_new_alert_cat; /**< Characteristic for the Supported New Alert category. See @ref BLE_UUID_SUPPORTED_NEW_ALERT_CATEGORY_CHAR. */
- ble_gattc_char_t suported_unread_alert_cat; /**< Characteristic for the Unread Alert category. See @ref BLE_UUID_SUPPORTED_UNREAD_ALERT_CATEGORY_CHAR. */
- ble_gattc_char_t new_alert; /**< Characteristic for the New Alert Notification. See @ref BLE_UUID_NEW_ALERT_CHAR. */
- ble_gattc_desc_t new_alert_cccd; /**< Characteristic Descriptor for the New Alert category. Enables or disables GATT notifications. */
- ble_gattc_char_t unread_alert_status; /**< Characteristic for the Unread Alert Notification. See @ref BLE_UUID_UNREAD_ALERT_CHAR. */
- ble_gattc_desc_t unread_alert_cccd; /**< Characteristic Descriptor for the Unread Alert category. Enables or disables GATT notifications */
- } ble_ans_c_service_t;
- /**@brief Alert Notification Event structure
- *
- * @details Structure for holding information about the event that should be handled, as well as
- * additional information.
- */
- typedef struct
- {
- ble_ans_c_evt_type_t evt_type; /**< Type of event. */
- 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.*/
- ble_uuid_t uuid; /**< UUID of the event in case of an alert or notification. */
- union
- {
- ble_ans_alert_settings_t settings; /**< Setting returned from server on read request. */
- ble_ans_alert_notification_t alert; /**< Alert Notification data sent by the server. */
- 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. */
- 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.*/
- } data;
- } ble_ans_c_evt_t;
- /**@brief Alert Notification event handler type. */
- typedef void (*ble_ans_c_evt_handler_t) (ble_ans_c_evt_t * p_evt);
- /**@brief Alert Notification structure. Contains various status information for the client. */
- struct ble_ans_c_s
- {
- ble_ans_c_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Alert Notification Client Application. */
- ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
- 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). */
- uint8_t central_handle; /**< Handle for the currently connected central, if peer is bonded. */
- uint8_t service_handle; /**< Handle for the service in the database to be used for this instance. */
- uint32_t message_buffer_size; /**< Size of the message buffer to hold the additional text messages received on notifications. */
- uint8_t * p_message_buffer; /**< Pointer to the buffer to be used for additional text message handling. */
- ble_ans_c_service_t service; /**< Struct to store different handles and UUIDs related to the service. */
- nrf_ble_gq_t * p_gatt_queue; /**< Pointer to the BLE GATT Queue instance. */
- };
- /**@brief Alert Notification init structure. Contains all options and data needed for
- * the initialization of the client.*/
- typedef struct
- {
- ble_ans_c_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Battery Service. */
- ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
- uint32_t message_buffer_size; /**< Size of the buffer to handle messages. */
- uint8_t * p_message_buffer; /**< Pointer to the buffer for passing messages. */
- nrf_ble_gq_t * p_gatt_queue; /**< Pointer to the BLE GATT Queue instance. */
- } ble_ans_c_init_t;
- /**@brief Function for handling events from the Database Discovery module.
- *
- * @details Call this function when you get a callback event from the Database Discovery module.
- * This function handles an event from the Database Discovery module and determines
- * whether it relates to the discovery of Heart Rate Service at the peer. If it does, this function
- * calls the application's event handler to indicate that the Heart Rate Service was
- * discovered at the peer. The function also populates the event with service-related
- * information before providing it to the application.
- *
- * @param[in] p_ans Pointer to the Alert Notification client structure instance that will handle
- * the discovery.
- * @param[in] p_evt Pointer to the event received from the Database Discovery module.
- */
- void ble_ans_c_on_db_disc_evt(ble_ans_c_t * p_ans, ble_db_discovery_evt_t const * p_evt);
- /**@brief Function for handling the application's BLE stack events.
- *
- * @details Handles all events from the BLE stack of interest to the Alert Notification Client.
- *
- * @param[in] p_ble_evt Event received from the BLE stack.
- * @param[in] p_context Alert Notification Client structure.
- */
- void ble_ans_c_on_ble_evt(ble_evt_t const * p_ble_evt, void * p_context);
- /**@brief Function for initializing the Alert Notification Client.
- *
- * @param[out] p_ans Alert Notification Client structure. This structure must be
- * supplied by the application. It is initialized by this function,
- * and is later used to identify this particular client instance.
- * @param[in] p_ans_init Information needed to initialize the client.
- *
- * @return NRF_SUCCESS on successful initialization of client. Otherwise, it returns an error code.
- */
- uint32_t ble_ans_c_init(ble_ans_c_t * p_ans, ble_ans_c_init_t const * p_ans_init);
- /**@brief Function for writing the to CCCD to enable new alert notifications from the Alert Notification Service.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- *
- * @return NRF_SUCCESS on successful writing of the CCCD. Otherwise, it returns an error code.
- */
- uint32_t ble_ans_c_enable_notif_new_alert(ble_ans_c_t const * p_ans);
- /**@brief Function for writing to the CCCD to enable unread alert notifications from the Alert Notification Service.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- *
- * @return NRF_SUCCESS on successful writing of the CCCD. Otherwise, it returns an error code.
- */
- uint32_t ble_ans_c_enable_notif_unread_alert(ble_ans_c_t const * p_ans);
- /**@brief Function for writing to the CCCD to disable new alert notifications from the Alert Notification Service.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- *
- * @return NRF_SUCCESS on successful writing of the CCCD. Otherwise, it returns an error code.
- */
- uint32_t ble_ans_c_disable_notif_new_alert(ble_ans_c_t const * p_ans);
- /**@brief Function for writing to the CCCD to disable unread alert notifications from the Alert Notification Service.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- *
- * @return NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
- */
- uint32_t ble_ans_c_disable_notif_unread_alert(ble_ans_c_t const * p_ans);
- /**@brief Function for writing to the Alert Notification Control Point to specify alert notification behavior in the
- * Alert Notification Service on the Central.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be
- * supplied by the application. It identifies the particular client
- * instance to use.
- * @param[in] p_control_point Alert Notification Control Point structure. This structure
- * specifies the values to write to the Alert Notification Control
- * Point (UUID 0x2A44).
- *
- * @return NRF_SUCCESS on successful writing of the Control Point. Otherwise,
- * this API propagates the error code returned by function
- * @ref nrf_ble_gq_item_add.
- */
- uint32_t ble_ans_c_control_point_write(ble_ans_c_t const * p_ans,
- ble_ans_control_point_t const * p_control_point);
- /**@brief Function for reading the Supported New Alert characteristic value of the service.
- * The value describes the alerts supported in the central.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- *
- * @return NRF_SUCCESS on successful transmission of the read request. Otherwise,
- * this API propagates the error code returned by function
- * @ref nrf_ble_gq_item_add.
- */
- uint32_t ble_ans_c_new_alert_read(ble_ans_c_t const * p_ans);
- /**@brief Function for reading the Supported Unread Alert characteristic value of the service.
- * The value describes the alerts supported in the central.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- *
- * @return NRF_SUCCESS on successful transmission of the read request. Otherwise,
- * this API propagates the error code returned by function
- * @ref nrf_ble_gq_item_add.
- */
- uint32_t ble_ans_c_unread_alert_read(ble_ans_c_t const * p_ans);
- /**@brief Function for requesting the peer to notify the New Alert characteristics immediately.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- * @param[in] category The category ID for which the peer should notify the client.
- *
- * @return NRF_SUCCESS on successful transmission of the read request. Otherwise, it returns an error code.
- */
- uint32_t ble_ans_c_new_alert_notify(ble_ans_c_t const * p_ans, ble_ans_category_id_t category);
- /**@brief Function for requesting the peer to notify the Unread Alert characteristics immediately.
- *
- * @param[in] p_ans Alert Notification structure. This structure must be supplied by
- * the application. It identifies the particular client instance to use.
- * @param[in] category The category ID for which the peer should notify the client.
- *
- * @return NRF_SUCCESS on successful transmission of the read request. Otherwise, it returns an error code.
- */
- uint32_t ble_ans_c_unread_alert_notify(ble_ans_c_t const * p_ans, ble_ans_category_id_t category);
- /**@brief Function for assigning handles to an instance of ans_c.
- *
- * @details Call this function when a link has been established with a peer to
- * associate the link to an instance of the module. This makes it possible
- * to handle several links and associate each link to a particular
- * instance of the ans_c module. The connection handle and attribute handles
- * are provided from the discovery event @ref BLE_ANS_C_EVT_DISCOVERY_COMPLETE.
- *
- * @param[in] p_ans Pointer to the Alert Notification client structure instance to
- * associate with the handles.
- * @param[in] conn_handle Connection handle to associated with the given Alert Notification Client
- * Instance.
- * @param[in] p_peer_handles Attribute handles on the ANS server that you want this ANS client to
- * interact with.
- *
- */
- uint32_t ble_ans_c_handles_assign(ble_ans_c_t * p_ans,
- uint16_t const conn_handle,
- ble_ans_c_service_t const * p_peer_handles);
- #ifdef __cplusplus
- }
- #endif
- #endif // BLE_ANS_C_H__
- /** @} */
|