doc: Introduce Alert API

This API will be implemented and initially used by Phone Alert Status
and Alert Notification GATT profiles (server role).

diff --git a/Makefile.am b/Makefile.am
index c27eb01..470dbad 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -396,7 +396,7 @@ EXTRA_DIST += doc/manager-api.txt \
                doc/network-api.txt doc/input-api.txt doc/audio-api.txt \
                doc/control-api.txt doc/hfp-api.txt doc/health-api.txt \
                doc/sap-api.txt doc/media-api.txt doc/assigned-numbers.txt \
-               doc/supported-features.txt
+               doc/supported-features.txt doc/alert-api.txt
 
 AM_YFLAGS = -d
 

diff --git a/doc/alert-api.txt b/doc/alert-api.txt
new file mode 100644 (file)
index 0000000..bcaaaf3
--- /dev/null
+++ b/doc/alert-api.txt
@@ -0,0 +1,109 @@
+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.
+
+                       Description must not exceed 18 bytes when encoded in
+                       UTF-8 format, otherwise an error is returned. If there
+                       is no description, an empty string should 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().
+
+                       If there are more than 254 new alerts, count must be
+                       set to 255. 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.
+
+                       If there are more than 254 unread alerts, count must be
+                       set to 255.
+
+                       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 Release()
+
+                       Release this agent. At this point, it will not be used
+                       by BlueZ anymore and can be destroyed by the owner.