Alert Notification Service Client

nRF5 SDK v9.0.0
nRF51 SDK v9.0.0
Data Structures | Macros | Typedefs | Enumerations | Functions

Alert Notification module. More...

Data Structures

struct ble_ans_control_point_t
Alert Notification Control Point structure. More...
struct ble_ans_alert_settings_t
Alert Notification Setting structure containing the supported alerts in the service. More...
struct ble_ans_alert_notification_t
Alert Notification structure. More...
struct ble_ans_c_evt_t
Alert Notification Event structure. More...
struct ble_ans_c_s
Alert Notification structure. This contains various status information for the client. More...
struct ble_ans_c_init_t
Alert Notification init structure. This contains all options and data needed for initialization of the client. More...

Macros

#define ANS_NB_OF_CHARACTERISTICS 5
#define ANS_NB_OF_SERVICES 1
#define INVALID_SERVICE_HANDLE_BASE 0xF0
#define INVALID_SERVICE_HANDLE ( INVALID_SERVICE_HANDLE_BASE + 0x0F)
#define INVALID_SERVICE_HANDLE_DISC ( INVALID_SERVICE_HANDLE_BASE + 0x0E)
#define BLE_ANS_INVALID_HANDLE 0xFF

Typedefs

typedef struct ble_ans_c_s ble_ans_c_t
typedef void(* ble_ans_c_evt_handler_t )( ble_ans_c_evt_t *p_evt)
Alert Notification event handler type.

Enumerations

enum ble_ans_category_id_t {
ANS_TYPE_SIMPLE_ALERT = 0,
ANS_TYPE_EMAIL = 1,
ANS_TYPE_NEWS = 2,
ANS_TYPE_NOTIFICATION_CALL = 3,
ANS_TYPE_MISSED_CALL = 4,
ANS_TYPE_SMS_MMS = 5,
ANS_TYPE_VOICE_MAIL = 6,
ANS_TYPE_SCHEDULE = 7,
ANS_TYPE_HIGH_PRIORITIZED_ALERT = 8,
ANS_TYPE_INSTANT_MESSAGE = 9,
ANS_TYPE_ALL_ALERTS = 0xFF
}
enum ble_ans_command_id_t {
ANS_ENABLE_NEW_INCOMING_ALERT_NOTIFICATION = 0,
ANS_ENABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION = 1,
ANS_DISABLE_NEW_INCOMING_ALERT_NOTIFICATION = 2,
ANS_DISABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION = 3,
ANS_NOTIFY_NEW_INCOMING_ALERT_IMMEDIATELY = 4,
ANS_NOTIFY_UNREAD_CATEGORY_STATUS_IMMEDIATELY = 5
}
enum ble_ans_c_evt_type_t {
BLE_ANS_C_EVT_DISCOVER_COMPLETE ,
BLE_ANS_C_EVT_DISCOVER_FAILED ,
BLE_ANS_C_EVT_RECONNECT ,
BLE_ANS_C_EVT_DISCONN_COMPLETE ,
BLE_ANS_C_EVT_NOTIFICATION ,
BLE_ANS_C_EVT_READ_RESP ,
BLE_ANS_C_EVT_WRITE_RESP
}
Alert Notification Event types that are passed from client to application on an event. More...

Functions

void ble_ans_c_on_ble_evt ( ble_ans_c_t *p_ans, const ble_evt_t *p_ble_evt)
Function for handling the Application's BLE Stack events. More...
void ble_ans_c_on_device_manager_evt ( ble_ans_c_t *p_ans, dm_handle_t const *p_handle, dm_event_t const *p_dm_evt)
Function for handling the Alert Notification Client - Device Manager Event. More...
uint32_t ble_ans_c_init ( ble_ans_c_t *p_ans, const ble_ans_c_init_t *p_ans_init)
Function for initializing the Alert Notification Client. More...
uint32_t ble_ans_c_enable_notif_new_alert (const ble_ans_c_t *p_ans)
Function for writing the to CCCD to enable new alert notifications from the Alert Notification Service. More...
uint32_t ble_ans_c_enable_notif_unread_alert (const ble_ans_c_t *p_ans)
Function for writing to the CCCD to enable unread alert notifications from the Alert Notification Service. More...
uint32_t ble_ans_c_disable_notif_new_alert (const ble_ans_c_t *p_ans)
Function for writing to the CCCD to disable new alert notifications from the Alert Notification Service. More...
uint32_t ble_ans_c_disable_notif_unread_alert (const ble_ans_c_t *p_ans)
Function for writing to the CCCD to disable unread alert notifications from the Alert Notification Service. More...
uint32_t ble_ans_c_control_point_write (const ble_ans_c_t *p_ans, const ble_ans_control_point_t *p_control_point)
Function for writing to the Alert Notification Control Point to specify alert notification behavior in the Alert Notification Service on the Central. More...
uint32_t ble_ans_c_new_alert_read (const ble_ans_c_t *p_ans)
Function for reading the Supported New Alert characteristic value of the service. The value describes the alerts supported in the central. More...
uint32_t ble_ans_c_unread_alert_read (const ble_ans_c_t *p_ans)
Function for reading the Supported Unread Alert characteristic value of the service. The value describes the alerts supported in the central. More...
uint32_t ble_ans_c_new_alert_notify (const ble_ans_c_t *p_ans, ble_ans_category_id_t category)
Function for requesting the peer to notify the New Alert characteristics immediately. More...
uint32_t ble_ans_c_unread_alert_notify (const ble_ans_c_t *p_ans, ble_ans_category_id_t category)
Function for requesting the peer to notify the Unread Alert characteristics immediately. More...
uint32_t ble_ans_c_service_load (const ble_ans_c_t *p_ans)
Function for loading previous discovered service and characteristic handles for bonded centrals from flash into RAM. More...
uint32_t ble_ans_c_service_store (void)
Function for storing discovered service and characteristic handles for bonded centrals into flash memory. More...
uint32_t ble_ans_c_service_delete (void)
Function for deleting the Alert Notification Client database from flash. More...

Detailed Description

Alert Notification module.

This module implements the Alert Notification Client according to the Alert Notification Profile.

Note
The application must propagate BLE stack events to the Alert Notification Client module by calling ble_ans_c_on_ble_evt() from the SoftDevice Event Handler callback.
Attention! To maintain compliance with Nordic Semiconductor ASA Bluetooth profile qualification listings, this section of source code must not be modified.

Macro Definition Documentation

#define ANS_NB_OF_CHARACTERISTICS   5

Number of characteristics as defined by Alert Notification Service specification.

#define ANS_NB_OF_SERVICES   1

Number of services supported in one central.

#define BLE_ANS_INVALID_HANDLE   0xFF

Indication that the current service handle is invalid.

#define INVALID_SERVICE_HANDLE   ( INVALID_SERVICE_HANDLE_BASE + 0x0F)

Indication that the current service handle is invalid.

#define INVALID_SERVICE_HANDLE_BASE   0xF0

Base for indicating invalid service handle.

#define INVALID_SERVICE_HANDLE_DISC   ( INVALID_SERVICE_HANDLE_BASE + 0x0E)

Indication that the current service handle is invalid but the service has been discovered.

Enumeration Type Documentation

enum ble_ans_c_evt_type_t

Alert Notification Event types that are passed from client to application on an event.

Enumerator
BLE_ANS_C_EVT_DISCOVER_COMPLETE

A successful connection has been established and the characteristics of the server has been fetched.

BLE_ANS_C_EVT_DISCOVER_FAILED

It was not possible to discover service or characteristics of the connected peer.

BLE_ANS_C_EVT_RECONNECT

A re-connection to a known and previously discovered central has occurred.

BLE_ANS_C_EVT_DISCONN_COMPLETE

The connection has been taken down.

BLE_ANS_C_EVT_NOTIFICATION

A valid Alert Notification has been received from the server.

BLE_ANS_C_EVT_READ_RESP

A read response has been received from the server.

BLE_ANS_C_EVT_WRITE_RESP

A write response has been received from the server.

enum ble_ans_category_id_t

Alerts types as defined in the alert category id; UUID: 0x2A43.

Enumerator
ANS_TYPE_SIMPLE_ALERT

General text alert or non-text alert.

ANS_TYPE_EMAIL

Alert when email messages arrives.

ANS_TYPE_NEWS

News feeds such as RSS, Atom.

ANS_TYPE_NOTIFICATION_CALL

Incoming call.

ANS_TYPE_MISSED_CALL

Missed call.

ANS_TYPE_SMS_MMS

SMS/MMS message arrives.

ANS_TYPE_VOICE_MAIL

Voice mail.

ANS_TYPE_SCHEDULE

Alert occurred on calendar, planner.

ANS_TYPE_HIGH_PRIORITIZED_ALERT

Alert that should be handled as high priority.

ANS_TYPE_INSTANT_MESSAGE

Alert for incoming instant messages.

ANS_TYPE_ALL_ALERTS

Identifies All Alerts.

enum ble_ans_command_id_t

Alerts notification control point commands as defined in the Alert Notification Specification; UUID: 0x2A44.

Enumerator
ANS_ENABLE_NEW_INCOMING_ALERT_NOTIFICATION

Enable New Incoming Alert Notification.

ANS_ENABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION

Enable Unread Category Status Notification.

ANS_DISABLE_NEW_INCOMING_ALERT_NOTIFICATION

Disable New Incoming Alert Notification.

ANS_DISABLE_UNREAD_CATEGORY_STATUS_NOTIFICATION

Disable Unread Category Status Notification.

ANS_NOTIFY_NEW_INCOMING_ALERT_IMMEDIATELY

Notify New Incoming Alert immediately.

ANS_NOTIFY_UNREAD_CATEGORY_STATUS_IMMEDIATELY

Notify Unread Category Status immediately.

Function Documentation

uint32_t ble_ans_c_control_point_write ( const ble_ans_c_t * p_ans ,
const ble_ans_control_point_t * p_control_point
)

Function for writing to the Alert Notification Control Point to specify alert notification behavior in the Alert Notification Service on the Central.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
[in] p_control_point Alert Notification Control Point structure. This structure specifies the values to write to the Alert Notification Control Point, UUID 0x2A44.
Returns
NRF_SUCCESS on successful writing of the Control Point, otherwise an error code.
uint32_t ble_ans_c_disable_notif_new_alert ( const ble_ans_c_t * p_ans )

Function for writing to the CCCD to disable new alert notifications from the Alert Notification Service.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
uint32_t ble_ans_c_disable_notif_unread_alert ( const ble_ans_c_t * p_ans )

Function for writing to the CCCD to disable unread alert notifications from the Alert Notification Service.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
uint32_t ble_ans_c_enable_notif_new_alert ( const ble_ans_c_t * p_ans )

Function for writing the to CCCD to enable new alert notifications from the Alert Notification Service.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
uint32_t ble_ans_c_enable_notif_unread_alert ( const ble_ans_c_t * p_ans )

Function for writing to the CCCD to enable unread alert notifications from the Alert Notification Service.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful writing of the CCCD, otherwise an error code.
uint32_t ble_ans_c_init ( ble_ans_c_t * p_ans ,
const ble_ans_c_init_t * p_ans_init
)

Function for initializing the Alert Notification Client.

Parameters
[out] p_ans Alert Notification Client structure. This structure will have to be supplied by the application. It will be initialized by this function, and will later be used to identify this particular client instance.
[in] p_ans_init Information needed to initialize the client.
Returns
NRF_SUCCESS on successful initialization of client, otherwise an error code.
uint32_t ble_ans_c_new_alert_notify ( const ble_ans_c_t * p_ans ,
ble_ans_category_id_t category
)

Function for requesting the peer to notify the New Alert characteristics immediately.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
[in] category The category ID for which the peer should notify the client.
Returns
NRF_SUCCESS on successful transmission of the read request, otherwise an error code.
uint32_t ble_ans_c_new_alert_read ( const ble_ans_c_t * p_ans )

Function for reading the Supported New Alert characteristic value of the service. The value describes the alerts supported in the central.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful transmission of the read request, otherwise an error code.
void ble_ans_c_on_ble_evt ( ble_ans_c_t * p_ans ,
const ble_evt_t * p_ble_evt
)

Function for handling the Application's BLE Stack events.

Handles all events from the BLE stack of interest to the Alert Notification Client.

Parameters
[in] p_ans Alert Notification Client structure.
[in] p_ble_evt Event received from the BLE stack.
void ble_ans_c_on_device_manager_evt ( ble_ans_c_t * p_ans ,
dm_handle_t const * p_handle ,
dm_event_t const * p_dm_evt
)

Function for handling the Alert Notification Client - Device Manager Event.

Handles all events from the Bond Manager of interest to the Alert Notification Client. The Alert Notification Client will use the events of re-connection to existing central and creation of new bonds for handling of service discovery and writing of the Alert Notification Control Point for re-send of New Alert and Unread Alert notifications.

Parameters
[in] p_ans Alert Notification Client structure.
[in] p_handle Handle.
[in] p_dm_evt Event received from the Bond Manager.
uint32_t ble_ans_c_service_delete ( void )

Function for deleting the Alert Notification Client database from flash.

After calling this function you should call ble_ans_c_init(...) to re-initialize the RAM database.

Returns
NRF_SUCCESS if all operations went successfully.
uint32_t ble_ans_c_service_load ( const ble_ans_c_t * p_ans )

Function for loading previous discovered service and characteristic handles for bonded centrals from flash into RAM.

Read the database of all discovered service and characteristic handles from flash. If the flash does not contain any valid data, the array of discovered service handles in RAM will be empty.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Note
Currently the Alert Notification Client uses only one page in flash.
Returns
NRF_SUCCESS if all operations went successfully, an error_code otherwise.
uint32_t ble_ans_c_service_store ( void )

Function for storing discovered service and characteristic handles for bonded centrals into flash memory.

This function will erase the flash page (if the data to store are diferent than the one already stored) and then write into flash. Those operations could prevent the radio to run.

Note
Do not call this function while in a connection or when advertising. If you do, the behavior is undefined.
Returns
NRF_SUCCESS if all operations went successfully, an error_code otherwise.
uint32_t ble_ans_c_unread_alert_notify ( const ble_ans_c_t * p_ans ,
ble_ans_category_id_t category
)

Function for requesting the peer to notify the Unread Alert characteristics immediately.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
[in] category The category ID for which the peer should notify the client.
Returns
NRF_SUCCESS on successful transmission of the read request, otherwise an error code.
uint32_t ble_ans_c_unread_alert_read ( const ble_ans_c_t * p_ans )

Function for reading the Supported Unread Alert characteristic value of the service. The value describes the alerts supported in the central.

Parameters
[in] p_ans Alert Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful transmission of the read request, otherwise an error code.

Please send us your feedback about the documentation! For technical questions, visit the Nordic Developer Zone .