mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-26 05:34:23 +08:00
bbaccd71b0
This API will be implemented and initially used by Phone Alert Status and Alert Notification GATT profiles (server role).
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.
|