|
|
|
@ -1,538 +0,0 @@
|
|
|
|
<?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" href="docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="article" title="Desktop Notifications Specification"><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><b>Table of Contents</b></p><dl><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="#id2776582">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" title="Introduction"><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" 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" title="Basic Design"><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="id2780838"></a><p class="title"><b>Table 1. Notification Components</b></p><div class="table-contents"><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" title="Backwards Compatibility"><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" title="Markup"><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 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" title="Hyperlinks"><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" title="Images"><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" title="Icons and Images"><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" title="Priorities"><div class="titlepage"><div><div><h3 class="title"><a id="id2776582"></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" title="Formats"><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 raw image data structure
|
|
|
|
|
|
|
|
of signature (iiibiiay) which describes the width, height, rowstride, has
|
|
|
|
|
|
|
|
alpha, bits per sample, channels and image data respectively.
|
|
|
|
|
|
|
|
</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" title="Categories"><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="id2776772"></a><p class="title"><b>Table 2. Categories</b></p><div class="table-contents"><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" title="Urgency Levels"><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="id2824982"></a><p class="title"><b>Table 3. Urgency Levels</b></p><div class="table-contents"><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" title="Hints"><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="id2825136"></a><p class="title"><b>Table 4. Standard Hints</b></p><div class="table-contents"><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">int</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">int</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" title="D-BUS Protocol"><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" title="Message commands"><div class="titlepage"><div><div><h3 class="title"><a id="commands"></a>Message commands</h3></div></div></div><div class="sect3" title="org.freedesktop.Notifications.GetCapabilities"><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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">STRING_ARRAY
|
|
|
|
|
|
|
|
<b class="fsfunc">org.freedesktop.Notifications.GetCapabilities</b>
|
|
|
|
|
|
|
|
(</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="id2825605"></a><p class="title"><b>Table 5. Server Capabilities</b></p><div class="table-contents"><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" title="org.freedesktop.Notifications.Notify"><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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">UINT32
|
|
|
|
|
|
|
|
<b class="fsfunc">org.freedesktop.Notifications.Notify</b>
|
|
|
|
|
|
|
|
(</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>ARRAY <var class="pdparam">actions</var></code>;<br /><code>DICT <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="id2825920"></a><p class="title"><b>Table 6. Notify Parameters</b></p><div class="table-contents"><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">ARRAY</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">DICT</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" title="org.freedesktop.Notifications.CloseNotification"><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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void
|
|
|
|
|
|
|
|
<b class="fsfunc">org.freedesktop.Notifications.CloseNotification</b>
|
|
|
|
|
|
|
|
(</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" title="org.freedesktop.Notifications.GetServerInformation"><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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">
|
|
|
|
|
|
|
|
void
|
|
|
|
|
|
|
|
<b class="fsfunc">org.freedesktop.Notifications.GetServerInformation</b>
|
|
|
|
|
|
|
|
(</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="id2826276"></a><p class="title"><b>Table 7. GetServerInformation Return Values</b></p><div class="table-contents"><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" title="Signals"><div class="titlepage"><div><div><h3 class="title"><a id="signals"></a>Signals</h3></div></div></div><div class="sect3" title="org.freedesktop.Notifications.NotificationClosed"><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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">
|
|
|
|
|
|
|
|
<b class="fsfunc">org.freedesktop.Notifications.NotificationClosed</b>
|
|
|
|
|
|
|
|
(</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="id2826433"></a><p class="title"><b>Table 8. NotificationClosed Parameters</b></p><div class="table-contents"><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" title="org.freedesktop.Notifications.ActionInvoked"><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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">
|
|
|
|
|
|
|
|
<b class="fsfunc">org.freedesktop.Notifications.ActionInvoked</b>
|
|
|
|
|
|
|
|
(</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" 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="id2826603"></a><p class="title"><b>Table 9. ActionInvoked Parameters</b></p><div class="table-contents"><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" title="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>
|
|
|
|
|
Alf Gaida
9 years ago