| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Typedefs | Enumerations | Functions
Alert Notification Service Client
BLE Services

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
| Struct to hold 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. 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...

## 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 application on an event. More...

## Functions
void | ble_ans_c_on_db_disc_evt (ble_ans_c_t *p_ans, const ble_db_discovery_evt_t *p_evt)
| Function for handling events from the database discovery module. More...
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...
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_handles_assign (ble_ans_c_t *p_ans, const uint16_t conn_handle, const ble_ans_c_service_t *p_peer_handles)
| Function for assigning a handles to a 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 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.

## 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_DISCOVERY_COMPLETE | A successful connection has been established and the characteristics of the server has been 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 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_handles_assign | ( | ble_ans_c_t * | p_ans,
|  | const uint16_t | conn_handle,
|  | const ble_ans_c_service_t * | p_peer_handles
| ) |  |

Function for assigning a handles to a an instance of ans_c.

Call this function when a link has been established with a peer to associate this link to an instance of the module. This makes it possible to handle several link and associate each link to a particular instance of the ans_c module. The connection handle and attribute handles will be provided from the discovery event BLE_ANS_C_EVT_DISCOVERY_COMPLETE.

Parameters

  [in] | p_ans | Pointer to the Alert Notification client structure instance to associate with the handles.
  [in] | conn_handle | Connection handle to associated with the given Alert Notification Client Instance.
  [in] | p_peer_handles | Attribute 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,
|  | 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_db_disc_evt | ( | ble_ans_c_t * | p_ans,
|  | const ble_db_discovery_evt_t * | p_evt
| ) |  |

Function for handling events from the database discovery module.

Call this function when getting a callback event from the DB discovery modue. This function will handle an event from the database discovery module, and determine if it relates to the discovery of heart rate service at the peer. If so, it will call the application's event handler indicating that the heart rate service has been discovered at the peer. It also populates the event with the service related information before providing it to the application.

Parameters

  [in] | p_ans | Pointer to the Alert Notification client structure instance that will handle the discovery.
  [in] | p_evt | Pointer to the event received from the database discovery module.

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.