libnotify/SPECIFICATION

FreeDesktop proposed notifications spec
=======================================

(c) 2004 Mike Hearn <mike@navi.cx>
    2004 Christian Hammond <chipx86@chipx86.com>

ChangeLog:

v0.1:
  * Initial version

---------------------------------------------------------------------

OVERVIEW

This is a draft standard for a desktop notifications service, through
which applications can generate passive popups (sometimes known as
"poptarts") to notify the user in an asynchronous manner of events.

This specification explicitly does not include other types of
notification presentation such as modal message boxes, window manager
decorations or window list annotations.

Example use cases include:

* Presence changes in IM programs: for instance, MSN Messenger on
  Windows pioneered the use of passive popups to indicate presence
  changes.

* New mail notification

* Low disk space/battery warnings



BASIC DESIGN

In order to ensure that multiple notifications can easily be
displayed at once, and to provide a convenient implementation, all
notifications are controlled by a single session-scoped service which
exposes a DBUS interface.

On startup, a conforming implementation should take the
"org.freedesktop.Notifications" service on the session bus. This
service will be referred to as the "notification server" or just "the
server" in this document. It can optionally be activated automatically
by the bus process, however this is not required and notification
server clients must not assume that it is available.

The server should implement the "org.freedesktop.Notifications" interface on
an object with the path "/org/freedesktop/Notifications". This is the
only interface required by this version of the specification.

A notification has the following components:

- A summary: This is a single line overview of the notification. For
  instance "You have mail" or "A friend has come online". It should
  generally not be longer than 40 characters (FIXME: is 40 sane?)

- An optional body: This is a multi-line body of text. Each line is a
  paragraph, server implementations are free to word wrap them as they
  see fit.

  The text may contain simple markup as specified in the MARKUP
  section below.

  If the body is omitted just the summary is displayed.

- An optional icon: See the ICONS/SOUNDS section below.

- An optional sound: See the ICONS/SOUNDS section below.

- An array of buttons. The buttons send a request message back to the
  notification client when clicked.

- A timeout: the time in milliseconds after which the notification
  should be hidden (FIXME: should this be a function of text length
  to accommodate different reading speeds?). If zero, the notification's
  timeout is dependent on the notification server's settings, and may vary
  for the type of notification.

  The timeout should be respected by implementations, but this is not
  required (this is for compatibility with KNotify).


Each notification displayed is allocated a unique ID by the server
(FIXME: should this be unique within a session, or just unique while
the notification is active?). This can be used to hide the
notification before the timeout is over. It can also be used to
atomically replace the notification with another: this allows you to
(for instance) modify the contents of a notification while it's
on-screen.


BACKWARDS COMPATIBILITY

Prior art in this area is basically just the KNotify system. This
specification strives to be compatible with KNotify, however there is
still some semantic mismatch. Clients should try and avoid making
assumptions about the presentation and abilities of the notification
server: the message content is the most important thing.


MARKUP

Description text may contain markup. The markup is XML-based, and consists
of a small subset of HTML along with a few additional tags.

The following tags should be supported by all implementations:

- <b>...</b> - Bold
- <i>...</i> - Italic
- <u>...</u> - Underline
- <a href="...">...</a> - Hyperlink

TODO: Add the rest of the tags! This is mostly a filler.


ICON ENCODING

Icons are sent through D-BUS either as an icon URI string, or as the raw
data. The determination should be automatically computed when sending or
receiving the icon.


ICON URIS:

Icon URIs must consist of one of the following forms:

- stock:<stockname>
- file://<hostname>/<path> [1]
- <path>

The supplied list of stock icon names should be represented by all
notification daemons. If an unknown stock icon name is specified, the
notification daemon is encouraged to provide a best-guess based on the
toolkit's own stock system, or simply ignore the icon.

The file URI must match the format provided by the freedesktop.org
File URI Specification <http://freedesktop.org/Standards/file-uri-spec>.


STOCK ICON NAMES:

- question
- info
- warning
- error
- critical

[Do we want any of the following?]
- camera
- printer
- email
- fax
- disk
- cfcard
- memstick
- sdcard


DBUS PROTOCOL

Write me!


REFERENCE

[1] http://freedesktop.org/Standards/file-uri-spec