nRF51 SDK - S130 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Apple Notification Service client

Apple Notification Center Service Client Module. More...

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_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_DISCOVER_COMPLETE,
  BLE_ANCS_C_EVT_DISCOVER_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...
 

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_device_manager_evt (ble_ancs_c_t *p_ancs, dm_handle_t const *p_handle, dm_event_t const *p_dm_evt)
 Function for handling the ANCS client Device Manager events. 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 (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 (const ble_ancs_c_evt_notif_t *p_notif)
 Function for requesting attributes for a notification. 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 and will 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:

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 countNotification UID
1 byte 1 byte 1 byte 1 byte 4 bytes

Enumeration Type Documentation

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.

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.

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.

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

Enumerator
BLE_ANCS_C_EVT_DISCOVER_COMPLETE 

A successful connection has been established and the service was found on the connected peer.

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

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.

Function Documentation

uint32_t ble_ancs_c_attr_add ( 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]idID of the attribute that will be added.
[in]p_dataPointer to a buffer where the data of the attribute can be stored.
[in]lenLength of the buffer where the data of the attribute can be stored.
Return values
NRF_SUCCESSIf 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_ancsiOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Return values
NRF_SUCCESSIf 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_ancsiOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Return values
NRF_SUCCESSIf writing to the CCCD was successful. Otherwise, an error code is returned.
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_ancsANCS 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_initInformation needed to initialize the client.
Return values
NRF_SUCCESSIf 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_ancsiOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Return values
NRF_SUCCESSIf 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_ancsiOS notification structure. This structure must be supplied by the application. It identifies the particular client instance to use.
Return values
NRF_SUCCESSIf 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_ancsANCS client structure.
[in]p_ble_evtEvent received from the BLE stack.
void ble_ancs_c_on_device_manager_evt ( ble_ancs_c_t p_ancs,
dm_handle_t const *  p_handle,
dm_event_t const *  p_dm_evt 
)

Function for handling the ANCS client Device Manager events.

This function handles all events from the Device Manager that are of interest to the ANCS client. When reconnecting to the existing central and creating new bonds for handling service discovery and writing to the Apple Notification Control Point, the Notification Provider will send new and unread iOS notifications again.

Parameters
[in]p_ancsANCS client structure.
[in]p_handlePointer to the ANCS device handle.
[in]p_dm_evtEvent received from the Device Manager.
uint32_t ble_ancs_c_request_attrs ( const ble_ancs_c_evt_notif_t p_notif)

Function for requesting attributes for a notification.

Parameters
[in]p_notifPointer to the notification whose attributes will be requested from the Notification Provider.
Return values
NRF_SUCCESSIf 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.