nRF5 SDK v17.1.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Alert Notification Service Client

Alert Notification module. More...

Modules

 Alert Notification Service Client configuration
 

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_service_t
 Structure for holding information on the Alert Notification Service, if found on the server. More...
 
struct  ble_ans_c_evt_t
 Alert Notification Event structure. More...
 
struct  ble_ans_c_s
 Alert Notification structure. Contains various status information for the client. More...
 
struct  ble_ans_c_init_t
 Alert Notification init structure. Contains all options and data needed for the initialization of the client. More...
 

Macros

#define BLE_ANS_C_DEF(_name)
 Macro for defining a ble_ans_c instance. More...
 
#define BLE_ANS_C_ARRAY_DEF(_name, _cnt)
 Macro for defining multiple ble_ans_c instances. More...
 

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_DISCOVERY_COMPLETE,
  BLE_ANS_C_EVT_DISCOVERY_FAILED,
  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 the application on an event. More...
 

Functions

void ble_ans_c_on_db_disc_evt (ble_ans_c_t *p_ans, ble_db_discovery_evt_t const *p_evt)
 Function for handling events from the Database Discovery module. More...
 
void ble_ans_c_on_ble_evt (ble_evt_t const *p_ble_evt, void *p_context)
 Function for handling the application's BLE stack events. More...
 
uint32_t ble_ans_c_init (ble_ans_c_t *p_ans, ble_ans_c_init_t const *p_ans_init)
 Function for initializing the Alert Notification Client. More...
 
uint32_t ble_ans_c_enable_notif_new_alert (ble_ans_c_t const *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 (ble_ans_c_t const *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 (ble_ans_c_t const *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 (ble_ans_c_t const *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 (ble_ans_c_t const *p_ans, ble_ans_control_point_t const *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 (ble_ans_c_t const *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 (ble_ans_c_t const *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 (ble_ans_c_t const *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 (ble_ans_c_t const *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_handles_assign (ble_ans_c_t *p_ans, uint16_t const conn_handle, ble_ans_c_service_t const *p_peer_handles)
 Function for assigning handles to an instance of ans_c. More...
 

Detailed Description

Alert Notification module.

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:
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 BLE_ANS_C_ARRAY_DEF (   _name,
  _cnt 
)

Macro for defining multiple ble_ans_c instances.

Parameters
_nameName of the array of instances.
_cntNumber of instances to define.
#define BLE_ANS_C_DEF (   _name)

Macro for defining a ble_ans_c instance.

Parameters
_nameName of the instance.

Enumeration Type Documentation

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

Enumerator
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.

Alert 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 

Email message 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 or MMS message arrives.

ANS_TYPE_VOICE_MAIL 

Voice mail.

ANS_TYPE_SCHEDULE 

Alert that occurs on calendar, planner.

ANS_TYPE_HIGH_PRIORITIZED_ALERT 

Alert to be handled as high priority.

ANS_TYPE_INSTANT_MESSAGE 

Alert for incoming instant messages.

ANS_TYPE_ALL_ALERTS 

Identifies all alerts.

Alert 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 ( ble_ans_c_t const *  p_ans,
ble_ans_control_point_t const *  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_ansAlert Notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
[in]p_control_pointAlert 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, this API propagates the error code returned by function nrf_ble_gq_item_add.
uint32_t ble_ans_c_disable_notif_new_alert ( ble_ans_c_t const *  p_ans)

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

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

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

Parameters
[in]p_ansAlert Notification structure. This structure must 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 ( ble_ans_c_t const *  p_ans)

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

Parameters
[in]p_ansAlert Notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Returns
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)

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

Parameters
[in]p_ansAlert Notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful writing of the CCCD. Otherwise, it returns an error code.
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 
)

Function for assigning handles to an instance of ans_c.

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 BLE_ANS_C_EVT_DISCOVERY_COMPLETE.

Parameters
[in]p_ansPointer to the Alert Notification client structure instance to associate with the handles.
[in]conn_handleConnection handle to associated with the given Alert Notification Client Instance.
[in]p_peer_handlesAttribute handles on the ANS server that you want this ANS client to interact with.
uint32_t ble_ans_c_init ( ble_ans_c_t p_ans,
ble_ans_c_init_t const *  p_ans_init 
)

Function for initializing the Alert Notification Client.

Parameters
[out]p_ansAlert 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.
[in]p_ans_initInformation needed to initialize the client.
Returns
NRF_SUCCESS on successful initialization of client. 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 
)

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

Parameters
[in]p_ansAlert Notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
[in]categoryThe category ID for which the peer should notify the client.
Returns
NRF_SUCCESS on successful transmission of the read request. Otherwise, it returns an error code.
uint32_t ble_ans_c_new_alert_read ( ble_ans_c_t const *  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_ansAlert Notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful transmission of the read request. Otherwise, this API propagates the error code returned by function nrf_ble_gq_item_add.
void ble_ans_c_on_ble_evt ( ble_evt_t const *  p_ble_evt,
void *  p_context 
)

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_ble_evtEvent received from the BLE stack.
[in]p_contextAlert Notification Client structure.
void ble_ans_c_on_db_disc_evt ( ble_ans_c_t p_ans,
ble_db_discovery_evt_t const *  p_evt 
)

Function for handling events from the Database Discovery module.

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.

Parameters
[in]p_ansPointer to the Alert Notification client structure instance that will handle the discovery.
[in]p_evtPointer to the event received from the Database Discovery module.
uint32_t ble_ans_c_unread_alert_notify ( ble_ans_c_t const *  p_ans,
ble_ans_category_id_t  category 
)

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

Parameters
[in]p_ansAlert Notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
[in]categoryThe category ID for which the peer should notify the client.
Returns
NRF_SUCCESS on successful transmission of the read request. Otherwise, it returns an error code.
uint32_t ble_ans_c_unread_alert_read ( ble_ans_c_t const *  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_ansAlert Notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Returns
NRF_SUCCESS on successful transmission of the read request. Otherwise, this API propagates the error code returned by function nrf_ble_gq_item_add.

Documentation feedback | Developer Zone | Subscribe | Updated