| Current File : //proc/self/root/kunden/usr/share/doc/libnotify/spec/notification-spec.html |
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Desktop Notifications Specification</title><link rel="stylesheet" type="text/css" href="docbook.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body><div class="article"><div class="titlepage"><div><div><h2 class="title"><a id="index"></a>Desktop Notifications Specification</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Mike</span> <span class="surname">Hearn</span></h3><div class="affiliation"><div class="address"><p><br />
<code class="email"><<a class="email" href="mailto:mike@navi.cx">mike@navi.cx</a>></code><br />
</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Christian</span> <span class="surname">Hammond</span></h3><div class="affiliation"><div class="address"><p><br />
<code class="email"><<a class="email" href="mailto:chipx86@chipx86.com">chipx86@chipx86.com</a>></code><br />
</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">William Jon</span> <span class="surname">McCann</span></h3><div class="affiliation"><div class="address"><p><br />
<code class="email"><<a class="email" href="mailto:jmccann@redhat.com">jmccann@redhat.com</a>></code><br />
</p></div></div></div></div></div><div><p class="releaseinfo">Version 1.2</p></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#introduction">Introduction</a></span></dt><dt><span class="sect1"><a href="#basic-design">Basic Design</a></span></dt><dt><span class="sect1"><a href="#backwards-compat">Backwards Compatibility</a></span></dt><dt><span class="sect1"><a href="#markup">Markup</a></span></dt><dd><dl><dt><span class="sect2"><a href="#hyperlinks">Hyperlinks</a></span></dt><dt><span class="sect2"><a href="#images">Images</a></span></dt></dl></dd><dt><span class="sect1"><a href="#icons-and-images">Icons and Images</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id-1.6.4">Priorities</a></span></dt><dt><span class="sect2"><a href="#icons-and-images-formats">Formats</a></span></dt></dl></dd><dt><span class="sect1"><a href="#categories">Categories</a></span></dt><dt><span class="sect1"><a href="#urgency-levels">Urgency Levels</a></span></dt><dt><span class="sect1"><a href="#hints">Hints</a></span></dt><dt><span class="sect1"><a href="#protocol">D-BUS Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="#commands">Message commands</a></span></dt><dt><span class="sect2"><a href="#signals">Signals</a></span></dt></dl></dd></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="introduction"></a>Introduction</h2></div></div></div><p>
This is a draft standard for a desktop notifications service,
through which applications can generate passive popups to notify
the user in an asynchronous manner of events.
</p><p>
This specification explicitly does not include other types of
notification presentation such as modal message boxes, window manager
decorations or window list annotations.
</p><p>
Example use cases include:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Messages from chat programs</p></li><li class="listitem"><p>Scheduled alarm</p></li><li class="listitem"><p>Completed file transfer</p></li><li class="listitem"><p>New mail notification</p></li><li class="listitem"><p>Low disk space/battery warnings</p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="basic-design"></a>Basic Design</h2></div></div></div><p>
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.
</p><p>
On startup, a conforming implementation should take the
<code class="literal">org.freedesktop.Notifications</code> 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.
</p><p>
The server should implement the
<code class="literal">org.freedesktop.Notifications</code> interface on
an object with the path <code class="literal">"/org/freedesktop/Notifications"</code>.
This is the only interface required by this version of the specification.
</p><p>
A notification has the following components:
</p><div class="table"><a id="id-1.3.6"></a><p class="title"><strong>Table 1. Notification Components</strong></p><div class="table-contents"><table class="table" summary="Notification Components" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Component</th><th>Description</th></tr></thead><tbody valign="top"><tr><td valign="top">Application Name</td><td valign="top">
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."
</td></tr><tr><td valign="top">Replaces ID</td><td valign="top">
An optional ID of an existing notification that this
notification is intended to replace.
</td></tr><tr><td valign="top">Notification Icon</td><td valign="top">
The notification icon. See <a class="xref" href="#icons-and-images-formats" title="Formats">Icons and Images Formats</a>.
</td></tr><tr><td valign="top">Summary</td><td valign="top">
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.
</td></tr><tr><td valign="top">Body</td><td valign="top">
<p>
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.
</p>
<p>
The body may contain simple markup as specified in
<a class="xref" href="#markup" title="Markup">Markup</a>. It must be encoded using UTF-8.
</p>
<p>
If the body is omitted, just the summary is displayed.
</p>
</td></tr><tr><td valign="top">Actions</td><td valign="top">
<p>
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
<a class="xref" href="#protocol" title="D-BUS Protocol">Protocol</a>). 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.
</p>
<p>
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.
</p>
<p>
The default action (usually invoked my clicking the notification)
should have a key named <code class="literal">"default"</code>. The name can
be anything, though implementations are free not to display it.
</p>
</td></tr><tr><td valign="top">Hints</td><td valign="top">
<p>
Hints are a way to provide extra data to a notification server that
the server may be able to make use of.
</p>
<p>See <a class="xref" href="#hints" title="Hints">Hints</a> for a list of available hints.</p>
</td></tr><tr><td valign="top">Expiration Timeout</td><td valign="top">
<p>
The timeout time in milliseconds since the display of the notification
at which the notification should automatically close.
</p>
<p>
If -1, the notification's expiration time is dependent on the
notification server's settings, and may vary for the type of
notification.
</p>
<p>
If 0, the notification never expires.
</p>
</td></tr></tbody></table></div></div><br class="table-break" /><p>
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.
</p><p>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="backwards-compat"></a>Backwards Compatibility</h2></div></div></div><p>
Clients should try and avoid making assumptions about the presentation and
abilities of the notification server. The message content is the most
important thing.
</p><p>
Clients can check with the server what capabilities are supported
using the <code class="literal">GetCapabilities</code> message. See
<a class="xref" href="#protocol" title="D-BUS Protocol">Protocol</a>.
</p><p>
If a client requires a response from a passive popup, it should be
coded such that a non-focus-stealing message box can be used in the
case that the notification server does not support this feature.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="markup"></a>Markup</h2></div></div></div><p>
Body text may contain markup. The markup is XML-based, and consists
of a small subset of HTML along with a few additional tags.
</p><p>
The following tags should be supported by the notification server.
Though it is optional, it is recommended. Notification servers that do
not support these tags should filter them out.
</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /></colgroup><tbody valign="top"><tr><td valign="top">
<code class="sgmltag-starttag"><b></code> ...
<code class="sgmltag-endtag"></b></code>
</td><td valign="top">Bold</td></tr><tr><td valign="top">
<code class="sgmltag-starttag"><i></code> ...
<code class="sgmltag-endtag"></i></code>
</td><td valign="top">Italic</td></tr><tr><td valign="top">
<code class="sgmltag-starttag"><u></code> ...
<code class="sgmltag-endtag"></u></code>
</td><td valign="top">Underline</td></tr><tr><td valign="top">
<code class="sgmltag-starttag"><a href="..."></code> ...
<code class="sgmltag-endtag"></a></code>
</td><td valign="top">Hyperlink</td></tr><tr><td valign="top">
<code class="sgmltag-emptytag"><img src="..." alt="..."/></code>
</td><td valign="top">Image</td></tr></tbody></table></div><p>
A full-blown HTML implementation is not required of this spec, and
notifications should never take advantage of tags that are not listed
above. As notifications are not a substitute for web browsers or complex
dialogs, advanced layout is not necessary, and may in fact limit the
number of systems that notification services can run on, due to memory
usage and screen space. Such examples are PDAs, certain cell phones, and
slow PCs or laptops with little memory.
</p><p>
For the same reason, a full XML or XHTML implementation using XSLT or
CSS stylesheets is not part of this specification. Information that
must be presented in a more complex form should use an application-specific
dialog, a web browser, or some other display mechanism.
</p><p>
The tags specified above mark up the content in a way that allows them
to be stripped out on some implementations without impacting the actual
content.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="hyperlinks"></a>Hyperlinks</h3></div></div></div><p>
Hyperlinks allow for linking one or more words to a URI. There is no
requirement to allow for images to be linked, and it is highly suggested
that implementations do not allow this, as there is no clean-looking,
standard visual indicator for a hyperlinked image.
</p><p>
Hyperlinked text should appear in the standard blue underline format.
</p><p>
Hyperlinks cannot function as a replacement for actions. They are
used to link to local directories or remote sites using standard URI
schemes.
</p><p>
Implementations are not required to support hyperlinks.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="images"></a>Images</h3></div></div></div><p>
Images may be placed in the notification, but this should be done with
caution. The image should never exceed 200x100, but this should be thought
of as a maximum size. Images should always have alternative text
provided through the <code class="literal">alt="..."</code> attribute.
</p><p>
Image data cannot be embedded in the message itself. Images referenced
must always be local files.
</p><p>
Implementations are not required to support images.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="icons-and-images"></a>Icons and Images</h2></div></div></div><p>
A notification can optionally have an associated icon and/or image.
</p><p>
The icon is defined by the "app_icon" parameter.
The image can be defined by the "image-path", the "image-data" hint or the
deprecated "icon_data" hint.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="id-1.6.4"></a>Priorities</h3></div></div></div><p>
An implementation which only displays one image or icon must choose which one
to display using the following order:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>"image-data"</p></li><li class="listitem"><p>"image-path"</p></li><li class="listitem"><p>app_icon parameter</p></li><li class="listitem"><p>for compatibility reason, "icon_data"</p></li></ol></div><p>
</p><p>
An implementation which can display both the image and icon must show the
icon from the "app_icon" parameter and choose which image to display using
the following order:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>"image-data"</p></li><li class="listitem"><p>"image-path"</p></li><li class="listitem"><p>for compatibility reason, "icon_data"</p></li></ol></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="icons-and-images-formats"></a>Formats</h3></div></div></div><p>
The "image-data" and "icon_data" hints should be a DBus structure
of signature (iiibiiay). The components of this structure are as follows:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>width (i): Width of image in pixels</p></li><li class="listitem"><p>height (i): Height of image in pixels</p></li><li class="listitem"><p>rowstride (i): Distance in bytes between row starts</p></li><li class="listitem"><p>has_alpha (b): Whether the image has an alpha channel</p></li><li class="listitem"><p>bits_per_sample (i): Must always be 8</p></li><li class="listitem"><p>channels (i): If has_alpha is TRUE, must be 4, otherwise 3</p></li><li class="listitem"><p>data (ay): The image data, in RGB byte order</p></li></ol></div><p>
This image format is derived from <a class="ulink" href="http://developer.gnome.org/gdk-pixbuf/stable/" target="_top">gdk-pixbuf</a>.
</p><p>
The "app_icon" parameter and "image-path" hint should be either an 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).
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="categories"></a>Categories</h2></div></div></div><p>
Notifications can optionally have a type indicator. Although neither
client or nor server must support this, some may choose to. Those servers
implementing categories may use them to intelligently display
the notification in a certain way, or group notifications of similar
types.
</p><p>
Categories are in
<code class="literal"><em class="replaceable"><code>class.specific</code></em></code> form.
<code class="literal">class</code> specifies the generic type of notification, and
<code class="literal">specific</code> specifies the more specific type of
notification.
</p><p>
If a specific type of notification does not exist for your notification,
but the generic kind does, a notification of type
<code class="literal"><em class="replaceable"><code>class</code></em></code> is acceptable.
</p><p>
Third parties, when defining their own categories, should discuss
the possibility of standardizing on the hint with other parties, preferably
in a place such as the
<a class="ulink" href="http://freedesktop.org/mailman/listinfo/xdg" target="_top">xdg</a>
mailing list at
<a class="ulink" href="http://freedesktop.org/" target="_top">freedesktop.org</a>. If it
warrants a standard, it will be added to the table above. If no
consensus is reached, the category should be in the form of
"<code class="literal">x-<em class="replaceable"><code>vendor</code></em>.<em class="replaceable"><code>class</code></em>.<em class="replaceable"><code>name</code></em></code>."
</p><p>
The following table lists standard notifications as defined by this spec.
More will be added in time.
</p><div class="table"><a id="id-1.7.7"></a><p class="title"><strong>Table 2. Categories</strong></p><div class="table-contents"><table class="table" summary="Categories" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="literal">"device"</code></td><td valign="top">
A generic device-related notification that doesn't fit into
any other category.
</td></tr><tr><td valign="top"><code class="literal">"device.added"</code></td><td valign="top">A device, such as a USB device, was added to the system.</td></tr><tr><td valign="top"><code class="literal">"device.error"</code></td><td valign="top">A device had some kind of error.</td></tr><tr><td valign="top"><code class="literal">"device.removed"</code></td><td valign="top">
A device, such as a USB device, was removed from the system.
</td></tr><tr><td valign="top"><code class="literal">"email"</code></td><td valign="top">
A generic e-mail-related notification that doesn't fit into any
other category.
</td></tr><tr><td valign="top"><code class="literal">"email.arrived"</code></td><td valign="top">A new e-mail notification.</td></tr><tr><td valign="top"><code class="literal">"email.bounced"</code></td><td valign="top">A notification stating that an e-mail has bounced.</td></tr><tr><td valign="top"><code class="literal">"im"</code></td><td valign="top">
A generic instant message-related notification that doesn't fit
into any other category.
</td></tr><tr><td valign="top"><code class="literal">"im.error"</code></td><td valign="top">An instant message error notification.</td></tr><tr><td valign="top"><code class="literal">"im.received"</code></td><td valign="top">A received instant message notification.</td></tr><tr><td valign="top"><code class="literal">"network"</code></td><td valign="top">
A generic network notification that doesn't fit into any other
category.
</td></tr><tr><td valign="top"><code class="literal">"network.connected"</code></td><td valign="top">
A network connection notification, such as successful sign-on to a
network service. This should not be confused with
<code class="literal">device.added</code> for new network devices.
</td></tr><tr><td valign="top"><code class="literal">"network.disconnected"</code></td><td valign="top">
A network disconnected notification. This should not be confused with
<code class="literal">device.removed</code> for disconnected network devices.
</td></tr><tr><td valign="top"><code class="literal">"network.error"</code></td><td valign="top">
A network-related or connection-related error.
</td></tr><tr><td valign="top"><code class="literal">"presence"</code></td><td valign="top">
A generic presence change notification that doesn't fit into
any other category, such as going away or idle.
</td></tr><tr><td valign="top"><code class="literal">"presence.offline"</code></td><td valign="top">An offline presence change notification.</td></tr><tr><td valign="top"><code class="literal">"presence.online"</code></td><td valign="top">An online presence change notification.</td></tr><tr><td valign="top"><code class="literal">"transfer"</code></td><td valign="top">
A generic file transfer or download notification that doesn't fit
into any other category.
</td></tr><tr><td valign="top"><code class="literal">"transfer.complete"</code></td><td valign="top">A file transfer or download complete notification.</td></tr><tr><td valign="top"><code class="literal">"transfer.error"</code></td><td valign="top">A file transfer or download error.</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="urgency-levels"></a>Urgency Levels</h2></div></div></div><p>
Notifications have an urgency level associated with them. This defines
the importance of the notification. For example, "Joe Bob signed on"
would be a low urgency. "You have new mail" or "A USB device was unplugged"
would be a normal urgency. "Your computer is on fire" would be a critical
urgency.
</p><p>Urgency levels are defined as follows:</p><div class="table"><a id="id-1.8.4"></a><p class="title"><strong>Table 3. Urgency Levels</strong></p><div class="table-contents"><table class="table" summary="Urgency Levels" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody valign="top"><tr><td valign="top">0</td><td valign="top">Low</td></tr><tr><td valign="top">1</td><td valign="top">Normal</td></tr><tr><td valign="top">2</td><td valign="top">Critical</td></tr></tbody></table></div></div><br class="table-break" /><p>
Developers must use their own judgement when deciding the urgency of a
notification. Typically, if the majority of programs are using the same
level for a specific type of urgency, other applications should follow
them.
</p><p>
For low and normal urgencies, server implementations may display the
notifications how they choose. They should, however, have a sane
expiration timeout dependent on the urgency level.
</p><p>
Critical notifications should not automatically expire, as they are
things that the user will most likely want to know about. They should
only be closed when the user dismisses them, for example, by clicking on
the notification.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="hints"></a>Hints</h2></div></div></div><p>
Hints are a way to provide extra data to a notification server that
the server may be able to make use of.
</p><p>
Neither clients nor notification servers are required to support any
hints. Both sides should assume that hints are not passed, and should
ignore any hints they do not understand.
</p><p>
Third parties, when defining their own hints, should discuss the
possibility of standardizing on the hint with other parties, preferably
in a place such as the
<a class="ulink" href="http://freedesktop.org/mailman/listinfo/xdg" target="_top">xdg</a>
mailing list at
<a class="ulink" href="http://freedesktop.org/" target="_top">freedesktop.org</a>. If it
warrants a standard, it will be added to the table above. If no
consensus is reached, the hint name should be in the form of
<code class="literal">"x-<em class="replaceable"><code>vendor</code></em>-<em class="replaceable"><code>name</code></em>."</code>
</p><p>
The value type for the hint dictionary in D-BUS is of the
<code class="literal">DBUS_TYPE_VARIANT</code> container type. This allows different
data types (string, integer, boolean, etc.) to be used for hints. When
adding a dictionary of hints, this type must be used, rather than putting
the actual hint value in as the dictionary value.
</p><p>
The following table lists the standard hints as defined by this
specification. Future hints may be proposed and added to this list
over time. Once again, implementations are not required to support these.
</p><div class="table"><a id="id-1.9.7"></a><p class="title"><strong>Table 4. Standard Hints</strong></p><div class="table-contents"><table class="table" summary="Standard Hints" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Value Type</th><th>Description</th><th>Spec Version</th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="literal">"action-icons"</code></td><td valign="top">BOOLEAN</td><td valign="top">
When set, a server that has the "action-icons" capability will
attempt to interpret any action identifier as a named icon.
The localized display name will be used to annotate the icon
for accessibility purposes. The icon name should be compliant
with the Freedesktop.org Icon Naming Specification.
</td><td valign="top">>= 1.2</td></tr><tr><td valign="top"><code class="literal">"category"</code></td><td valign="top">STRING</td><td valign="top">
The type of notification this is.
</td><td valign="top"> </td></tr><tr><td valign="top"><code class="literal">"desktop-entry"</code></td><td valign="top">STRING</td><td valign="top">
This specifies the name of the desktop filename representing the
calling program. This should be the same as the prefix used for the
application's .desktop file. An example would be "rhythmbox" from
"rhythmbox.desktop". This can be used by the daemon to retrieve the
correct icon for the application, for logging purposes, etc.
</td><td valign="top"> </td></tr><tr><td valign="top"><code class="literal">"image-data"</code></td><td valign="top">(iiibiiay)</td><td valign="top">
This is a raw data image format which describes the width, height,
rowstride, has alpha, bits per sample, channels and image data
respectively.
</td><td valign="top">>= 1.2</td></tr><tr><td valign="top"><code class="literal">"image_data"</code></td><td valign="top">(iiibiiay)</td><td valign="top">
<span class="emphasis"><em>Deprecated</em></span>. Use image-data instead.
</td><td valign="top">= 1.1</td></tr><tr><td valign="top"><code class="literal">"image-path"</code></td><td valign="top">STRING</td><td valign="top">
Alternative way to define the notification image. See <a class="xref" href="#icons-and-images" title="Icons and Images">Icons and Images</a>.
</td><td valign="top">>= 1.2</td></tr><tr><td valign="top"><code class="literal">"image_path"</code></td><td valign="top">STRING</td><td valign="top">
<span class="emphasis"><em>Deprecated</em></span>. Use image-path instead.
</td><td valign="top">= 1.1</td></tr><tr><td valign="top"><code class="literal">"icon_data"</code></td><td valign="top">(iiibiiay)</td><td valign="top">
<span class="emphasis"><em>Deprecated</em></span>. Use image-data instead.
</td><td valign="top">< 1.1</td></tr><tr><td valign="top"><code class="literal">"resident"</code></td><td valign="top">BOOLEAN</td><td valign="top">
When set the server will not automatically remove the
notification when an action has been invoked. The notification
will remain resident in the server until it is explicitly
removed by the user or by the sender. This hint is likely only
useful when the server has the "persistence" capability.
</td><td valign="top">>= 1.2</td></tr><tr><td valign="top"><code class="literal">"sound-file"</code></td><td valign="top">STRING</td><td valign="top">
The path to a sound file to play when the notification pops up.
</td><td valign="top"> </td></tr><tr><td valign="top"><code class="literal">"sound-name"</code></td><td valign="top">STRING</td><td valign="top">
A themeable named sound from the freedesktop.org
<a class="ulink" href="http://0pointer.de/public/sound-naming-spec.html" target="_top">sound naming specification</a>
to play when the notification pops up. Similar to icon-name, only for
sounds. An example would be "message-new-instant".
</td><td valign="top"> </td></tr><tr><td valign="top"><code class="literal">"suppress-sound"</code></td><td valign="top">BOOLEAN</td><td valign="top">
Causes the server to suppress playing any sounds, if it has that
ability. This is usually set when the client itself is going to
play its own sound.
</td><td valign="top"> </td></tr><tr><td valign="top"><code class="literal">"transient"</code></td><td valign="top">BOOLEAN</td><td valign="top">
When set the server will treat the notification as transient
and by-pass the server's persistence capability, if it should
exist.
</td><td valign="top">>= 1.2</td></tr><tr><td valign="top"><code class="literal">"x"</code></td><td valign="top">INT32</td><td valign="top">
Specifies the X location on the screen that the notification should
point to. The <code class="literal">"y"</code> hint must also be specified.
</td><td valign="top"> </td></tr><tr><td valign="top"><code class="literal">"y"</code></td><td valign="top">INT32</td><td valign="top">
Specifies the Y location on the screen that the notification should
point to. The <code class="literal">"x"</code> hint must also be specified.
</td><td valign="top"> </td></tr><tr><td valign="top"><code class="literal">"urgency"</code></td><td valign="top">BYTE</td><td valign="top">
The urgency level.
</td><td valign="top"> </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="protocol"></a>D-BUS Protocol</h2></div></div></div><p>
The following messages <span class="emphasis"><em>must</em></span> be supported by all
implementations.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="commands"></a>Message commands</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="command-get-capabilities"></a><code class="literal">org.freedesktop.Notifications.GetCapabilities</code></h4></div></div></div><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">as
<strong class="fsfunc">org.freedesktop.Notifications.GetCapabilities</strong>
(</code></td><td><code>)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div></div><p>
This message takes no parameters.
</p><p>
It returns an array of strings. Each string describes an optional
capability implemented by the server. The following values are
defined by this spec:
</p><div class="table"><a id="id-1.10.3.2.5"></a><p class="title"><strong>Table 5. Server Capabilities</strong></p><div class="table-contents"><table class="table" summary="Server Capabilities" border="1"><colgroup><col /><col /></colgroup><tbody valign="top"><tr><td valign="top"><code class="literal">"action-icons"</code></td><td valign="top">
Supports using icons instead of text for displaying actions.
Using icons for actions must be enabled on a per-notification
basis using the "action-icons" hint.
</td></tr><tr><td valign="top"><code class="literal">"actions"</code></td><td valign="top">
The server will provide the specified actions to the user. Even if
this cap is missing, actions may still be specified by the client,
however the server is free to ignore them.
</td></tr><tr><td valign="top"><code class="literal">"body"</code></td><td valign="top">
Supports body text. Some implementations may only show the
summary (for instance, onscreen displays, marquee/scrollers)
</td></tr><tr><td valign="top"><code class="literal">"body-hyperlinks"</code></td><td valign="top">
The server supports hyperlinks in the notifications.
</td></tr><tr><td valign="top"><code class="literal">"body-images"</code></td><td valign="top">
The server supports images in the notifications.
</td></tr><tr><td valign="top"><code class="literal">"body-markup"</code></td><td valign="top">
Supports markup in the body text. If marked up text is sent
to a server that does not give this cap, the markup will show
through as regular text so must be stripped clientside.
</td></tr><tr><td valign="top"><code class="literal">"icon-multi"</code></td><td valign="top">
The server will render an animation of all the frames in a given
image array. The client may still specify multiple frames even if
this cap and/or <code class="literal">"icon-static"</code> is missing, however
the server is free to ignore them and use only the primary frame.
</td></tr><tr><td valign="top"><code class="literal">"icon-static"</code></td><td valign="top">
Supports display of exactly 1 frame of any given image array.
This value is mutually exclusive with
<code class="literal">"icon-multi"</code>, it is a protocol error for the
server to specify both.
</td></tr><tr><td valign="top"><code class="literal">"persistence"</code></td><td valign="top">
The server supports persistence of notifications.
Notifications will be retained until they are acknowledged or
removed by the user or recalled by the sender. The presence
of this capability allows clients to depend on the server to
ensure a notification is seen and eliminate the need for
the client to display a reminding function (such as a status
icon) of its own.
</td></tr><tr><td valign="top"><code class="literal">"sound"</code></td><td valign="top">
The server supports sounds on notifications. If returned, the
server must support the <code class="literal">"sound-file"</code> and
<code class="literal">"suppress-sound"</code> hints.
</td></tr></tbody></table></div></div><br class="table-break" /><p>
New vendor-specific caps may be specified as long as they start with
<code class="literal">"x-<em class="replaceable"><code>vendor</code></em>"</code>. For instance,
<code class="literal">"x-gnome-foo-cap"</code>. Capability names must not
contain spaces. They are limited to alpha-numeric characters and dashes
(<code class="literal">"-"</code>).
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="command-notify"></a><code class="literal">org.freedesktop.Notifications.Notify</code></h4></div></div></div><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">UINT32
<strong class="fsfunc">org.freedesktop.Notifications.Notify</strong>
(</code></td><td><var class="pdparam">app_name</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">replaces_id</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">app_icon</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">summary</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">body</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">actions</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">hints</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">expire_timeout</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>STRING <var class="pdparam">app_name</var></code>;<br /><code>UINT32 <var class="pdparam">replaces_id</var></code>;<br /><code>STRING <var class="pdparam">app_icon</var></code>;<br /><code>STRING <var class="pdparam">summary</var></code>;<br /><code>STRING <var class="pdparam">body</var></code>;<br /><code>as <var class="pdparam">actions</var></code>;<br /><code>a{sv} <var class="pdparam">hints</var></code>;<br /><code>INT32 <var class="pdparam">expire_timeout</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
Sends a notification to the notification server.
</p><div class="table"><a id="id-1.10.3.3.4"></a><p class="title"><strong>Table 6. Notify Parameters</strong></p><div class="table-contents"><table class="table" summary="Notify Parameters" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody valign="top"><tr><td valign="top"><em class="parameter"><code>app_name</code></em></td><td valign="top">STRING</td><td valign="top">
The optional name of the application sending the notification.
Can be blank.
</td></tr><tr><td valign="top"><em class="parameter"><code>replaces_id</code></em></td><td valign="top">UINT32</td><td valign="top">
The optional notification ID that this notification replaces. The
server must atomically (ie with no flicker or other visual cues)
replace the given notification with this one. This allows clients to
effectively modify the notification while it's active. A value of
value of 0 means that this notification won't replace any
existing notifications.
</td></tr><tr><td valign="top"><em class="parameter"><code>app_icon</code></em></td><td valign="top">STRING</td><td valign="top">
The optional program icon of the calling application. See <a class="xref" href="#icons-and-images" title="Icons and Images">Icons and Images</a>.
Can be an empty string, indicating no icon.
</td></tr><tr><td valign="top"><em class="parameter"><code>summary</code></em></td><td valign="top">STRING</td><td valign="top">The summary text briefly describing the notification.</td></tr><tr><td valign="top"><em class="parameter"><code>body</code></em></td><td valign="top">STRING</td><td valign="top">The optional detailed body text. Can be empty.</td></tr><tr><td valign="top"><em class="parameter"><code>actions</code></em></td><td valign="top">as</td><td valign="top">
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.
</td></tr><tr><td valign="top"><em class="parameter"><code>hints</code></em></td><td valign="top">a{sv}</td><td valign="top">
Optional hints that can be passed to the server from the client
program. Although clients and servers should never assume each other
supports any specific hints, they can be used to pass along
information, such as the process PID or window ID, that the server
may be able to make use of. See <a class="xref" href="#hints" title="Hints">Hints</a>. Can be
empty.
</td></tr><tr><td valign="top"><em class="parameter"><code>expire_timeout</code></em></td><td valign="top">INT32</td><td valign="top">
<p>
The timeout time in milliseconds since the display of the notification at
which the notification should automatically close.
</p>
<p>
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, never expire.
</p>
</td></tr></tbody></table></div></div><br class="table-break" /><p>
If <em class="parameter"><code>replaces_id</code></em> is 0, the return value is a
UINT32 that represent the notification. It is unique, and will not be
reused unless a <code class="constant">MAXINT</code> number of notifications
have been generated. An acceptable implementation may just use an
incrementing counter for the ID. The returned ID is always greater than
zero. Servers must make sure not to return zero as an ID.
</p><p>
If <em class="parameter"><code>replaces_id</code></em> is not 0, the returned value
is the same value as <em class="parameter"><code>replaces_id</code></em>.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="command-close-notification"></a><code class="literal">org.freedesktop.Notifications.CloseNotification</code></h4></div></div></div><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void
<strong class="fsfunc">org.freedesktop.Notifications.CloseNotification</strong>
(</code></td><td><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>UINT32 id</code>;</div><div class="funcprototype-spacer"> </div></div><p>
Causes a notification to be forcefully closed and removed from the user's
view. It can be used, for example, in the event that what the
notification pertains to is no longer relevant, or to cancel a
notification with no expiration time.
</p><p>
The <code class="literal">NotificationClosed</code> signal is emitted by this
method.
</p><p>
If the notification no longer exists, an empty D-BUS Error message is
sent back.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="command-get-server-information"></a><code class="literal">org.freedesktop.Notifications.GetServerInformation</code></h4></div></div></div><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">
void
<strong class="fsfunc">org.freedesktop.Notifications.GetServerInformation</strong>
(</code></td><td><var class="pdparam">name</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">vendor</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">version</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">spec_version</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>out STRING <var class="pdparam">name</var></code>;<br /><code>out STRING <var class="pdparam">vendor</var></code>;<br /><code>out STRING <var class="pdparam">version</var></code>;<br /><code>out STRING <var class="pdparam">spec_version</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
This message returns the information on the server. Specifically,
the server name, vendor, and version number.
</p><div class="table"><a id="id-1.10.3.5.4"></a><p class="title"><strong>Table 7. GetServerInformation Return Values</strong></p><div class="table-contents"><table class="table" summary="GetServerInformation Return Values" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody valign="top"><tr><td valign="top"><em class="parameter"><code>name</code></em></td><td valign="top">STRING</td><td valign="top">The product name of the server.</td></tr><tr><td valign="top"><em class="parameter"><code>vendor</code></em></td><td valign="top">STRING</td><td valign="top">
The vendor name. For example, "KDE," "GNOME,"
"freedesktop.org," or "Microsoft."
</td></tr><tr><td valign="top"><em class="parameter"><code>version</code></em></td><td valign="top">STRING</td><td valign="top">The server's version number.</td></tr><tr><td valign="top"><em class="parameter"><code>spec_version</code></em></td><td valign="top">STRING</td><td valign="top">The specification version the server is compliant with.</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="signals"></a>Signals</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="signal-notification-closed"></a><code class="literal">org.freedesktop.Notifications.NotificationClosed</code></h4></div></div></div><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">
<strong class="fsfunc">org.freedesktop.Notifications.NotificationClosed</strong>
(</code></td><td><var class="pdparam">id</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">reason</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>UINT32 <var class="pdparam">id</var></code>;<br /><code>UINT32 <var class="pdparam">reason</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
A completed notification is one that has timed out, or has been
dismissed by the user.
</p><div class="table"><a id="id-1.10.4.2.4"></a><p class="title"><strong>Table 8. NotificationClosed Parameters</strong></p><div class="table-contents"><table class="table" summary="NotificationClosed Parameters" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody valign="top"><tr><td valign="top"><em class="parameter"><code>id</code></em></td><td valign="top">UINT32</td><td valign="top">The ID of the notification that was closed.</td></tr><tr><td valign="top"><em class="parameter"><code>reason</code></em></td><td valign="top">UINT32</td><td valign="top">
<p>The reason the notification was closed.</p>
<p>1 - The notification expired.</p>
<p>2 - The notification was dismissed by the user.</p>
<p>3 - The notification was closed by a call to
<code class="literal">CloseNotification</code>.</p>
<p>4 - Undefined/reserved reasons.</p>
</td></tr></tbody></table></div></div><br class="table-break" /><p>
The ID specified in the signal is invalidated
<span class="emphasis"><em>before</em></span> the signal is sent and may not be used
in any further communications with the server.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="signal-action-invoked"></a><code class="literal">org.freedesktop.Notifications.ActionInvoked</code></h4></div></div></div><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">
<strong class="fsfunc">org.freedesktop.Notifications.ActionInvoked</strong>
(</code></td><td><var class="pdparam">id</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">action_key</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>UINT32 <var class="pdparam">id</var></code>;<br /><code>STRING <var class="pdparam">action_key</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
This signal is emitted when one of the following occurs:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The user performs some global "invoking" action upon a notification.
For instance, clicking somewhere on the notification itself.
</p></li><li class="listitem"><p>
The user invokes a specific action as specified in the original
Notify request. For example, clicking on an action button.
</p></li></ul></div><div class="table"><a id="id-1.10.4.3.5"></a><p class="title"><strong>Table 9. ActionInvoked Parameters</strong></p><div class="table-contents"><table class="table" summary="ActionInvoked Parameters" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody valign="top"><tr><td valign="top"><em class="parameter"><code>id</code></em></td><td valign="top">UINT32</td><td valign="top">
The ID of the notification emitting the ActionInvoked signal.
</td></tr><tr><td valign="top"><em class="parameter"><code>action_key</code></em></td><td valign="top">STRING</td><td valign="top">
The key of the action invoked. These match the keys sent over
in the list of actions.
</td></tr></tbody></table></div></div><br class="table-break" /><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Clients should not assume the server will generate this signal. Some
servers may not support user interaction at all, or may not support
the concept of being able to "invoke" a notification.
</p></div></div></div></div></div></body></html>