doc/alert-api.txt

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.