This API will be implemented and initially used by Phone Alert Status and Alert Notification GATT profiles (server role). --- doc/alert-api.txt | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 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..79d65b8 --- /dev/null +++ b/doc/alert-api.txt @@ -0,0 +1,124 @@ +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 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 -- To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
