Apple Notification Center Service (ANCS) Client

Note

Disclaimer: Nordic Semiconductor ASA can change this client implementation of the Apple Notification Center Service at any time. Apple can change the server implementations such as the ones found in iOS at any time, which may cause this client implementation to stop working.

The ANCS Client 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 that is acting as a server. For detailed information about the Apple Notification Center Service, see Apple Developer Documentation.

The term “notification” is used in two different meanings:

• An iOS notification is the data received from the Notification Provider.

• A GATT notification is a way to transfer data with Bluetooth® Low Energy.

In this module, iOS notifications are received through the GATT notifications. The full term (iOS notification or GATT notification) is used where required to avoid confusion.

The ANCS Client is used in the Bluetooth: Peripheral ANCS client sample.

Usage

Upon initializing the module, you must add the different iOS notification attributes you would like to receive for iOS notifications (see bt_ancs_register_attr()).

Once a connection is established with a central device, the module needs a service discovery to discover the ANCS server handles. If this succeeds, the handles for the ANCS server must be assigned to an ANCS client instance using the bt_ancs_handles_assign() function.

The application can now subscribe to iOS notifications with bt_ancs_subscribe_notification_source(). The notifications arrive through the callback function of the notification source subscription. Use bt_ancs_request_attrs() to request attributes for the notifications. The attributes arrive through the callback function of the data source subscription with a Command ID BT_ANCS_COMMAND_ID_GET_NOTIF_ATTRIBUTES. Use bt_ancs_request_app_attr() to request attributes of the app that issued the notifications. The app attributes arrive through the callback function of the data source subscription with a Command ID BT_ANCS_COMMAND_ID_GET_APP_ATTRIBUTES. Use bt_ancs_notification_action() to make the Notification Provider perform an action based on the provided notification.

API documentation

Header file: include/bluetooth/services/ancs_client.h

Source files: subsys/bluetooth/services/ancs_client.c and subsys/bluetooth/services/ancs_attr_parser.c and subsys/bluetooth/services/ancs_app_attr_get.c

group bt_ancs_client

Apple Notification Center Service Client module.

Defines

BT_UUID_ANCS_VAL

Apple Notification Center Service UUID.

BT_UUID_ANCS_NOTIFICATION_SOURCE_VAL

Notification Source Characteristic UUID.

BT_UUID_ANCS_CONTROL_POINT_VAL

Control Point Characteristic UUID.

BT_UUID_ANCS_DATA_SOURCE_VAL

Data Source Characteristic UUID.

BT_UUID_ANCS

BT_UUID_ANCS_NOTIFICATION_SOURCE

BT_UUID_ANCS_CONTROL_POINT

BT_UUID_ANCS_DATA_SOURCE

BT_ANCS_ATTR_DATA_MAX

Maximum data length of an iOS notification attribute.

BT_ANCS_CATEGORY_ID_COUNT

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

BT_ANCS_NOTIF_ATTR_COUNT

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

BT_ANCS_APP_ATTR_COUNT

Number of iOS application attributes: DisplayName.

BT_ANCS_EVT_ID_COUNT

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

BT_ANCS_NOTIF_DATA_LENGTH

Length of the iOS notification data.

BT_ANCS_EVENT_FLAG_SILENT

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

BT_ANCS_EVENT_FLAG_IMPORTANT

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

BT_ANCS_EVENT_FLAG_PREEXISTING

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

BT_ANCS_EVENT_FLAG_POSITIVE_ACTION

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

BT_ANCS_EVENT_FLAG_NEGATIVE_ACTION

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

Typedefs

typedef void (*bt_ancs_ns_notif_cb)(struct bt_ancs_client *ancs_c, int err, const struct bt_ancs_evt_notif *notif)

Notification Source notification callback function.

Param ancs_c

[in] ANCS client instance.

Param err

[in] 0 if the notification is valid. Otherwise, contains a (negative) error code.

Param notif

[in] iOS notification structure.

typedef void (*bt_ancs_ds_notif_cb)(struct bt_ancs_client *ancs_c, const struct bt_ancs_attr_response *response)

Data Source notification callback function.

Param ancs_c

[in] ANCS client instance.

Param response

[in] Attribute response structure.

typedef void (*bt_ancs_write_cb)(struct bt_ancs_client *ancs_c, uint8_t err)

Write response callback function.

Param ancs_c

[in] ANCS client instance.

Param err

[in] ATT error code.

Enums

enum bt_ancs_category_id_val

Category IDs for iOS notifications.

Values:

enumerator BT_ANCS_CATEGORY_ID_OTHER

The iOS notification belongs to the “Other” category.

enumerator BT_ANCS_CATEGORY_ID_INCOMING_CALL

The iOS notification belongs to the “Incoming Call” category.

enumerator BT_ANCS_CATEGORY_ID_MISSED_CALL

The iOS notification belongs to the “Missed Call” category.

enumerator BT_ANCS_CATEGORY_ID_VOICE_MAIL

The iOS notification belongs to the “Voice Mail” category.

enumerator BT_ANCS_CATEGORY_ID_SOCIAL

The iOS notification belongs to the “Social” category.

enumerator BT_ANCS_CATEGORY_ID_SCHEDULE

The iOS notification belongs to the “Schedule” category.

enumerator BT_ANCS_CATEGORY_ID_EMAIL

The iOS notification belongs to the “Email” category.

enumerator BT_ANCS_CATEGORY_ID_NEWS

The iOS notification belongs to the “News” category.

enumerator BT_ANCS_CATEGORY_ID_HEALTH_AND_FITNESS

The iOS notification belongs to the “Health and Fitness” category.

enumerator BT_ANCS_CATEGORY_ID_BUSINESS_AND_FINANCE

The iOS notification belongs to the “Business and Finance” category.

enumerator BT_ANCS_CATEGORY_ID_LOCATION

The iOS notification belongs to the “Location” category.

enumerator BT_ANCS_CATEGORY_ID_ENTERTAINMENT

The iOS notification belongs to the “Entertainment” category.

enum bt_ancs_evt_id_values

Event IDs for iOS notifications.

Values:

enumerator BT_ANCS_EVENT_ID_NOTIFICATION_ADDED

The iOS notification was added.

enumerator BT_ANCS_EVENT_ID_NOTIFICATION_MODIFIED

The iOS notification was modified.

enumerator BT_ANCS_EVENT_ID_NOTIFICATION_REMOVED

The iOS notification was removed.

enum bt_ancs_cmd_id_val

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

Values:

enumerator BT_ANCS_COMMAND_ID_GET_NOTIF_ATTRIBUTES

Requests attributes to be sent from the NP to the NC for a given notification.

enumerator BT_ANCS_COMMAND_ID_GET_APP_ATTRIBUTES

Requests attributes to be sent from the NP to the NC for a given iOS app.

enumerator BT_ANCS_COMMAND_ID_PERFORM_NOTIF_ACTION

Requests an action to be performed on a given notification. For example, dismiss an alarm.

enum bt_ancs_action_id_values

IDs for actions that can be performed for iOS notifications.

Values:

enumerator BT_ANCS_ACTION_ID_POSITIVE

Positive action.

enumerator BT_ANCS_ACTION_ID_NEGATIVE

Negative action.

enum bt_ancs_app_attr_id_val

App attribute ID values.

Currently, only one value is defined. However, the number of app attributes might increase. For this reason, they are stored in an enumeration.

Values:

enumerator BT_ANCS_APP_ATTR_ID_DISPLAY_NAME

Command used to get the display name for an app identifier.

enum bt_ancs_notif_attr_id_val

IDs for iOS notification attributes.

Values:

enumerator BT_ANCS_NOTIF_ATTR_ID_APP_IDENTIFIER

Identifies that the attribute data is of an “App Identifier” type.

enumerator BT_ANCS_NOTIF_ATTR_ID_TITLE

Identifies that the attribute data is a “Title”.

enumerator BT_ANCS_NOTIF_ATTR_ID_SUBTITLE

Identifies that the attribute data is a “Subtitle”.

enumerator BT_ANCS_NOTIF_ATTR_ID_MESSAGE

Identifies that the attribute data is a “Message”.

enumerator BT_ANCS_NOTIF_ATTR_ID_MESSAGE_SIZE

Identifies that the attribute data is a “Message Size”.

enumerator BT_ANCS_NOTIF_ATTR_ID_DATE

Identifies that the attribute data is a “Date”.

enumerator BT_ANCS_NOTIF_ATTR_ID_POSITIVE_ACTION_LABEL

The notification has a “Positive action” that can be executed associated with it.

enumerator BT_ANCS_NOTIF_ATTR_ID_NEGATIVE_ACTION_LABEL

The notification has a “Negative action” that can be executed associated with it.

enum bt_ancs_parse_state

Parsing states for received iOS notification and app attributes.

Values:

enumerator BT_ANCS_PARSE_STATE_COMMAND_ID

Parsing the command ID.

enumerator BT_ANCS_PARSE_STATE_NOTIF_UID

Parsing the notification UID.

enumerator BT_ANCS_PARSE_STATE_APP_ID

Parsing app ID.

enumerator BT_ANCS_PARSE_STATE_ATTR_ID

Parsing attribute ID.

enumerator BT_ANCS_PARSE_STATE_ATTR_LEN1

Parsing the LSB of the attribute length.

enumerator BT_ANCS_PARSE_STATE_ATTR_LEN2

Parsing the MSB of the attribute length.

enumerator BT_ANCS_PARSE_STATE_ATTR_DATA

Parsing the attribute data.

enumerator BT_ANCS_PARSE_STATE_ATTR_SKIP

Parsing is skipped for the rest of an attribute (or entire attribute).

enumerator BT_ANCS_PARSE_STATE_DONE

Parsing for one attribute is done.

Functions

int bt_ancs_client_init(struct bt_ancs_client *ancs_c)

Function for initializing the ANCS client.

Parameters

• ancs_c – [out] ANCS client instance. 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.

Return values

0 – If the client was initialized successfully. Otherwise, a (negative) error code is returned.

int bt_ancs_subscribe_notification_source(struct bt_ancs_client *ancs_c, bt_ancs_ns_notif_cb func)

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

Parameters

• ancs_c – [in] ANCS client instance.

• func – [in] Callback function for handling notification.

Return values

0 – If writing to the CCCD was successful. Otherwise, a (negative) error code is returned.

int bt_ancs_subscribe_data_source(struct bt_ancs_client *ancs_c, bt_ancs_ds_notif_cb func)

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

Parameters

• ancs_c – [in] ANCS client instance.

• func – [in] Callback function for handling notification.

Return values

0 – If writing to the CCCD was successful. Otherwise, a (negative) error code is returned.

int bt_ancs_unsubscribe_notification_source(struct bt_ancs_client *ancs_c)

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

Parameters

• ancs_c – [in] ANCS client instance

Return values

0 – If writing to the CCCD was successful. Otherwise, a (negative) error code is returned.

int bt_ancs_unsubscribe_data_source(struct bt_ancs_client *ancs_c)

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

Parameters

• ancs_c – [in] ANCS client instance.

Return values

0 – If writing to the CCCD was successful. Otherwise, a (negative) error code is returned.

int bt_ancs_register_attr(struct bt_ancs_client *ancs_c, const enum bt_ancs_notif_attr_id_val id, uint8_t *data, const uint16_t len)

Function for registering attributes that will be requested when bt_ancs_request_attrs is called.

Parameters

• ancs_c – [in] ANCS client instance on which the attribute is registered.

• id – [in] ID of the attribute that is added.

• data – [in] Pointer to the buffer where the data of the attribute can be stored.

• len – [in] Length of the buffer where the data of the attribute can be stored.

Return values

0 – If all operations are successful. Otherwise, a (negative) error code is returned.

int bt_ancs_register_app_attr(struct bt_ancs_client *ancs_c, const enum bt_ancs_app_attr_id_val id, uint8_t *data, const uint16_t len)

Function for registering attributes that will be requested when bt_ancs_request_app_attr is called.

Parameters

• ancs_c – [in] ANCS client instance on which the attribute is registered.

• id – [in] ID of the attribute that is added.

• data – [in] Pointer to the buffer where the data of the attribute can be stored.

• len – [in] Length of the buffer where the data of the attribute can be stored.

Return values

0 – If all operations are successful. Otherwise, a (negative) error code is returned.

int bt_ancs_request_attrs(struct bt_ancs_client *ancs_c, const struct bt_ancs_evt_notif *notif, bt_ancs_write_cb func)

Function for requesting attributes for a notification.

Parameters

• ancs_c – [in] ANCS client instance.

• notif – [in] Pointer to the notification whose attributes will be requested from the Notification Provider.

• func – [in] Callback function for handling NP write response.

Return values

0 – If all operations are successful. Otherwise, a (negative) error code is returned.

int bt_ancs_request_app_attr(struct bt_ancs_client *ancs_c, const uint8_t *app_id, uint32_t len, bt_ancs_write_cb func)

Function for requesting attributes for a given app.

Parameters

• ancs_c – [in] ANCS client instance.

• app_id – [in] App identifier of the app for which the app attributes are requested.

• len – [in] Length of the app identifier.

• func – [in] Callback function for handling NP write response.

Return values

0 – If all operations are successful. Otherwise, a (negative) error code is returned.

int bt_ancs_notification_action(struct bt_ancs_client *ancs_c, uint32_t uuid, enum bt_ancs_action_id_values action_id, bt_ancs_write_cb func)

Function for performing a notification action.

Parameters

• ancs_c – [in] ANCS client instance.

• uuid – [in] The UUID of the notification for which to perform the action.

• action_id – [in] Perform a positive or negative action.

• func – [in] Callback function for handling NP write response.

Return values

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ancs_handles_assign(struct bt_gatt_dm *dm, struct bt_ancs_client *ancs_c)

Function for assigning handles to ANCS client instance.

Call this function when a link has been established with a peer to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module.

Parameters

• dm – [in] Discovery object.

• ancs_c – [inout] ANCS client instance for associating the link.

Return values

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

struct bt_ancs_notif_flags

#include <ancs_client.h>

Flags for iOS notifications.

Public Members

uint8_t silent

If this flag is set, the notification has a low priority.

uint8_t important

If this flag is set, the notification has a high priority.

uint8_t pre_existing

If this flag is set, the notification is pre-existing.

uint8_t positive_action

If this flag is set, the notification has a positive action that can be taken.

uint8_t negative_action

If this flag is set, the notification has a negative action that can be taken.

struct bt_ancs_evt_notif

#include <ancs_client.h>

iOS notification structure.

Public Members

uint32_t notif_uid

Notification UID.

enum bt_ancs_evt_id_values evt_id

Whether the notification was added, removed, or modified.

struct bt_ancs_notif_flags evt_flags

Bitmask to signal whether a special condition applies to the notification. For example, “Silent” or “Important”.

enum bt_ancs_category_id_val category_id

Classification of the notification type. For example, email or location.

uint8_t category_count

Current number of active notifications for this category ID.

struct bt_ancs_attr

#include <ancs_client.h>

iOS attribute structure. This type is used for both notification attributes and app attributes.

Public Members

uint16_t attr_len

Length of the received attribute data.

uint32_t attr_id

Classification of the attribute type. For example, “Title” or “Date”.

uint8_t *attr_data

Pointer to where the memory is allocated for storing incoming attributes.

struct bt_ancs_attr_list

#include <ancs_client.h>

iOS notification attribute content requested by the application.

Public Members

bool get

Boolean to determine whether this attribute will be requested from the Notification Provider.

uint32_t attr_id

Attribute ID: AppIdentifier(0), Title(1), Subtitle(2), Message(3), MessageSize(4), Date(5), PositiveActionLabel(6), NegativeActionLabel(7).

uint16_t attr_len

Length of the attribute. If more data is received from the Notification Provider, all the data beyond this length is discarded.

uint8_t *attr_data

Pointer to where the memory is allocated for storing incoming attributes.

struct bt_ancs_attr_response

#include <ancs_client.h>

Attribute response structure.

Public Members

enum bt_ancs_cmd_id_val command_id

Command ID.

struct bt_ancs_attr attr

iOS notification attribute or app attribute, depending on the Command ID.

uint32_t notif_uid

Notification UID.

uint8_t app_id[32]

App identifier.

struct bt_ancs_parse_sm

#include <ancs_client.h>

Public Members

struct bt_ancs_attr_list *attr_list

The current list of attributes that are being parsed. This will point to either ancs_notif_attr_list or ancs_app_attr_list in struct bt_ancs_client.

uint32_t attr_count

Number of possible attributes. When parsing begins, it is set to either BT_ANCS_NOTIF_ATTR_COUNT or BT_ANCS_APP_ATTR_COUNT.

uint32_t expected_number_of_attrs

The number of attributes expected upon receiving attributes. Keeps track of when to stop reading incoming attributes.

enum bt_ancs_parse_state parse_state

ANCS notification attribute parsing state.

enum bt_ancs_cmd_id_val command_id

Variable to keep track of what command type is being parsed ( BT_ANCS_COMMAND_ID_GET_NOTIF_ATTRIBUTES or BT_ANCS_COMMAND_ID_GET_APP_ATTRIBUTES).

uint8_t *data_dest

Attribute that the parsed data is copied into.

uint16_t current_attr_index

Variable to keep track of the parsing progress, for the given attribute.

uint32_t current_app_id_index

Variable to keep track of the parsing progress, for the given app identifier.

struct bt_ancs_client

#include <ancs_client.h>

ANCS client instance, which contains various status information.

Public Members

struct bt_conn *conn

Connection object.

atomic_t state

Internal state.

uint16_t handle_cp

Handle of the Control Point Characteristic.

uint16_t handle_ns

Handle of the Notification Source Characteristic.

uint16_t handle_ns_ccc

Handle of the CCCD of the Notification Source Characteristic.

uint16_t handle_ds

Handle of the Data Source Characteristic.

uint16_t handle_ds_ccc

Handle of the CCCD of the Data Source Characteristic.

struct bt_gatt_write_params cp_write_params

GATT write parameters for Control Point Characteristic.

bt_ancs_write_cb cp_write_cb

Callback function for Control Point GATT write.

uint8_t cp_data[CONFIG_BT_ANCS_CLIENT_CP_BUFF_SIZE]

Data buffer for Control Point GATT write.

struct bt_gatt_subscribe_params ns_notif_params

GATT subscribe parameters for Notification Source Characteristic.

bt_ancs_ns_notif_cb ns_notif_cb

Callback function for Notification Source notification.

struct bt_gatt_subscribe_params ds_notif_params

GATT subscribe parameters for Data Source Characteristic.

bt_ancs_ds_notif_cb ds_notif_cb

Callback function for Data Source notification.

struct bt_ancs_attr_list ancs_notif_attr_list[8]

For all attributes: contains information about whether the attributes are to be requested upon attribute request, and the length and buffer of where to store attribute data.

struct bt_ancs_attr_list ancs_app_attr_list[1]

For all app attributes: contains information about whether the attributes are to be requested upon attribute request, and the length and buffer of where to store attribute data.

uint32_t number_of_requested_attr

The number of attributes that are to be requested when an iOS notification attribute request is made.

struct bt_ancs_parse_sm parse_info

Structure containing different information used to parse incoming attributes correctly (from data_source characteristic).

struct bt_ancs_attr_response attr_response

Allocate memory for the attribute response here.