| 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 | Macros | Typedefs | Enumerations | Functions | Variables
Apple Notification Service client
BLE Services

Apple Notification Center Service Client Module. More...

## Modules
| Apple Notification Service Client configuration

## Data Structures
struct | ble_ancs_c_notif_flags_t
| Flags for iOS notifications. More...
struct | ble_ancs_c_evt_notif_t
| iOS notification structure. More...
struct | ble_ancs_c_evt_notif_attr_t
| iOS notification attribute structure for incomming attributes. More...
struct | ble_ancs_c_attr_list_t
| iOS notification attribute content wanted by our application. More...
struct | ble_ancs_c_service_t
| Structure used for holding the Apple Notification Center Service found during the discovery process. More...
struct | ble_ancs_c_evt_t
| ANCS client module event structure. More...
struct | ble_ancs_c_t
| iOS notification structure, which contains various status information for the client. More...
struct | ble_ancs_c_init_t
| Apple Notification client init structure, which contains all options and data needed for initialization of the client. More...

## Macros
#define | BLE_ANCS_ATTR_DATA_MAX 32
#define | BLE_ANCS_NB_OF_CATEGORY_ID 12
#define | BLE_ANCS_NB_OF_ATTRS 8
#define | BLE_ANCS_NB_OF_EVT_ID 3
#define | BLE_ANCS_NOTIFICATION_DATA_LENGTH 8
| Length of the iOS notification data. More...
#define | ANCS_UUID_SERVICE 0xF431
#define | ANCS_UUID_CHAR_CONTROL_POINT 0xD8F3
#define | ANCS_UUID_CHAR_DATA_SOURCE 0xC6E9
#define | ANCS_UUID_CHAR_NOTIFICATION_SOURCE 0x120D
#define | BLE_ANCS_EVENT_FLAG_SILENT 0
#define | BLE_ANCS_EVENT_FLAG_IMPORTANT 1
#define | BLE_ANCS_EVENT_FLAG_PREEXISTING 2
#define | BLE_ANCS_EVENT_FLAG_POSITIVE_ACTION 3
#define | BLE_ANCS_EVENT_FLAG_NEGATIVE_ACTION 4

## Typedefs
typedef void(* | ble_ancs_c_evt_handler_t )(ble_ancs_c_evt_t *p_evt)
| iOS notification event handler type.

## Enumerations
enum | ble_ancs_c_evt_type_t { BLE_ANCS_C_EVT_DISCOVERY_COMPLETE, BLE_ANCS_C_EVT_DISCOVERY_FAILED, BLE_ANCS_C_EVT_NOTIF, BLE_ANCS_C_EVT_INVALID_NOTIF, BLE_ANCS_C_EVT_NOTIF_ATTRIBUTE }
| Event types that are passed from client to application on an event. More...
enum | ble_ancs_c_category_id_values_t { BLE_ANCS_CATEGORY_ID_OTHER, BLE_ANCS_CATEGORY_ID_INCOMING_CALL, BLE_ANCS_CATEGORY_ID_MISSED_CALL, BLE_ANCS_CATEGORY_ID_VOICE_MAIL, BLE_ANCS_CATEGORY_ID_SOCIAL, BLE_ANCS_CATEGORY_ID_SCHEDULE, BLE_ANCS_CATEGORY_ID_EMAIL, BLE_ANCS_CATEGORY_ID_NEWS, BLE_ANCS_CATEGORY_ID_HEALTH_AND_FITNESS, BLE_ANCS_CATEGORY_ID_BUSINESS_AND_FINANCE, BLE_ANCS_CATEGORY_ID_LOCATION, BLE_ANCS_CATEGORY_ID_ENTERTAINMENT }
| Category IDs for iOS notifications. More...
enum | ble_ancs_c_evt_id_values_t { BLE_ANCS_EVENT_ID_NOTIFICATION_ADDED, BLE_ANCS_EVENT_ID_NOTIFICATION_MODIFIED, BLE_ANCS_EVENT_ID_NOTIFICATION_REMOVED }
| Event IDs for iOS notifications. More...
enum | ble_ancs_c_command_id_values_t { BLE_ANCS_COMMAND_ID_GET_NOTIF_ATTRIBUTES, BLE_ANCS_COMMAND_ID_GET_APP_ATTRIBUTES, BLE_ANCS_COMMAND_ID_GET_PERFORM_NOTIF_ACTION }
| Control point command IDs that the Notification Consumer can send to the Notification Provider. More...
enum | ble_ancs_c_notif_attr_id_values_t { BLE_ANCS_NOTIF_ATTR_ID_APP_IDENTIFIER, BLE_ANCS_NOTIF_ATTR_ID_TITLE, BLE_ANCS_NOTIF_ATTR_ID_SUBTITLE, BLE_ANCS_NOTIF_ATTR_ID_MESSAGE, BLE_ANCS_NOTIF_ATTR_ID_MESSAGE_SIZE, BLE_ANCS_NOTIF_ATTR_ID_DATE, BLE_ANCS_NOTIF_ATTR_ID_POSITIVE_ACTION_LABEL, BLE_ANCS_NOTIF_ATTR_ID_NEGATIVE_ACTION_LABEL }
| IDs for iOS notification attributes. More...
enum | ble_ancs_c_parse_state_t { COMMAND_ID_AND_NOTIF_UID, ATTR_ID, ATTR_LEN1, ATTR_LEN2, ATTR_DATA, DONE }
| Parsing states for received iOS notification attributes. More...

## Functions
void | ble_ancs_c_on_ble_evt (ble_ancs_c_t *p_ancs, const ble_evt_t *p_ble_evt)
| Function for handling the application's BLE Stack events. More...
void | ble_ancs_c_on_db_disc_evt (ble_ancs_c_t *p_ancs, ble_db_discovery_evt_t *p_evt)
| Function for handling events from the database discovery module. More...
uint32_t | ble_ancs_c_init (ble_ancs_c_t *p_ancs, const ble_ancs_c_init_t *p_ancs_init)
| Function for initializing the ANCS client. More...
uint32_t | ble_ancs_c_notif_source_notif_enable (const ble_ancs_c_t *p_ancs)
| Function for writing to the CCCD to enable notifications from the Apple Notification Service. More...
uint32_t | ble_ancs_c_data_source_notif_enable (const ble_ancs_c_t *p_ancs)
| Function for writing to the CCCD to enable data source notifications from the ANCS. More...
uint32_t | ble_ancs_c_notif_source_notif_disable (const ble_ancs_c_t *p_ancs)
| Function for writing to the CCCD to disable notifications from the ANCS. More...
uint32_t | ble_ancs_c_data_source_notif_disable (const ble_ancs_c_t *p_ancs)
| Function for writing to the CCCD to disable data source notifications from the ANCS. More...
uint32_t | ble_ancs_c_attr_add (ble_ancs_c_t *p_ancs, const ble_ancs_c_notif_attr_id_values_t id, uint8_t *p_data, const uint16_t len)
| Function for registering attributes that will be requested if ble_ancs_c_request_attrs is called. More...
uint32_t | ble_ancs_c_request_attrs (ble_ancs_c_t *p_ancs, const ble_ancs_c_evt_notif_t *p_notif)
| Function for requesting attributes for a notification. More...
uint32_t | ble_ancs_c_handles_assign (ble_ancs_c_t *p_ancs, const uint16_t conn_handle, const ble_ancs_c_service_t *p_service)
| Function for assigning handle to a this instance of ancs_c. More...

## Variables
const ble_uuid128_t | ble_ancs_base_uuid128
| Apple Notification Center Service UUIDs. More...
const ble_uuid128_t | ble_ancs_cp_base_uuid128
const ble_uuid128_t | ble_ancs_ns_base_uuid128
const ble_uuid128_t | ble_ancs_ds_base_uuid128

## Detailed Description

Apple Notification Center Service Client Module.

Disclaimer: This client implementation of the Apple Notification Center Service can be changed at any time by Nordic Semiconductor ASA. Server implementations such as the ones found in iOS can be changed at any time by Apple and may cause this client implementation to stop working.

This module implements the Apple Notification Center Service (ANCS) client. This client can be used as a Notification Consumer (NC) that receives data notifications from a Notification Provider (NP). The NP is typically an iOS device acting as a server. For terminology and up-to-date specs, see http://developer.apple.com.

The term "notification" is used in two different meanings:

- An iOS notification is the data received from the Notification Provider.
- A GATTC notification is a way to transfer data with Bluetooth Smart. In this module, we receive iOS notifications using GATTC notifications. We use the full term (iOS notification or GATTC notification) where required to avoid confusion.

Upon initializing the module, you must add the different iOS notification attributes you would like to receive for iOS notifications. ble_ancs_c_attr_add.

Once a connection is established with a central device, the module does a service discovery to discover the ANVS server handles. If this succeeds (BLE_ANCS_C_EVT_DISCOVERY_COMPLETE) The handles for the CTS server are part of the ble_ancs_c_evt_t structure and must be assigned to a ANCS_C instance using the ble_ancs_c_handles_assign function. For more information about service discovery, see the ble_discovery module documentation Database Discovery Module.

The application can now subscribe to iOS notifications using ble_ancs_c_notif_source_notif_enable. They arrive in the BLE_ANCS_C_EVT_NOTIF event. ble_ancs_c_request_attrs can be used to request attributes for the notifications. They arrive in the BLE_ANCS_C_EVT_NOTIF_ATTRIBUTE event.

Note
  The application must propagate BLE stack events to this module by calling ble_ancs_c_on_ble_evt() from the SoftDevice Event Handler callback.

## Macro Definition Documentation

#define ANCS_UUID_CHAR_CONTROL_POINT 0xD8F3

16-bit control point UUID.

#define ANCS_UUID_CHAR_DATA_SOURCE 0xC6E9

16-bit data source UUID.

#define ANCS_UUID_CHAR_NOTIFICATION_SOURCE 0x120D

16-bit notification source UUID.

#define ANCS_UUID_SERVICE 0xF431

16-bit service UUID for the Apple Notification Center Service.

#define BLE_ANCS_ATTR_DATA_MAX 32

Maximum data length of an iOS notification attribute.

#define BLE_ANCS_EVENT_FLAG_IMPORTANT 1

0b......1. Important: Second (LSB) bit is set. All flags can be active at the same time.

#define BLE_ANCS_EVENT_FLAG_NEGATIVE_ACTION 4

0b...1.... Negative action: Fifth (LSB) bit is set. All flags can be active at the same time.

#define BLE_ANCS_EVENT_FLAG_POSITIVE_ACTION 3

0b....1... Positive action: Fourth (LSB) bit is set. All flags can be active at the same time.

#define BLE_ANCS_EVENT_FLAG_PREEXISTING 2

0b.....1.. Pre-existing: Third (LSB) bit is set. All flags can be active at the same time.

#define BLE_ANCS_EVENT_FLAG_SILENT 0

0b.......1 Silent: First (LSB) bit is set. All flags can be active at the same time.

#define BLE_ANCS_NB_OF_ATTRS 8

Number of iOS notification attributes: AppIdentifier, Title, Subtitle, Message, MessageSize, Date, PositiveActionLabel, NegativeActionLabel.

#define BLE_ANCS_NB_OF_CATEGORY_ID 12

Number of iOS notification categories: Other, Incoming Call, Missed Call, Voice Mail, Social, Schedule, Email, News, Health And Fitness, Business And Finance, Location, Entertainment.

#define BLE_ANCS_NB_OF_EVT_ID 3

Number of iOS notification events: Added, Modified, Removed.

#define BLE_ANCS_NOTIFICATION_DATA_LENGTH 8

Length of the iOS notification data.

8 bytes:

Event ID | Event flags | Category ID | Category count | Notification UID
--- | --- | --- | --- | ---
1 byte | 1 byte | 1 byte | 1 byte | 4 bytes

## Enumeration Type Documentation

enum ble_ancs_c_category_id_values_t

Category IDs for iOS notifications.

Enumerator
BLE_ANCS_CATEGORY_ID_OTHER | The iOS notification belongs to the "other" category.
BLE_ANCS_CATEGORY_ID_INCOMING_CALL | The iOS notification belongs to the "Incoming Call" category.
BLE_ANCS_CATEGORY_ID_MISSED_CALL | The iOS notification belongs to the "Missed Call" category.
BLE_ANCS_CATEGORY_ID_VOICE_MAIL | The iOS notification belongs to the "Voice Mail" category.
BLE_ANCS_CATEGORY_ID_SOCIAL | The iOS notification belongs to the "Social" category.
BLE_ANCS_CATEGORY_ID_SCHEDULE | The iOS notification belongs to the "Schedule" category.
BLE_ANCS_CATEGORY_ID_EMAIL | The iOS notification belongs to the "E-mail" category.
BLE_ANCS_CATEGORY_ID_NEWS | The iOS notification belongs to the "News" category.
BLE_ANCS_CATEGORY_ID_HEALTH_AND_FITNESS | The iOS notification belongs to the "Health and Fitness" category.
BLE_ANCS_CATEGORY_ID_BUSINESS_AND_FINANCE | The iOS notification belongs to the "Buisness and Finance" category.
BLE_ANCS_CATEGORY_ID_LOCATION | The iOS notification belongs to the "Location" category.
BLE_ANCS_CATEGORY_ID_ENTERTAINMENT | The iOS notification belongs to the "Entertainment" category.

enum ble_ancs_c_command_id_values_t

Control point command IDs that the Notification Consumer can send to the Notification Provider.

Enumerator
BLE_ANCS_COMMAND_ID_GET_NOTIF_ATTRIBUTES | Requests attributes to be sent from the NP to the NC for a given notification.
BLE_ANCS_COMMAND_ID_GET_APP_ATTRIBUTES | Requests attributes to be sent from the NP to the NC for a given iOS App.
BLE_ANCS_COMMAND_ID_GET_PERFORM_NOTIF_ACTION | Requests an action to be performed on a given notification, for example dismiss an alarm.

enum ble_ancs_c_evt_id_values_t

Event IDs for iOS notifications.

Enumerator
BLE_ANCS_EVENT_ID_NOTIFICATION_ADDED | The iOS notification was added.
BLE_ANCS_EVENT_ID_NOTIFICATION_MODIFIED | The iOS notification was modified.
BLE_ANCS_EVENT_ID_NOTIFICATION_REMOVED | The iOS notification was removed.

enum ble_ancs_c_evt_type_t

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

Enumerator
BLE_ANCS_C_EVT_DISCOVERY_COMPLETE | A successful connection has been established and the service was found on the connected peer.
BLE_ANCS_C_EVT_DISCOVERY_FAILED | It was not possible to discover the service or characteristics of the connected peer.
BLE_ANCS_C_EVT_NOTIF | An iOS notification was received on the notification source control point.
BLE_ANCS_C_EVT_INVALID_NOTIF | An iOS notification was received on the notification source control point, but the format is invalid.
BLE_ANCS_C_EVT_NOTIF_ATTRIBUTE | A received iOS notification attribute has been parsed.

enum ble_ancs_c_notif_attr_id_values_t

IDs for iOS notification attributes.

Enumerator
BLE_ANCS_NOTIF_ATTR_ID_APP_IDENTIFIER | Identifies that the attribute data is of an "App Identifier" type.
BLE_ANCS_NOTIF_ATTR_ID_TITLE | Identifies that the attribute data is a "Title".
BLE_ANCS_NOTIF_ATTR_ID_SUBTITLE | Identifies that the attribute data is a "Subtitle".
BLE_ANCS_NOTIF_ATTR_ID_MESSAGE | Identifies that the attribute data is a "Message".
BLE_ANCS_NOTIF_ATTR_ID_MESSAGE_SIZE | Identifies that the attribute data is a "Message Size".
BLE_ANCS_NOTIF_ATTR_ID_DATE | Identifies that the attribute data is a "Date".
BLE_ANCS_NOTIF_ATTR_ID_POSITIVE_ACTION_LABEL | The notification has a "Positive action" that can be executed associated with it.
BLE_ANCS_NOTIF_ATTR_ID_NEGATIVE_ACTION_LABEL | The notification has a "Negative action" that can be executed associated with it.

enum ble_ancs_c_parse_state_t

Parsing states for received iOS notification attributes.

Enumerator
COMMAND_ID_AND_NOTIF_UID | Parsing the command ID and the notification UID.
ATTR_ID | Parsing attribute ID.
ATTR_LEN1 | Parsing the LSB of the attribute length.
ATTR_LEN2 | Parsing the MSB of the attribute length.
ATTR_DATA | Parsing the attribute data.
DONE | Parsing is done.

## Function Documentation

uint32_t ble_ancs_c_attr_add | ( | ble_ancs_c_t * | p_ancs,
|  | const ble_ancs_c_notif_attr_id_values_t | id,
|  | uint8_t * | p_data,
|  | const uint16_t | len
| ) |  |

Function for registering attributes that will be requested if ble_ancs_c_request_attrs is called.

Parameters

  [in] | p_ancs | ANCS client instance on which the attribute will be registered.
  [in] | id | ID of the attribute that will be added.
  [in] | p_data | Pointer to a buffer where the data of the attribute can be stored.
  [in] | len | Length of the buffer where the data of the attribute can be stored.

Return values

  NRF_SUCCESS | If all operations were successful. Otherwise, an error code is returned.

uint32_t ble_ancs_c_data_source_notif_disable | ( | const ble_ancs_c_t * | p_ancs | ) |

Function for writing to the CCCD to disable data source notifications from the ANCS.

Parameters

  [in] | p_ancs | iOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.

Return values

  NRF_SUCCESS | If writing to the CCCD was successful. Otherwise, an error code is returned.

uint32_t ble_ancs_c_data_source_notif_enable | ( | const ble_ancs_c_t * | p_ancs | ) |

Function for writing to the CCCD to enable data source notifications from the ANCS.

Parameters

  [in] | p_ancs | iOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.

Return values

  NRF_SUCCESS | If writing to the CCCD was successful. Otherwise, an error code is returned.

uint32_t ble_ancs_c_handles_assign | ( | ble_ancs_c_t * | p_ancs,
|  | const uint16_t | conn_handle,
|  | const ble_ancs_c_service_t * | p_service
| ) |  |

Function for assigning handle to a this instance of ancs_c.

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

Parameters

  [in] | p_ancs | Pointer to the ANCS client structure instance to associate with these handles.
  [in] | conn_handle | Connection handle to associated with the given ANCS Instance.
  [in] | p_service | Attribute handles on the ANCS server that you want this ANCS client to interact with.

Return values

  NRF_SUCCESS | If the operation was successful.
  NRF_ERROR_NULL | If a p_ancs was a NULL pointer.

uint32_t ble_ancs_c_init | ( | ble_ancs_c_t * | p_ancs,
|  | const ble_ancs_c_init_t * | p_ancs_init
| ) |  |

Function for initializing the ANCS client.

Parameters

  [out] | p_ancs | ANCS client structure. This structure must be supplied by the application. It is initialized by this function and will later be used to identify this particular client instance.
  [in] | p_ancs_init | Information needed to initialize the client.

Return values

  NRF_SUCCESS | If the client was initialized successfully. Otherwise, an error code is returned.

uint32_t ble_ancs_c_notif_source_notif_disable | ( | const ble_ancs_c_t * | p_ancs | ) |

Function for writing to the CCCD to disable notifications from the ANCS.

Parameters

  [in] | p_ancs | iOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.

Return values

  NRF_SUCCESS | If writing to the CCCD was successful. Otherwise, an error code is returned.

uint32_t ble_ancs_c_notif_source_notif_enable | ( | const ble_ancs_c_t * | p_ancs | ) |

Function for writing to the CCCD to enable notifications from the Apple Notification Service.

Parameters

  [in] | p_ancs | iOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.

Return values

  NRF_SUCCESS | If writing to the CCCD was successful. Otherwise, an error code is returned.

void ble_ancs_c_on_ble_evt | ( | ble_ancs_c_t * | p_ancs,
|  | const ble_evt_t * | p_ble_evt
| ) |  |

Function for handling the application's BLE Stack events.

Handles all events from the BLE stack that are of interest to the ANCS client.

Parameters

  [in] | p_ancs | ANCS client structure.
  [in] | p_ble_evt | Event received from the BLE stack.

void ble_ancs_c_on_db_disc_evt | ( | ble_ancs_c_t * | p_ancs,
|  | ble_db_discovery_evt_t * | p_evt
| ) |  |

Function for handling events from the database discovery module.

This function will handle an event from the database discovery module, and determine if it relates to the discovery of ANCS at the peer. If so, it will call the application's event handler indicating that ANCS 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_ancs | Pointer to the ANCS client structure.
  [in] | p_evt | Pointer to the event received from the database discovery module.

uint32_t ble_ancs_c_request_attrs | ( | ble_ancs_c_t * | p_ancs,
|  | const ble_ancs_c_evt_notif_t * | p_notif
| ) |  |

Function for requesting attributes for a notification.

Parameters

  [in] | p_ancs | iOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
  [in] | p_notif | Pointer to the notification whose attributes will be requested from the Notification Provider.

Return values

  NRF_SUCCESS | If all operations were successful. Otherwise, an error code is returned.

## Variable Documentation

const ble_uuid128_t ble_ancs_base_uuid128

Apple Notification Center Service UUIDs.

Service UUID.

const ble_uuid128_t ble_ancs_cp_base_uuid128

Control point UUID.

const ble_uuid128_t ble_ancs_ds_base_uuid128

Data source UUID.

const ble_uuid128_t ble_ancs_ns_base_uuid128

Notification source UUID.