ble_ans_c.h

00001 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is property of Nordic Semiconductor ASA.
00004  * Terms and conditions of usage are described in detail in NORDIC
00005  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
00006  *
00007  * Licensees are granted free, non-transferable use of the information. NO
00008  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
00009  * the file.
00010  */
00011 
00012 /** @file
00013  *
00014  * @defgroup ble_sdk_srv_ans_c Alert Notification Service Client
00015  * @{
00016  * @ingroup ble_sdk_srv
00017  * @brief Alert Notification module.
00018  *
00019  * @details This module implements the Alert Notification Client according to the
00020  *          Alert Notification Profile.
00021  *
00022  * @note The application must propagate BLE stack events to the Alert Notification Client module
00023  *       by calling ble_ans_c_on_ble_evt() from the from the @ref ble_stack_handler callback.
00024  *
00025  * @note Attention! 
00026  *  To maintain compliance with Nordic Semiconductor ASA Bluetooth profile 
00027  *  qualification listings, this section of source code must not be modified.
00028  */
00029 #ifndef BLE_ANS_C_H__
00030 #define BLE_ANS_C_H__
00031 
00032 #include "ble.h"
00033 #include "ble_gatts.h"
00034 #include "ble_types.h"
00035 #include "ble_srv_common.h "
00036 #include "device_manager.h "
00037 
00038 #define ANS_NB_OF_CHARACTERISTICS                   5                                     /**< Number of characteristics as defined by Alert Notification Service specification. */
00039 #define ANS_NB_OF_SERVICES                          1                                     /**< Number of services supported in one central. */
00040 #define INVALID_SERVICE_HANDLE_BASE                 0xF0                                  /**< Base for indicating invalid service handle. */
00041 #define INVALID_SERVICE_HANDLE                      (INVALID_SERVICE_HANDLE_BASE + 0x0F)  /**< Indication that the current service handle is invalid. */
00042 #define INVALID_SERVICE_HANDLE_DISC                 (INVALID_SERVICE_HANDLE_BASE + 0x0E)  /**< Indication that the current service handle is invalid but the service has been discovered. */
00043 #define BLE_ANS_INVALID_HANDLE                      0xFF                                  /**< Indication that the current service handle is invalid. */
00044 
00045 // Forward declaration of the ble_ans_c_t type.
00046 typedef struct ble_ans_c_s ble_ans_c_t;
00047 
00048 /** Alerts types as defined in the alert category id; UUID: 0x2A43. */
00049 typedef enum
00050 {
00051     ANS_TYPE_SIMPLE_ALERT                           = 0,                                  /**< General text alert or non-text alert.*/
00052     ANS_TYPE_EMAIL                                  = 1,                                  /**< Alert when email messages arrives.*/
00053     ANS_TYPE_NEWS                                   = 2,                                  /**< News feeds such as RSS, Atom.*/
00054     ANS_TYPE_NOTIFICATION_CALL                      = 3,                                  /**< Incoming call.*/
00055     ANS_TYPE_MISSED_CALL                            = 4,                                  /**< Missed call.*/
00056     ANS_TYPE_SMS_MMS                                = 5,                                  /**< SMS/MMS message arrives.*/
00057     ANS_TYPE_VOICE_MAIL                             = 6,                                  /**< Voice mail.*/
00058     ANS_TYPE_SCHEDULE                               = 7,                                  /**< Alert occurred on calendar, planner.*/
00059     ANS_TYPE_HIGH_PRIORITIZED_ALERT                 = 8,                                  /**< Alert that should be handled as high priority.*/
00060     ANS_TYPE_INSTANT_MESSAGE                        = 9,                                  /**< Alert for incoming instant messages.*/
00061     ANS_TYPE_ALL_ALERTS                             = 0xFF                                /**< Identifies All Alerts. */
00062 } ble_ans_category_id_t;
00063 
00064 /** Alerts notification control point commands as defined in the Alert Notification Specification;
00065  * UUID: 0x2A44.
00066  */
00067 typedef enum
00068 {
00069     ANS_ENABLE_NEW_INCOMING_ALERT_NOTIFICATION      = 0,                                  /**< Enable New Incoming Alert Notification.*/
00070     ANS_ENABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION  = 1,                                  /**< Enable Unread Category Status Notification.*/
00071     ANS_DISABLE_NEW_INCOMING_ALERT_NOTIFICATION     = 2,                                  /**< Disable New Incoming Alert Notification.*/
00072     ANS_DISABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION = 3,                                  /**< Disable Unread Category Status Notification.*/
00073     ANS_NOTIFY_NEW_INCOMING_ALERT_IMMEDIATELY       = 4,                                  /**< Notify New Incoming Alert immediately.*/
00074     ANS_NOTIFY_UNREAD_CATEGORY_STATUS_IMMEDIATELY   = 5,                                  /**< Notify Unread Category Status immediately.*/
00075 } ble_ans_command_id_t;
00076 
00077 /**@brief Alert Notification Event types that are passed from client to application on an event. */
00078 typedef enum
00079 {
00080     BLE_ANS_C_EVT_DISCOVER_COMPLETE,                                                      /**< A successful connection has been established and the characteristics of the server has been fetched. */
00081     BLE_ANS_C_EVT_DISCOVER_FAILED,                                                        /**< It was not possible to discover service or characteristics of the connected peer. */
00082     BLE_ANS_C_EVT_RECONNECT,                                                              /**< A re-connection to a known and previously discovered central has occurred. */
00083     BLE_ANS_C_EVT_DISCONN_COMPLETE,                                                       /**< The connection has been taken down. */
00084     BLE_ANS_C_EVT_NOTIFICATION,                                                           /**< A valid Alert Notification has been received from the server.*/
00085     BLE_ANS_C_EVT_READ_RESP,                                                              /**< A read response has been received from the server.*/
00086     BLE_ANS_C_EVT_WRITE_RESP                                                              /**< A write response has been received from the server.*/
00087 } ble_ans_c_evt_type_t;
00088 
00089 /**@brief Alert Notification Control Point structure. */
00090 typedef struct
00091 {
00092     ble_ans_command_id_t                command;                                          /**< The command to be written to the control point, see @ref ble_ans_command_id_t. */
00093     ble_ans_category_id_t               category;                                         /**< The category for the control point for which the command applies, see @ref ble_ans_category_id_t. */
00094 } ble_ans_control_point_t;
00095 
00096 /**@brief Alert Notification Setting structure containing the supported alerts in the service.
00097   *
00098   *@details
00099   * The structure contains bit fields describing which alerts that are supported:
00100   * 0 = Unsupported
00101   * 1 = Supported
00102   */
00103 typedef struct
00104 {
00105     uint8_t                             ans_simple_alert_support           : 1;           /**< Support for General text alert or non-text alert.*/
00106     uint8_t                             ans_email_support                  : 1;           /**< Support for Alert when email messages arrives.*/
00107     uint8_t                             ans_news_support                   : 1;           /**< Support for News feeds such as RSS, Atom.*/
00108     uint8_t                             ans_notification_call_support      : 1;           /**< Support for Incoming call.*/
00109     uint8_t                             ans_missed_call_support            : 1;           /**< Support for Missed call.*/
00110     uint8_t                             ans_sms_mms_support                : 1;           /**< Support for SMS/MMS message arrives.*/
00111     uint8_t                             ans_voice_mail_support             : 1;           /**< Support for Voice mail.*/
00112     uint8_t                             ans_schedule_support               : 1;           /**< Support for Alert occurred on calendar, planner.*/
00113     uint8_t                             ans_high_prioritized_alert_support : 1;           /**< Support for Alert that should be handled as high priority.*/
00114     uint8_t                             ans_instant_message_support        : 1;           /**< Support for Alert for incoming instant messages.*/
00115     uint8_t                             reserved                           : 6;           /**< Reserved for future use. */
00116 } ble_ans_alert_settings_t;
00117 
00118 /**@brief Alert Notification structure
00119  */
00120 typedef struct
00121 {
00122     uint8_t                             alert_category;                                   /**< Alert category to which this alert belongs.*/
00123     uint8_t                             alert_category_count;                             /**< Number of alerts in the category. */
00124     uint32_t                            alert_msg_length;                                 /**< Length of optional text message send by the server. */
00125     uint8_t *                           p_alert_msg_buf;                                  /**< Pointer to buffer containing the optional text message. */
00126 } ble_ans_alert_notification_t;
00127 
00128 /**@brief Alert Notification Event structure
00129  *
00130  * @details The structure contains the event that should be handled, as well as
00131  *          additional information.
00132  */
00133 typedef struct
00134 {
00135     ble_ans_c_evt_type_t                evt_type;                                         /**< Type of event. */
00136     ble_uuid_t                          uuid;                                             /**< UUID of the event in case of an alert or notification. */
00137     union
00138     {
00139         ble_ans_alert_settings_t        settings;                                         /**< Setting returned from server on read request. */
00140         ble_ans_alert_notification_t    alert;                                            /**< Alert Notification data sent by the server. */
00141         uint32_t                        error_code;                                       /**< Additional status/error code if the event was caused by a stack error or gatt status, e.g. during service discovery. */
00142     } data;
00143 } ble_ans_c_evt_t;
00144 
00145 /**@brief Alert Notification event handler type. */
00146 typedef void (*ble_ans_c_evt_handler_t) (ble_ans_c_evt_t * p_evt);
00147 
00148 /**@brief Alert Notification structure. This contains various status information for the client. */
00149 typedef struct ble_ans_c_s
00150 {
00151     ble_ans_c_evt_handler_t             evt_handler;                                      /**< Event handler to be called for handling events in the Alert Notification Client Application. */
00152     ble_srv_error_handler_t             error_handler;                                    /**< Function to be called in case of an error. */
00153     uint16_t                            conn_handle;                                      /**< Handle of the current connection (as provided by the BLE stack, is BLE_CONN_HANDLE_INVALID if not in a connection). */
00154     uint8_t                             central_handle;                                   /**< Handle for the currently connected central if peer is bonded. */
00155     uint8_t                             service_handle;                                   /**< Handle to the service in the database to use for this instance. */
00156     uint32_t                            message_buffer_size;                              /**< Size of message buffer to hold the additional text messages received on notifications. */
00157     uint8_t *                           p_message_buffer;                                 /**< Pointer to the buffer to be used for additional text message handling. */
00158 } ble_ans_c_t;
00159 
00160 /**@brief Alert Notification init structure. This contains all options and data needed for
00161  *        initialization of the client.*/
00162 typedef struct
00163 {
00164     ble_ans_c_evt_handler_t             evt_handler;                                      /**< Event handler to be called for handling events in the Battery Service. */
00165     ble_srv_error_handler_t             error_handler;                                    /**< Function to be called in case of an error. */
00166     uint32_t                            message_buffer_size;                              /**< Size of buffer to handle messages. */
00167     uint8_t *                           p_message_buffer;                                 /**< Pointer to buffer for passing messages. */
00168 } ble_ans_c_init_t;
00169 
00170 
00171 /**@brief Function for handling the Application's BLE Stack events.
00172  *
00173  * @details Handles all events from the BLE stack of interest to the Alert Notification Client.
00174  *
00175  * @param[in]   p_ans      Alert Notification Client structure.
00176  * @param[in]   p_ble_evt  Event received from the BLE stack.
00177  */
00178 void ble_ans_c_on_ble_evt(ble_ans_c_t * p_ans, const ble_evt_t * p_ble_evt);
00179 
00180 
00181 /**@brief Function for handling the Alert Notification Client - Device Manager Event.
00182  *
00183  * @details Handles all events from the Bond Manager of interest to the Alert Notification Client.
00184  *          The Alert Notification Client will use the events of re-connection to existing central
00185  *          and creation of new bonds for handling of service discovery and writing of the Alert
00186  *          Notification Control Point for re-send of New Alert and Unread Alert notifications.
00187  *
00188  * @param[in]   p_ans            Alert Notification Client structure.
00189  * @param[in]   p_bond_mgmr_evt  Event received from the Bond Manager.
00190  */
00191 void ble_ans_c_on_device_manager_evt(ble_ans_c_t       * p_ans,
00192                                      dm_handle_t const * p_handle,
00193                                      dm_event_t const  * p_dm_evt);
00194 
00195 
00196 /**@brief Function for initializing the Alert Notification Client.
00197  *
00198  * @param[out]  p_ans       Alert Notification Client structure. This structure will have to be
00199  *                          supplied by the application. It will be initialized by this function,
00200  *                          and will later be used to identify this particular client instance.
00201  * @param[in]   p_ans_init  Information needed to initialize the client.
00202  *
00203  * @return      NRF_SUCCESS on successful initialization of client, otherwise an error code.
00204  */
00205 uint32_t ble_ans_c_init(ble_ans_c_t * p_ans, const ble_ans_c_init_t * p_ans_init);
00206 
00207 
00208 /**@brief Function for writing the to CCCD to enable new alert notifications from the Alert Notification Service.
00209  *
00210  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00211  *                         the application. It identifies the particular client instance to use.
00212  *
00213  * @return     NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
00214  */
00215 uint32_t ble_ans_c_enable_notif_new_alert(const ble_ans_c_t * p_ans);
00216 
00217 
00218 /**@brief Function for writing to the CCCD to enable unread alert notifications from the Alert Notification Service.
00219  *
00220  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00221  *                         the application. It identifies the particular client instance to use.
00222  *
00223  * @return     NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
00224  */
00225 uint32_t ble_ans_c_enable_notif_unread_alert(const ble_ans_c_t * p_ans);
00226 
00227 
00228 /**@brief Function for writing to the CCCD to disable new alert notifications from the Alert Notification Service.
00229  *
00230  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00231  *                         the application. It identifies the particular client instance to use.
00232  *
00233  * @return     NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
00234  */
00235 uint32_t ble_ans_c_disable_notif_new_alert(const ble_ans_c_t * p_ans);
00236 
00237 
00238 /**@brief Function for writing to the CCCD to disable unread alert notifications from the Alert Notification Service.
00239  *
00240  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00241  *                         the application. It identifies the particular client instance to use.
00242  *
00243  * @return     NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
00244  */
00245 uint32_t ble_ans_c_disable_notif_unread_alert(const ble_ans_c_t * p_ans);
00246 
00247 
00248 /**@brief Function for writing to the Alert Notification Control Point to specify alert notification behavior in the
00249  * Alert Notification Service on the Central.
00250  *
00251  * @param[in]  p_ans           Alert Notification structure. This structure will have to be
00252  *                             supplied by the application. It identifies the particular client
00253  *                             instance to use.
00254  * @param[in]  p_control_point Alert Notification Control Point structure. This structure
00255  *                             specifies the values to write to the Alert Notification Control
00256  *                             Point, UUID 0x2A44.
00257  *
00258  * @return     NRF_SUCCESS     on successful writing of the Control Point, otherwise an error code.
00259  */
00260 uint32_t ble_ans_c_control_point_write(const ble_ans_c_t * p_ans,
00261                                        const ble_ans_control_point_t * p_control_point);
00262 
00263 
00264 /**@brief Function for reading the Supported New Alert characteristic value of the service.
00265  *        The value describes the alerts supported in the central.
00266  *
00267  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00268  *                         the application. It identifies the particular client instance to use.
00269  *
00270  * @return     NRF_SUCCESS on successful transmission of the read request, otherwise an error code.
00271  */
00272 uint32_t ble_ans_c_new_alert_read(const ble_ans_c_t * p_ans);
00273 
00274 
00275 /**@brief Function for reading the Supported Unread Alert characteristic value of the service.
00276  *        The value describes the alerts supported in the central.
00277  *
00278  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00279  *                         the application. It identifies the particular client instance to use.
00280  *
00281  * @return     NRF_SUCCESS on successful transmission of the read request, otherwise an error code.
00282  */
00283 uint32_t ble_ans_c_unread_alert_read(const ble_ans_c_t * p_ans);
00284 
00285 
00286 /**@brief Function for requesting the peer to notify the New Alert characteristics immediately.
00287  *
00288  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00289  *                         the application. It identifies the particular client instance to use.
00290  * @param[in]  category    The category ID for which the peer should notify the client.
00291  *
00292  * @return     NRF_SUCCESS on successful transmission of the read request, otherwise an error code.
00293  */
00294 uint32_t ble_ans_c_new_alert_notify(const ble_ans_c_t * p_ans, ble_ans_category_id_t category);
00295 
00296 
00297 /**@brief Function for requesting the peer to notify the Unread Alert characteristics immediately.
00298  *
00299  * @param[in]  p_ans       Alert Notification structure. This structure will have to be supplied by
00300  *                         the application. It identifies the particular client instance to use.
00301  * @param[in]  category    The category ID for which the peer should notify the client.
00302  *
00303  * @return     NRF_SUCCESS on successful transmission of the read request, otherwise an error code.
00304  */
00305 uint32_t ble_ans_c_unread_alert_notify(const ble_ans_c_t * p_ans, ble_ans_category_id_t category);
00306 
00307 
00308 /**@brief  Function for loading previous discovered service and characteristic handles for bonded centrals from
00309  *          flash into RAM.
00310  *
00311  * @details Read the database of all discovered service and characteristic handles from flash.
00312  *          If the flash does not contain any valid data, the array of discovered service handles in
00313  *          RAM will be empty.
00314  *
00315  * @param[in] p_ans  Alert Notification structure. This structure will have to be supplied by the
00316  *                   application. It identifies the particular client instance to use.
00317  *
00318  * @note    Currently the Alert Notification Client uses only one page in flash.
00319  *
00320  * @return  NRF_SUCCESS if all operations went successfully, an error_code otherwise.
00321  */
00322 uint32_t ble_ans_c_service_load(const ble_ans_c_t * p_ans);
00323 
00324 
00325 /**@brief Function for storing discovered service and characteristic handles for bonded centrals into flash memory.
00326  *
00327  * @details This function will erase the flash page (if the data to store
00328  *          are diferent than the one already stored) and then write into flash. Those
00329  *          operations could prevent the radio to run.
00330  *
00331  * @note    Do not call this function while in a connection or when advertising. If you do, the
00332  *          behavior is undefined.
00333  *
00334  * @return  NRF_SUCCESS if all operations went successfully, an error_code otherwise.
00335  */
00336 uint32_t ble_ans_c_service_store(void);
00337 
00338 
00339 /**@brief Function for deleting the Alert Notification Client database from flash.
00340  *
00341  * @details After calling this function you should call ble_ans_c_init(...) to re-initialize
00342  *          the RAM database.
00343  *
00344  * @return  NRF_SUCCESS if all operations went successfully.
00345  */
00346 uint32_t ble_ans_c_service_delete(void);
00347 
00348 #endif // BLE_ANS_C_H__
00349 
00350 /** @} */
00351