--- /dev/null
+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.