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

Apple Notification module - Disclaimer: This module (Apple Notification Center Service) can and will be changed at any time by either Apple or Nordic Semiconductor ASA. More...

Data Structures

struct  ble_ancs_c_evt_ios_notification_t
 
struct  ble_ancs_c_evt_notif_attribute_t
 
struct  ble_ancs_attr_list_t
 
struct  ble_ancs_c_evt_t
 Apple Notification Event structure. More...
 
struct  ble_ancs_c_s
 Apple Notification structure. This contains various status information for the client. More...
 
struct  ble_ancs_c_init_t
 Apple Notification init structure. This contains all options and data needed for initialization of the client. More...
 

Macros

#define ANCS_NB_OF_CHARACTERISTICS   5
 
#define ANCS_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_ANCS_INVALID_HANDLE   0xFF
 
#define ANCS_ATTRIBUTE_DATA_MAX   32 /*<< Maximium notification attribute data length. */
 
#define BLE_UUID_APPLE_NOTIFICATION_CENTER_SERVICE   0xf431 /*<< ANCS service UUID. */
 
#define BLE_UUID_ANCS_CONTROL_POINT_CHAR   0xd8f3 /*<< Control point UUID. */
 
#define BLE_UUID_ANCS_NOTIFICATION_SOURCE_CHAR   0x120d /*<< Notification source UUID. */
 
#define BLE_UUID_ANCS_DATA_SOURCE_CHAR   0xc6e9 /*<< Data source UUID. */
 
#define BLE_ANCS_EVENT_FLAG_SILENT   (1 << 0)
 Event flags for iOS notifications.
 
#define BLE_ANCS_EVENT_FLAG_IMPORTANT   (1 << 1)
 

Typedefs

typedef struct ble_ancs_c_s ble_ancs_c_t
 Apple Notification structure. This contains various status information for the client.
 
typedef void(* ble_ancs_c_evt_handler_t )(ble_ancs_c_evt_t *p_evt)
 Apple 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_IOS_NOTIFICATION,
  BLE_ANCS_C_EVT_NOTIF_ATTRIBUTE
}
 Event types that are passed from client to application on an event. More...
 
enum  ble_ancs_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.
 
enum  ble_ancs_event_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.
 
enum  ble_ancs_command_id_values_t {
  BLE_ANCS_COMMAND_ID_GET_NOTIFICATION_ATTRIBUTES,
  BLE_ANCS_COMMAND_ID_GET_APP_ATTRIBUTES
}
 Control point command IDs.
 
enum  ble_ancs_notification_attribute_id_values_t {
  BLE_ANCS_NOTIFICATION_ATTRIBUTE_ID_APP_IDENTIFIER,
  BLE_ANCS_NOTIFICATION_ATTRIBUTE_ID_TITLE,
  BLE_ANCS_NOTIFICATION_ATTRIBUTE_ID_SUBTITLE,
  BLE_ANCS_NOTIFICATION_ATTRIBUTE_ID_MESSAGE,
  BLE_ANCS_NOTIFICATION_ATTRIBUTE_ID_MESSAGE_SIZE,
  BLE_ANCS_NOTIFICATION_ATTRIBUTE_ID_DATE
}
 Notification attribute IDs.
 

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 event. 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_enable_notif_notification_source (const ble_ancs_c_t *p_ancs)
 Function for writing the to CCCD to enable notifications from the Apple Notification Service. More...
 
uint32_t ble_ancs_c_enable_notif_data_source (const ble_ancs_c_t *p_ancs)
 Function for writing to the CCCD to enable data souce notifications from the Apple Notification Service. More...
 
uint32_t ble_ancs_c_disable_notif_notification_source (const ble_ancs_c_t *p_ancs)
 Function for writing to the CCCD to notifications from the Apple Notification Service. More...
 
uint32_t ble_ancs_c_disable_notif_data_source (const ble_ancs_c_t *p_ancs)
 Function for writing to the CCCD to disable data source notifications from the Apple Notification Service. More...
 
uint32_t ble_ancs_get_notification_attributes (const ble_ancs_c_t *p_ancs, uint8_t *p_uid, uint8_t num_attr, ble_ancs_attr_list_t *p_attr)
 Function to send a Get Notification Attributes command to the ANCS control point. More...
 
uint32_t ble_ans_c_service_load (const ble_ancs_c_t *p_ancs)
 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 Apple Notification Center Client database from flash. 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 module - Disclaimer: This module (Apple Notification Center Service) can and will be changed at any time by either Apple or Nordic Semiconductor ASA.

This module implements the Apple Notification Center Service (ANCS) Client.

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

Macro Definition Documentation

#define ANCS_NB_OF_CHARACTERISTICS   5

Number of characteristics as defined by Apple Notification Service specification.

#define ANCS_NB_OF_SERVICES   1

Number of services supported in one master.

#define BLE_ANCS_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

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 characteristics of the server has been fetched.

BLE_ANCS_C_EVT_DISCOVER_FAILED 

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

BLE_ANCS_C_EVT_IOS_NOTIFICATION 

An iOS notification was received on the notification source control point.

BLE_ANCS_C_EVT_NOTIF_ATTRIBUTE 

A received iOS a received notification attribute has been completely parsed and reassembled.

Function Documentation

uint32_t ble_ancs_c_disable_notif_data_source ( const ble_ancs_c_t p_ancs)

Function for writing to the CCCD to disable data source notifications from the Apple Notification Service.

Parameters
[in]p_ancsApple 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_ancs_c_disable_notif_notification_source ( const ble_ancs_c_t p_ancs)

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

Parameters
[in]p_ancsApple 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_ancs_c_enable_notif_data_source ( const ble_ancs_c_t p_ancs)

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

Parameters
[in]p_ancsApple 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_ancs_c_enable_notif_notification_source ( const ble_ancs_c_t p_ancs)

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

Parameters
[in]p_ancsApple 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_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 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_ancs_initInformation needed to initialize the client.
Returns
NRF_SUCCESS on successful initialization of client, otherwise an error code.
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 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 event.

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

Parameters
[in]p_ancsANCS Client structure.
[in]p_handlePointer to ANCS device handle.
[in]p_dm_evtEvent received from the Bond Manager.
uint32_t ble_ancs_get_notification_attributes ( const ble_ancs_c_t p_ancs,
uint8_t *  p_uid,
uint8_t  num_attr,
ble_ancs_attr_list_t p_attr 
)

Function to send a Get Notification Attributes command to the ANCS control point.

Parameters
[in]p_ancsApple Notification structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
[in]p_uidUID of the notification.
[in]num_attrNumber of attributes.
[in]p_attrAttribute list.
Returns
NRF_SUCCESS on success, otherwise an error code.
uint32_t ble_ans_c_service_delete ( void  )

Function for deleting the Apple Notification Center 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_ancs_c_t p_ancs)

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_ancsApple Notification Center Service structure. This structure will have to be supplied by the application. It identifies the particular client instance to use.
Note
Currently the Apple Notification Center 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.

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.