mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-29 23:24:20 +08:00
110 lines
3.5 KiB
Plaintext
110 lines
3.5 KiB
Plaintext
|
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.
|