[RFC BlueZ] doc: Introduce Alert API

[RFC BlueZ] doc: Introduce Alert API

[Anderson Lizardo]

This API will be implemented and initially used by Phone Alert Status
and Alert Notification GATT profiles (server role).
---
 doc/alert-api.txt |   95 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 doc/alert-api.txt

diff --git a/doc/alert-api.txt b/doc/alert-api.txt
new file mode 100644
index 0000000..209c4da
--- /dev/null
+++ b/doc/alert-api.txt
@@ -0,0 +1,95 @@
+BlueZ D-Bus Alert API description
+*********************************
+
+Copyright (C) 2012  Instituto Nokia de Tecnologia - INdT
+
+Introduction
+------------
+
+Currently, there are two different GATT server profiles that depend on
+receiving alerts or notifications from the platform: Phone Alert Status (PASP)
+and Alert Notification (ANP). Additionally, PASP is very specific to mobile
+phones, and also allow limited control to alerts (i.e. mute once, or switch to
+a silent mode).
+
+This document presents a unified API that allows to register, 
+
+Alert hierarchy
+===============
+
+Service		org.bluez
+Interface	org.bluez.Alert
+Object path	/org/bluez
+
+Methods		void RegisterAlert(string category)
+
+			Register a new alert category. This means the
+			application will be responsible for notifying BlueZ of
+			any alerts of that category, using the Alert() method.
+
+			Supported categories: generic, email, news, call,
+			missed_call, sms_mms, voice_mail, schedule,
+			instant_message, ringer, vibrate, display.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void RegisterAgent(string category, object agent)
+
+			Register a new agent for the alert category. The agent
+			object methods to be called depend on the category. The
+			currently supported category is "ringer", with methods
+			MuteOnce() and SetRingerMode().
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void NewAlert(string category, string description)
+
+			Notify BlueZ of a new alert for the given category. The
+			description can be sender name, called ID, title, or
+			other information specific to the alert. For ringer,
+			vibrate and display categories, valid descriptions are
+			"active" and "not active".
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void UnreadAlertCount(string category, uint16 count)
+
+			Some services (like SMS and e-mail) keep track of
+			number of unread items. This method allows to update
+			this counter, so peer devices can read it using Alert
+			Notification Profile.
+
+			Note that just calling NewAlert() will not implicitly
+			increment the unread count for a category. The
+			application must call this method to increase or
+			decrease the unread counter.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+Alert Agent hierarchy
+=====================
+
+Service		org.bluez
+Interface	org.bluez.AlertAgent
+Object path	freely definable
+
+Methods		void MuteOnce()
+
+			This method is only called if "ringer" alert category
+			is specified when registering the agent.
+
+			Mute the ringer once (e.g. during a incoming call). If
+			ringer is not active, does nothing.
+
+		void SetRingerMode(string mode)
+
+			This method is only called if "ringer" alert category
+			is specified when registering the agent.
+
+			Set ringer to the specified mode. If mode is "normal",
+			ringer is set to the default mode, as defined by the
+			current active profile. If mode is "silent", ringer
+			will not activate on incoming calls, until it is set
+			back to "normal" mode.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
-- 
1.7.9.5

Re: [RFC BlueZ] doc: Introduce Alert API

[Gustavo Padovan]

Hi Anderson,

* Anderson Lizardo <anderson.lizardo@openbossa.org> [2012-08-08 14:23:06 -0400]:

> This API will be implemented and initially used by Phone Alert Status
> and Alert Notification GATT profiles (server role).
> ---
>  doc/alert-api.txt |   95 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 95 insertions(+)
>  create mode 100644 doc/alert-api.txt
> 
> diff --git a/doc/alert-api.txt b/doc/alert-api.txt
> new file mode 100644
> index 0000000..209c4da
> --- /dev/null
> +++ b/doc/alert-api.txt
> @@ -0,0 +1,95 @@
> +BlueZ D-Bus Alert API description
> +*********************************
> +
> +Copyright (C) 2012  Instituto Nokia de Tecnologia - INdT
> +
> +Introduction
> +------------
> +
> +Currently, there are two different GATT server profiles that depend on
> +receiving alerts or notifications from the platform: Phone Alert Status (PASP)
> +and Alert Notification (ANP). Additionally, PASP is very specific to mobile
> +phones, and also allow limited control to alerts (i.e. mute once, or switch to
> +a silent mode).
> +
> +This document presents a unified API that allows to register, 

Is there some missing text here?

> +
> +Alert hierarchy
> +===============
> +
> +Service		org.bluez
> +Interface	org.bluez.Alert
> +Object path	/org/bluez
> +
> +Methods		void RegisterAlert(string category)
> +
> +			Register a new alert category. This means the
> +			application will be responsible for notifying BlueZ of
> +			any alerts of that category, using the Alert() method.
> +
> +			Supported categories: generic, email, news, call,
> +			missed_call, sms_mms, voice_mail, schedule,
> +			instant_message, ringer, vibrate, display.
> +
> +			Possible Errors: org.bluez.Error.InvalidArguments
> +
> +		void RegisterAgent(string category, object agent)
> +
> +			Register a new agent for the alert category. The agent
> +			object methods to be called depend on the category. The
> +			currently supported category is "ringer", with methods
> +			MuteOnce() and SetRingerMode().
> +
> +			Possible Errors: org.bluez.Error.InvalidArguments

If I got this right you RegisterAlert() and then RegisterAgent() in the
sequence, right? Why can't you merge both calls into one.

> +
> +		void NewAlert(string category, string description)
> +
> +			Notify BlueZ of a new alert for the given category. The
> +			description can be sender name, called ID, title, or
> +			other information specific to the alert. For ringer,
> +			vibrate and display categories, valid descriptions are
> +			"active" and "not active".

The way I understand it I see many NewAlert() calls happening almost at the
same time. Isn't possible to pass a dict with many {string category, string
description} inside?

> +
> +			Possible Errors: org.bluez.Error.InvalidArguments
> +
> +		void UnreadAlertCount(string category, uint16 count)
> +
> +			Some services (like SMS and e-mail) keep track of
> +			number of unread items. This method allows to update
> +			this counter, so peer devices can read it using Alert
> +			Notification Profile.
> +
> +			Note that just calling NewAlert() will not implicitly
> +			increment the unread count for a category. The
> +			application must call this method to increase or
> +			decrease the unread counter.

Is there a good reason for not increment the count on NewAlert()?

	Gustavo

Re: [RFC BlueZ] doc: Introduce Alert API

[Anderson Lizardo]

Hi Gustavo,

On Wed, Aug 15, 2012 at 12:27 AM, Gustavo Padovan <gustavo@padovan.org> wrote:
>> +Currently, there are two different GATT server profiles that depend on
>> +receiving alerts or notifications from the platform: Phone Alert Status (PASP)
>> +and Alert Notification (ANP). Additionally, PASP is very specific to mobile
>> +phones, and also allow limited control to alerts (i.e. mute once, or switch to
>> +a silent mode).
>> +
>> +This document presents a unified API that allows to register,
>
> Is there some missing text here?

Yes, I will fill the missing text on next revision. I also have minor
fixes to the alert categories.

>> +
>> +Alert hierarchy
>> +===============
>> +
>> +Service              org.bluez
>> +Interface    org.bluez.Alert
>> +Object path  /org/bluez
>> +
>> +Methods              void RegisterAlert(string category)
>> +
>> +                     Register a new alert category. This means the
>> +                     application will be responsible for notifying BlueZ of
>> +                     any alerts of that category, using the Alert() method.
>> +
>> +                     Supported categories: generic, email, news, call,
>> +                     missed_call, sms_mms, voice_mail, schedule,
>> +                     instant_message, ringer, vibrate, display.
>> +
>> +                     Possible Errors: org.bluez.Error.InvalidArguments
>> +
>> +             void RegisterAgent(string category, object agent)
>> +
>> +                     Register a new agent for the alert category. The agent
>> +                     object methods to be called depend on the category. The
>> +                     currently supported category is "ringer", with methods
>> +                     MuteOnce() and SetRingerMode().
>> +
>> +                     Possible Errors: org.bluez.Error.InvalidArguments
>
> If I got this right you RegisterAlert() and then RegisterAgent() in the
> sequence, right? Why can't you merge both calls into one.

Originally, the agent was only necessary for the "ringer" category.
But after further thinking, looks like we can use it to update the
"new alert" and "unread alert" counts necessary for ANP. I will
prepare an updated document and send ASAP.

>> +
>> +             void NewAlert(string category, string description)
>> +
>> +                     Notify BlueZ of a new alert for the given category. The
>> +                     description can be sender name, called ID, title, or
>> +                     other information specific to the alert. For ringer,
>> +                     vibrate and display categories, valid descriptions are
>> +                     "active" and "not active".
>
> The way I understand it I see many NewAlert() calls happening almost at the
> same time. Isn't possible to pass a dict with many {string category, string
> description} inside?

It is not clear from the description above (I will improve it), but
for categories like "email" that can have many messages received after
a sync, only a single NewAlert() call is made. The description is for
the last e-mail sent. So the event is actually a single one: "you got
N e-mails, and the sender for the last one is ...". The same applies
to any alerts which have multiple items.

>
>> +
>> +                     Possible Errors: org.bluez.Error.InvalidArguments
>> +
>> +             void UnreadAlertCount(string category, uint16 count)
>> +
>> +                     Some services (like SMS and e-mail) keep track of
>> +                     number of unread items. This method allows to update
>> +                     this counter, so peer devices can read it using Alert
>> +                     Notification Profile.
>> +
>> +                     Note that just calling NewAlert() will not implicitly
>> +                     increment the unread count for a category. The
>> +                     application must call this method to increase or
>> +                     decrease the unread counter.
>
> Is there a good reason for not increment the count on NewAlert()?

There are two counts supported by the ANP profile: "Unread Alert
count" and "New Alert count". I'll try to explain here, but I
suggesting reading sections 1.7.2, 1.7.3, 4.1.2 and 4.1.3 from
ANS_SPEC_V10.pdf. These counts are per category.

Unread Alert count is only useful to some categories, like SMS and
e-mail, that have the concept of "unread message". It may
increase/decrease depending on user interaction with the host UI (e.g.
marking messages as read/unread, deleting messages etc.)

New Alert count is used to keep track of how many alerts are not yet
acknowledged by the user. It is also applicable to SMS/email, and all
other categories. E.g. two calendar events on the same day, and none
of them were opened by the user, will increase this count by two.

As mentioned above, we can use the zgent to have better tracking of
these counts. This would avoid the need for this method, and instead
BlueZ could request for the up-to-date alert counts from the e-mail
application (for example). I will send soon a v2 of this document.


Thanks for your comments!

Best Regards,
-- 
Anderson Lizardo
Instituto Nokia de Tecnologia - INdT
Manaus - Brazil

[RFC v2 BlueZ] doc: Introduce Alert API

[Anderson Lizardo]

This API will be implemented and initially used by Phone Alert Status
and Alert Notification GATT profiles (server role).
---
 doc/alert-api.txt |  119 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 doc/alert-api.txt

diff --git a/doc/alert-api.txt b/doc/alert-api.txt
new file mode 100644
index 0000000..4ead9e8
--- /dev/null
+++ b/doc/alert-api.txt
@@ -0,0 +1,119 @@
+BlueZ D-Bus Alert API description
+*********************************
+
+Copyright (C) 2012  Instituto Nokia de Tecnologia - INdT
+
+Introduction
+------------
+
+Currently, there are two different GATT server profiles that depend on
+receiving alerts or notifications from the platform: Phone Alert Status (PASP)
+and Alert Notification (ANP). PASP is very specific to mobile phones, and also
+allows limited control to alerts (i.e. mute once or switch to a silent mode).
+
+This document presents a unified API that allows to register and notify alerts,
+and to control some alerts (using the provided agent object).
+
+
+Alert hierarchy
+===============
+
+Service		org.bluez
+Interface	org.bluez.Alert
+Object path	/org/bluez
+
+Methods		void RegisterAlert(string category, object agent)
+
+			Register a new alert category and an agent for it. This
+			means the application will be responsible for notifying
+			BlueZ of any alerts of that category, using the
+			NewAlert() method.
+
+			Supported ANP categories: simple, email, news, call,
+				missed_call, sms_mms, voice_mail, schedule,
+				high_priority, instant_message
+			Supported PASP categories: ringer, vibrate, display
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void NewAlert(string category, uint16 count, string description)
+
+			Notify BlueZ of new alert(s) for the given category. The
+			description is relative to the last received alert and
+			can be sender name, caller ID, title, or other
+			information specific to the category.
+
+			For ringer, vibrate and display categories, valid
+			descriptions are "active" and "not active". Alerts from
+			ringer category also accept "enabled" and "disabled",
+			depending on whether ringer is in silent mode or not.
+
+			If there is no description, an empty string can be
+			used.
+
+			The count argument contains the number of alerts not
+			yet acknowledged by the user on the UI. To save D-Bus
+			traffic, events that may generate multiple alerts at
+			the same time (like email, sms, news) should trigger a
+			single NewAlert().
+
+			PASP alerts should always set count to 1.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void UnreadAlert(string category, uint16 count)
+
+			Some services (like SMS and e-mail) keep track of
+			number of unread items. This method allows to update
+			this counter, so peer devices can be notified using
+			Alert Notification Profile.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+Alert Agent hierarchy
+=====================
+
+Service		org.bluez
+Interface	org.bluez.AlertAgent
+Object path	freely definable
+
+Methods		void MuteOnce()
+
+			This method is only called if "ringer" alert category
+			is specified when registering the agent.
+
+			Mute the ringer once (e.g. during a incoming call). If
+			ringer is not active, does nothing.
+
+		void SetRinger(string mode)
+
+			This method is only called if "ringer" alert category
+			is specified when registering the agent.
+
+			Set ringer to the specified mode. If mode is "enabled",
+			ringer is set to the default mode, as defined by the
+			current active profile. If mode is "disabled", ringer
+			will not activate on incoming calls, until it is set
+			back to "enabled" mode.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void Suspend(string category)
+
+			Suspend alerts for this category, which means that
+			new/unread alerts should not be reported to save D-Bus
+			traffic. This means that no client has enabled this
+			alert yet.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void Resume(string category)
+
+			Resume alerts for this category.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		void Release()
+
+			Release this agent. At this point, it will be not used
+			by BlueZ anymore and can be destroyed by the owner.
-- 
1.7.9.5