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 D-BUS 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:

Table 1. Notification Components

Component

Description

Application Name

This is the optional name of the application sending the notification.
This should be the application's formal name, rather than some sort
of ID. An example would be "FredApp E-Mail Client," rather than
"fredapp-email-client."

Replaces ID

An optional ID of an existing notification that this
notification is intended to replace.

Notification Icon

The notification icon. This is represented either as a URI
(file:// is the only URI schema supported right now) or a name in
a freedesktop.org-compliant icon theme (not a GTK+ stock ID).

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, though this is not a requirement,
and server implementations should word wrap if necessary. The summary
must be encoded using UTF-8.

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 body may contain simple markup as specified in
Markup. It must be encoded using UTF-8.

If the body is omitted, just the summary is displayed.

Actions

The actions send a request message back to the notification client
when invoked. This functionality may not be implemented by the
notification server, conforming clients should check if it is available
before using it (see the GetCapabilities message in
Protocol). An implementation is free to ignore any
requested by the client. As an example one possible rendering of
actions would be as buttons in the notification popup.

Actions are sent over as a list of pairs. Each even element in the
list (starting at index 0) represents the identifier for the action.
Each odd element in the list is the localized string that will be
displayed to the user.

The default action (usually invoked my clicking the notification)
should have a key named "default". The name can
be anything, though implementations are free not to display it.

Beyond the core protocol is the hints table. A couple of core
elements have been moved to hints mostly because in a huge number
of cases their default values would be sufficent. The elements moved
to hints are:

Elements Moved to Hints

Element: Category ID

Description: An optional ID representing the type of notification (the name
has been changed from Notification Type ID in pervious versions).
See Categories.

Element: Urgency Level

Description: The urgency of the notification. See
Urgency Levels. (Defaults to 1 - Normal)

Element: Icon Data

Description: Instead of overloading the icon field we now have an icon_data
field that is used when icon is blank.

Expiration Timeout

The timeout time in milliseconds since the display of the notification
at which the notification should automatically close.

If -1, the notification's expiration time is dependent on the
notification server's settings, and may vary for the type of
notification.

If 0, the notification never expires.

Each notification displayed is allocated a unique ID by the server.
This is unique within the session. While the notification server is
running, the ID will not be recycled unless the capacity of a uint32 is
exceeded.

This can be used to hide the notification before the expiration timeout
is reached. 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.