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." |
| Application Icon | The application icon. This is represented either as a path or a name in an icon theme. |
| Replaces ID | An optional ID of an existing notification that this notification is intended to replace. |
| Notification Type ID | An optional ID representing the notification type. See Notification Types. |
| Urgency Level | The urgency of the notification. See Urgency Levels. |
| 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. |
| Images | See Icons. |
| 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. |
| Hints | See Hints. |
| Expires |
A boolean flag indicating whether or not this notification should automatically expire. |
| Expiration Timeout |
The timeout time in seconds since the display of the notification at which the notification should automatically close. This is ignored if the expires flag is set to false. If zero, the notification's expiration time is dependent on the notification server's settings, and may vary for the type of notification. |
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.