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¶
include/bluetooth/services/ancs_client.h
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.
- Parameters
ancs_c – [in] ANCS client instance.
err – [in] 0 if the notification is valid. Otherwise, contains a (negative) error code.
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.
- Parameters
ancs_c – [in] ANCS client instance.
response – [in] Attribute response structure.
-
typedef void (*
bt_ancs_write_cb
)(struct bt_ancs_client *ancs_c, uint8_t err)¶ Write response callback function.
- Parameters
ancs_c – [in] ANCS client instance.
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
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.
- Returns 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.
- Returns 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.
- Returns 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
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
-
uint8_t
-
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.
-
uint32_t
-
struct
bt_ancs_attr
¶ - #include <ancs_client.h>
iOS attribute structure. This type is used for both notification attributes and app 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.
-
bool
-
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.
-
enum bt_ancs_cmd_id_val
-
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_attr_list *
-
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.
-
struct bt_conn *
-