台灣繁中 Apple Notification Center Service (ANCS) Specification

Introduction

ANCS的目的是提供BLE藍牙裝置一個簡單而方便的方式去存取由iOS devices生成的Notifications。

ANCS的設計圍繞著三個主軸：簡單、效率、範圍可變性。因此，小至簡單的LEDs，大至功能強大的穿戴式裝置都可以發現這個服務是很有用的。

Dependencies

ANCS是沒有相依性且符合GATT規範的。配件當扮演GATT的client角色時，可以自由存取任何services並同時使用ANCS。

Endianness and String Encoding

除非遇到特殊情況，不然所有的數值資料在ANCS都會以little endian的方式傳遞。
除非遇到特殊情況，不然所有的字串資料在ANCS都會以UTF-8的編碼傳遞。

Terminology

在下面的文章中，都用如下的術語表示：
ANCS:The Apple Notification Center Service
NP:Notification Provider      ANCS的發佈者(iOS device)
NC:Notification Consumer   ANCS的接受者(藍牙 device)
iOS notifacation:所有顯示在iOS 通知中心的notification
GATT notification:所有透過GATT characteristic以非同步訊息傳送的notification

The Apple Notification Center Service

ANCS主要的service UUID是7905F431-B5CE-4E99-A40F-4B1E122D00D0。

只有一個ANCS的實體在NP上運作。由於iOS的天性，ANCS不保證總是可以被接受到。

因此，NC應該要找到可以偵測Service Changed狀態的characteristic，才可以隨時監控何時會發生潛在的ANCS發佈。

Service Characteristics

ANCS提供出三個characteristic以供操作

• Notification Source: UUID 9FBF120D-6301-42D9-8C58-25E699A21DBD (notifiable)
• Control Point: UUID 69D1D8F3-45E1-49A8-9821-9BBDFDAAD9D9 (writeable with response)
• Data Source: UUID 22EAC6E9-24D6-4BB5-BE44-B36ACE7C7BFB (notifiable)

在這三個之中，支援Notification Source是必須的。相反的，另外二個characteristic是非必要的。

Notification Source

這個characteristic會被呼叫，當NC被通知：

1,NP接到notification時

2,NP修改notification時

3,NP移除notification時

在NC訂閱這個characteristic時，GATT notification就可能被傳送。因此NC應該在訂閱之前，先確認自己可以正常接收和處理即將會收到的訊息。

GATT notifications透過Notification Source characteristic傳送時的格式如下圖2-1

Figure 2-1  The format of a GATT notification delivered through a Notification Source characteristic

透過Notification Source characteristic傳送的GATT notification包含下列資訊：

• EventID: 事件ID用來表示這是新增事件，修改事件，或是移除事件，其列舉值可以參考  “EventID Values.”
• EventFlags: 這是一個用來通知NC該iOS notification訊息的"重要性"的 bitmask。舉例來說，如果某個iOS notification被認為"很重要"，那NC可能會想要把它顯示到更顯眼的畫面，來讓使用者可以確實被提醒到。這個bits的列舉值被定義在 “EventFlags.”
• CategoryID: 這是一個數值，用來提供iOS notification可以被分類的Category。NP會盡量提供一個正確的category給每一個iOS notification。 這個field的列舉值被定義在“CategoryID Values.”
• CategoryCount: 這則iOS notification在category中最新的個數。舉例來說，如果現在已經有二封未讀郵件在郵箱中，這時又有一封新的郵件送來，那麼這時的CategoryCount就會是3。
• NotificationUID: A 32-bit numerical value that is the unique identifier (UID) for the iOS notification. This value can be used as a handle in commands sent to the Control Point characteristic to retrieve more information about the iOS notification.

iOS notification的生命週期可以被明確的依NP的Notification Source GATT notifications所產生的順序來解釋,
如圖2-2所示。

Figure 2-2  The lifetime of an iOS notification

Control Point and Data Source

An NC may want to retrieve more information about an iOS notification, including its contents. The retrieval of these attributes is performed through the Control Point and Data Source characteristics.

An NC can issue a request to retrieve more information about an iOS notification by writing specific commands to the Control Point characteristic. If the write to the Control Point characteristic is successful, the NP will promptly respond to the request through a stream of GATT notifications on the Data Source characteristic.

Get Notification Attributes

The Get Notification Attributes command allows an NC to retrieve the attributes of a specific iOS notification. The format of a Get Notification Attribute command is shown in Figure 2-3.

Figure 2-3  The format of a Get Notification Attribute command

A Get Notification Attributes command contains the following information:

• CommandID: Should be set to 0 (CommandIDGetNotificationAttributes).
• NotificationUID: The 32-bit numerical value representing the UID of the iOS notification for which the client wants information.
• AttributeIDs: A list of attributes that the NC wants to retrieve. Some attributes may need to be followed by a 16-bit length parameter that specifies the maximum number of bytes of the attribute the NC wants to retrieve.

The format of a response to a Get Notification Attributes command is shown in Figure 2-4.

Figure 2-4  The format of a response to a Get Notification Attributes command

A response to a Get Notification Attributes command contains the following information:

• CommandID: Set to 0 (CommandIDGetNotificationAttributes).
• NotificationUID: The 32-bit numerical value that is the UID of the iOS notification the following attributes correspond to.
• AttributeList: A list of AttributeIDs/16-bit Length/Attribute tuples. An attribute is always a string whose length in bytes is provided in the tuple, but which is not NULL-terminated. If a requested attribute is empty or missing for the iOS notification, its length is set to 0.

If the response is larger than the negotiated GATT Maximum Transmission Unit (MTU), it is split into multiple fragments by the NP. The NC must recompose the response by splicing each fragment. The response is complete when the complete tuples for each requested attribute has been received.

Get App Attributes

The Get App Attributes command allows an NC to retrieve attributes of a specific app installed on the NP. The format of the Get App Attributes command is shown in Figure 2-5.

Figure 2-5  The format of a Get App Attributes command

A Get App Attributes command contains the following information:

• CommandID: 應該設定成 1 (CommandIDGetAppAttributes).
• AppIdentifier: The string identifier of the app the client wants information about. This string must be NULL-terminated.
• AttributeIDs: A list of attributes the NC wants to retrieve.

The format of a response to a Get App Attributes command is shown in Figure 2-6.

Figure 2-6  The format of a response to a Get App Attributes command

A response to a Get App Attributes command contains the following information:

• CommandID: 設定為 1 (CommandIDGetAppAttributes).
• AppIdentifier: The string identifier of the app the following attributes correspond to. This string is NULL-terminated.
• AttributeList: A list of AttributeIDs/16-bit Length/Attribute tuples. An attribute is always a string whose length in bytes is provided in the tuple, but which is not NULL-terminated. If a requested attribute is empty or missing for the app, its length is set to 0.

As with a response to a Get Notification Attributes command, if the response to a Get App Attributes command is larger than the negotiated GATT Maximum Transmission Unit (MTU), it is split into multiple fragments by the NP. The NC must recompose the response by splicing each fragment. The response is complete when the complete tuples for each requested attribute has been received.

Sessions

一個ANCS session在NC訂閱NP上的Notification Source characteristic時，即被建立；
而在NC取消訂閱時，或NC斷線時，即被結束。

因為ANCS不是被設計為一個完全同步的服務，所以它不會持續追踪session的state。
因此，所有的identifiers跟所有的NC與NP之間的資料交換都是只有在特定的session中才有效。

當這個特定的session結束時，NC應該要移除所有的identifiers以及它先前抓取到的所有data。
當一個新的session被建立時，NP盡可能地通知NC目前系統上存在的所有iOS notifications。
NC可以用這些資訊來建一個model作為提示之用。

Attribute Fetching and Caching

It is strongly recommended for an NC to fetch attributes only as needed and possibly in response to user actions. For example, if an NC chooses to display active iOS notifications in a simple list, and to show only details about a specific iOS notification when selected by the user, then the retrieval of this iOS notification’s attributes can be triggered lazily.

During a session, it is strongly recommended that an NC build a cache of App Attributes for each app identifier it encounters. Building this cache allows the NC to avoid retrieving the same immutable App Attributes multiple times—saving time and preserving battery.

Error Codes

當寫入 Control Point characteristic時, NC 可能會接收到下列的 ANCS-specific 錯誤碼:

• Unknown command (0xA0): NP無法辨別這個 commandID.
• Invalid command (0xA1): 這個命令的格式錯誤.
• Invalid parameter (0xA2): 其中某個參數 (舉例來說, 像是NotificationUID) 並未指向NP中所存在的物件.

如果 NP 回應錯誤碼，那在Data Source characteristic上將不會產生任何 GATT notification來回應你所下的命令。

Example Diagrams

下列這兩張圖是兩個常見的NP與NC之間的互動。
圖2-7顯示當你要在NC上建立ANCS時的一個典型的命令與回應關係。
圖2-8是當你要在NC上顯示更多關於iOS notification的資訊時，典型的命令與回應關係。

Figure 2-7  Service setup example

Figure 2-8  Notification attribute retrieval example