blob: fc427c8274c9cb879d2745c00e96a5ce3905accd [file] [log] [blame]
BlueZ D-Bus Alert API description
*********************************
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.Alert1
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.AlertAgent1
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.