978 lines
32 KiB
XML
978 lines
32 KiB
XML
<?xml version="1.0"?>
|
|
|
|
<!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
|
|
|
<article id="index">
|
|
<articleinfo>
|
|
<title>Desktop Notifications Specification</title>
|
|
<releaseinfo>Version 0.3</releaseinfo>
|
|
<date>15 September 2004</date>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Mike</firstname>
|
|
<surname>Hearn</surname>
|
|
<affiliation>
|
|
<address>
|
|
<email>mike@navi.cx</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
<author>
|
|
<firstname>Christian</firstname>
|
|
<surname>Hammond</surname>
|
|
<affiliation>
|
|
<address>
|
|
<email>chipx86@chipx86.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
</authorgroup>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>0.3</revnumber>
|
|
<date>15 September 2004</date>
|
|
<authorinitials>cdh</authorinitials>
|
|
<revremark>Added hint and notification type sections</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>0.2</revnumber>
|
|
<date>foo</date>
|
|
<authorinitials>mh</authorinitials>
|
|
<revremark>Added replaces field to protocol</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>0.1</revnumber>
|
|
<date>foo</date>
|
|
<authorinitials>mh</authorinitials>
|
|
<revremark>Initial version</revremark>
|
|
</revision>
|
|
</revhistory>
|
|
</articleinfo>
|
|
|
|
<sect1 id="introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
This is a draft standard for a desktop notifications service, through
|
|
which applications can generate passive popups (sometimes known as
|
|
"poptarts") to notify the user in an asynchronous manner of events.
|
|
</para>
|
|
<para>
|
|
This specification explicitly does not include other types of
|
|
notification presentation such as modal message boxes, window manager
|
|
decorations or window list annotations.
|
|
</para>
|
|
<para>
|
|
Example use cases include:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Presence changes in IM programs: for instance, MSN Messenger on
|
|
Windows pioneered the use of passive popups to indicate presence
|
|
changes.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>Scheduled alarm</para></listitem>
|
|
<listitem><para>Completed file transfer</para></listitem>
|
|
<listitem><para>New mail notification</para></listitem>
|
|
<listitem><para>Low disk space/battery warnings</para></listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="basic-design">
|
|
<title>Basic Design</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
On startup, a conforming implementation should take the
|
|
<literal>org.freedesktop.Notifications</literal> 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.
|
|
</para>
|
|
<para>
|
|
The server should implement the
|
|
<literal>org.freedesktop.Notifications</literal> interface on
|
|
an object with the path <literal>"/org/freedesktop/Notifications"</literal>.
|
|
This is the only interface required by this version of the specification.
|
|
</para>
|
|
<para>
|
|
A notification has the following components:
|
|
</para>
|
|
<table>
|
|
<title>Notification Components</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Component</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>Application Name</entry>
|
|
<entry>
|
|
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."
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Application Icon</entry>
|
|
<entry>
|
|
The application icon. This is represented either as a path or a name
|
|
in an icon theme.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Replaces ID</entry>
|
|
<entry>
|
|
An optional ID of an existing notification that this
|
|
notification is intended to replace.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Notification Type ID</entry>
|
|
<entry>
|
|
An optional ID representing the notification type. See
|
|
<xref linkend="notification-types"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Urgency Level</entry>
|
|
<entry>
|
|
The urgency of the notification. See <xref linkend="urgency-levels"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Summary</entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Body</entry>
|
|
<entry>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
The text may contain simple markup as specified in
|
|
<xref linkend="markup"/>. It must be encoded using UTF-8.
|
|
</para>
|
|
<para>
|
|
If the body is omitted just the summary is displayed.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Images</entry>
|
|
<entry>See <xref linkend="icons"/>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Actions</entry>
|
|
<entry>
|
|
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
|
|
<xref linkend="protocol"/>. An implementation is free to ignore any
|
|
requested by the client. As an example one possible rendering of
|
|
actions would be as buttons in the notification popup.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Hints</entry>
|
|
<entry>See <xref linkend="hints"/>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Expiration Time</entry>
|
|
<entry>
|
|
<para>
|
|
The timestamp in seconds since the epoch that the notification should
|
|
close. For example, if one wishes to have an expiration of 5 seconds
|
|
from now, they must grab the current timestamp and add 5 seconds to it.
|
|
</para>
|
|
<para>
|
|
If zero, the notification's expiration time is dependent on the
|
|
notification server's settings, and may vary for the type of
|
|
notification.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
This can be used to hide the notification before the expiration time
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="backwards-compat" xreflabel="Backwards Compatibility">
|
|
<title>Backwards Compatibility</title>
|
|
<para>
|
|
Clients should try and avoid making assumptions about the presentation and
|
|
abilities of the notification server. The message content is the most
|
|
important thing.
|
|
</para>
|
|
<para>
|
|
Clients can check with the server what capabilities are supported
|
|
using the <literal>GetCapabilities</literal> message. See
|
|
<xref linkend="protocol"/>.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="markup" xreflabel="Markup">
|
|
<title>Markup</title>
|
|
<para>
|
|
Body text may contain markup. The markup is XML-based, and consists
|
|
of a small subset of HTML along with a few additional tags.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>
|
|
<sgmltag class="starttag">b</sgmltag> ...
|
|
<sgmltag class="endtag">b</sgmltag>
|
|
</entry>
|
|
<entry>Bold</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<sgmltag class="starttag">i</sgmltag> ...
|
|
<sgmltag class="endtag">i</sgmltag>
|
|
</entry>
|
|
<entry>Italic</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<sgmltag class="starttag">u</sgmltag> ...
|
|
<sgmltag class="endtag">u</sgmltag>
|
|
</entry>
|
|
<entry>Underline</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<sgmltag class="starttag">a href="..."</sgmltag> ...
|
|
<sgmltag class="endtag">a</sgmltag>
|
|
</entry>
|
|
<entry>Hyperlink</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
<remark>
|
|
What else do we want here? We're going to want more tags
|
|
for sure.
|
|
</remark>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="icons" xreflabel="Icons">
|
|
<title>Icons</title>
|
|
<para>
|
|
A notification can optionally include an array of images. The array of
|
|
images specifies frames in an animation, which always loop.
|
|
Implementations are free to ignore the images data, and implementations
|
|
that support images need not support animation.
|
|
</para>
|
|
<para>
|
|
If the image array has more than one element, a "primary frame" can
|
|
be specified. If not specified, it defaults to the first frame. For
|
|
implementations that support images but not animation, only the primary
|
|
frame will be used.
|
|
</para>
|
|
<para>
|
|
Each element of the array must have the same type as the first
|
|
element. Mixtures of strings and blobs are not allowed. The element
|
|
types can be one of the following:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Element</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>Icon Theme Name</entry>
|
|
<entry>String</entry>
|
|
<entry>
|
|
Any string that does not begin with the <literal>/</literal>
|
|
character is assumed to be an icon theme name and is looked up
|
|
according to the spec. The best size to fit the servers chosen
|
|
presentation will be used. This is the recommended way of specifying
|
|
images.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Absolute Path</entry>
|
|
<entry>String</entry>
|
|
<entry>
|
|
Any string that begins with a <literal>/</literal> will be used as
|
|
an absolute file path. Implementations should support at minimum
|
|
files of type image/png and image/svg.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Image Data</entry>
|
|
<entry>Binary Data</entry>
|
|
<entry>
|
|
A data stream may be embedded in the message. This is assumed to be
|
|
of type image/png.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect1>
|
|
|
|
<sect1 id="notification-types" xreflabel="Notification Types">
|
|
<title>Notification Types</title>
|
|
<para>
|
|
Notifications can optionally have a type indicator. Although neither
|
|
client or nor server must support this, some may choose to. Those servers
|
|
implementing notification types may use them to intelligently display
|
|
the notification in a certain way, or group notifications of similar
|
|
types.
|
|
</para>
|
|
<para>
|
|
The following table lists standard notifications as defined by this spec.
|
|
More will be added in time.
|
|
</para>
|
|
<table>
|
|
<title>Notification Types</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><literal>"email"</literal></entry>
|
|
<entry>An e-mail notification.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"im"</literal></entry>
|
|
<entry>A new IM notification.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"device"</literal></entry>
|
|
<entry>A device-related notification, such as a USB device being
|
|
plugged in or unplugged.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"presence"</literal></entry>
|
|
<entry>A presence change, such as a user going online or offline.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"transfer-complete"</literal></entry>
|
|
<entry>A file transfer or download complete notification.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
Third parties, when defining their own notification types, should discuss
|
|
the possibility of standardizing on the hint with other parties, preferably
|
|
in a place such as the
|
|
<ulink url="http://freedesktop.org/mailman/listinfo/xdg">xdg</ulink>
|
|
mailing list at
|
|
<ulink url="http://freedesktop.org/">freedesktop.org</ulink>. If it
|
|
warrants a standard, it will be added to the table above. If no
|
|
consensus is reached, the notification type should be in the form of
|
|
<literal>"x-<replaceable>vendor</replaceable>-<replaceable>name</replaceable>."</literal>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="urgency-levels" xreflabel="Urgency Levels">
|
|
<title>Urgency Levels</title>
|
|
<para>
|
|
Notifications have an urgency level associated with them. This defines
|
|
the importance of the notification. For example, "Your computer is on
|
|
fire" would be a critical urgency. "Joe Bob signed on" would be a low
|
|
urgency.
|
|
</para>
|
|
<para>Urgency levels are defined as follows:</para>
|
|
<table>
|
|
<title>Urgency Levels</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>0</entry>
|
|
<entry>Low</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>Medium (Normal)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>2</entry>
|
|
<entry>High</entry>
|
|
</row>
|
|
<row>
|
|
<entry>3</entry>
|
|
<entry>Critical</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
For the most part, server implementations may use urgency information
|
|
how they see fit. The one exception is the Critical notification.
|
|
As Critical notifications are things that the user will most likely want
|
|
to know about, they should not be closed until the user dismisses them.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="hints" xreflabel="Hints">
|
|
<title>Hints</title>
|
|
<para>
|
|
Hints are a way to provide extra data to a notification server that
|
|
the server may be able to make use of.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<!--
|
|
<para>
|
|
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.
|
|
</para>
|
|
<table>
|
|
<title>Standard Hints</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Value Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><literal>"winid"</literal></entry>
|
|
<entry>UINT32</entry>
|
|
<entry>
|
|
The Window ID that sent the notification. This may be used,
|
|
for example, to flash the window.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
-->
|
|
<para>
|
|
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
|
|
<ulink url="http://freedesktop.org/mailman/listinfo/xdg">xdg</ulink>
|
|
mailing list at
|
|
<ulink url="http://freedesktop.org/">freedesktop.org</ulink>. 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
|
|
<literal>"x-<replaceable>vendor</replaceable>-<replaceable>name</replaceable>."</literal>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="protocol" xreflabel="Protocol">
|
|
<title>D-BUS Protocol</title>
|
|
<para>
|
|
The following messages <emphasis>must</emphasis> be supported by all
|
|
implementations.
|
|
</para>
|
|
|
|
<sect2 id="commands">
|
|
<title>Message commands</title>
|
|
|
|
<sect3 id="command-get-capabilities">
|
|
<title><literal>org.freedesktop.Notifications.GetCapabilities</literal></title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>STRING_ARRAY
|
|
<function>org.freedesktop.Notifications.GetCapabilities</function>
|
|
</funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This message takes no parameters.
|
|
</para>
|
|
<para>
|
|
It returns an array of strings. Each string describes an optional
|
|
capability implemented by the server. The following values are
|
|
defined by this spec:
|
|
</para>
|
|
<table>
|
|
<title>Server Capabilities</title>
|
|
<tgroup cols="2">
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><literal>"body"</literal></entry>
|
|
<entry>
|
|
Supports body text. Some implementations may only show the
|
|
summary (for instance, onscreen displays, marquee/scrollers)
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"markup"</literal></entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"static-image"</literal></entry>
|
|
<entry>
|
|
Supports display of exactly 1 frame of any given image array.
|
|
This value is mutually exclusive with
|
|
<literal>"multi-image"</literal>, it is a protocol error for the
|
|
server to specify both.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"multi-image"</literal></entry>
|
|
<entry>
|
|
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 static-image is missing, however the server is
|
|
free to ignore them and use only the primary frame.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"actions"</literal></entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
New vendor-specific caps may be specified as long as they start with
|
|
<literal>"x-<replaceable>vendor</replaceable>"</literal>. For instance,
|
|
<literal>"x-gnome-foo-cap"</literal>. Capability names must not
|
|
contain spaces. They are limited to alpha-numeric characters and dashes
|
|
(<literal>"-"</literal>).
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="command-notify">
|
|
<title><literal>org.freedesktop.Notifications.Notify</literal></title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>UINT32
|
|
<function>org.freedesktop.Notifications.Notify</function>
|
|
</funcdef>
|
|
<paramdef>STRING_OR_NIL <parameter>app_name</parameter></paramdef>
|
|
<paramdef>BYTE_ARRAY_OR_STRING_OR_NIL <parameter>app_icon</parameter></paramdef>
|
|
<paramdef>UINT32_OR_NIL <parameter>replaces_id</parameter></paramdef>
|
|
<paramdef>STRING_OR_NIL <parameter>notification_type</parameter></paramdef>
|
|
<paramdef>BYTE <parameter>urgency_level</parameter></paramdef>
|
|
<paramdef>STRING <parameter>summary</parameter></paramdef>
|
|
<paramdef>STRING_OR_NIL <parameter>body</parameter></paramdef>
|
|
<paramdef>ARRAY <parameter>images</parameter></paramdef>
|
|
<paramdef>DICT_OR_NIL <parameter>actions</parameter></paramdef>
|
|
<paramdef>DICT_OR_NIL <parameter>hints</parameter></paramdef>
|
|
<paramdef>UINT32_OR_NIL <parameter>expire_time</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Sends a notification to the notification server.
|
|
</para>
|
|
<table>
|
|
<title>Notify Parameters</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><parameter>app_name</parameter></entry>
|
|
<entry>STRING or NIL</entry>
|
|
<entry>
|
|
The optional name of the application sending the notification.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>app_icon</parameter></entry>
|
|
<entry>BYTE_ARRAY or STRING or NIL</entry>
|
|
<entry>
|
|
The optional program icon of the calling application. This is in
|
|
the same format as an image frame. See <xref linkend="icons"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>replaces_id</parameter></entry>
|
|
<entry>UINT32 or NIL</entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>notification_type</parameter></entry>
|
|
<entry>STRING or NIL</entry>
|
|
<entry>
|
|
The optional notification type ID, for potential server
|
|
categorization and logging purposes. See
|
|
<xref linkend="notification-types"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>urgency_level</parameter></entry>
|
|
<entry>BYTE</entry>
|
|
<entry>The urgency level. See <xref linkend="urgency-levels"/>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>summary</parameter></entry>
|
|
<entry>STRING</entry>
|
|
<entry>The summary text briefly describing the notification.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>body</parameter></entry>
|
|
<entry>STRING or NIL</entry>
|
|
<entry>The optional detailed body text.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>images</parameter></entry>
|
|
<entry>ARRAY or NIL</entry>
|
|
<entry>
|
|
The optional array of images. See <xref linkend="icons"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>actions</parameter></entry>
|
|
<entry>DICT or NIL</entry>
|
|
<entry>
|
|
A dictionary key of actions. Each key is the localized name of the
|
|
action, as it should appear to the user, and maps to a UINT32 value
|
|
containing a program-specific action code. This code will be reported
|
|
back to the program if the action is invoked by the user.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>hints</parameter></entry>
|
|
<entry>DICT or NIL</entry>
|
|
<entry>
|
|
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 <xref linkend="hints"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>expire_time</parameter></entry>
|
|
<entry>UINT32 or NIL</entry>
|
|
<entry>
|
|
The notification time-out time, represented as UNIX-time (seconds
|
|
since the epoch). If this is NIL, the notification
|
|
will never time out, and will only be closed when an action is
|
|
invoked. If non-NIL, this will specify a time at which the notification
|
|
will be automatically closed. If zero, the server's default
|
|
expiration time will be used.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
If <parameter>replaces_id</parameter> is NIL, the return value is a
|
|
UINT32 that represent the notification. It is unique, and will not be
|
|
reused unless a <constant>MAXINT</constant> 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.
|
|
</para>
|
|
<para>
|
|
If <parameter>replaces_id</parameter> is not NIL, the returned value
|
|
is the same value as <parameter>replaces_id</parameter>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="command-close-notification">
|
|
<title><literal>org.freedesktop.Notifications.CloseNotification</literal></title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void
|
|
<function>org.freedesktop.Notifications.CloseNotification</function>
|
|
</funcdef>
|
|
<paramdef>UINT32 id</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
The <literal>NotificationClosed</literal> signal is emitted by this
|
|
method.
|
|
</para>
|
|
<para>
|
|
If the notification no longer exists, an empty D-BUS Error message is
|
|
sent back.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="command-get-server-information">
|
|
<title><literal>org.freedesktop.Notifications.GetServerInformation</literal></title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>
|
|
void
|
|
<function>org.freedesktop.Notifications.GetServerInformation</function>
|
|
</funcdef>
|
|
<paramdef>out STRING <parameter>name</parameter></paramdef>
|
|
<paramdef>out STRING <parameter>vendor</parameter></paramdef>
|
|
<paramdef>out STRING <parameter>version</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This message returns the information on the server. Specifically,
|
|
the server name, vendor, and version number.
|
|
</para>
|
|
<table>
|
|
<title>GetServerInformation Return Values</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><parameter>name</parameter></entry>
|
|
<entry>STRING</entry>
|
|
<entry>The product name of the server.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>vendor</parameter></entry>
|
|
<entry>STRING</entry>
|
|
<entry>
|
|
The vendor name. For example, "KDE," "GNOME,"
|
|
"freedesktop.org," or "Microsoft."
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>version</parameter></entry>
|
|
<entry>STRING</entry>
|
|
<entry>The server's version number.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="signals">
|
|
<title>Signals</title>
|
|
|
|
<sect3 id="signal-notification-closed">
|
|
<title><literal>org.freedesktop.Notifications.NotificationClosed</literal></title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>
|
|
<function>org.freedesktop.Notifications.NotificationClosed</function>
|
|
</funcdef>
|
|
<paramdef>UINT32 <parameter>id</parameter></paramdef>
|
|
<paramdef>UINT32 <parameter>reason</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
A completed notification is one that has timed out, or has been
|
|
dismissed by the user.
|
|
</para>
|
|
<table>
|
|
<title>NotificationClosed Parameters</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><parameter>id</parameter></entry>
|
|
<entry>UINT32</entry>
|
|
<entry>The ID of the notification that was closed.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>reason</parameter></entry>
|
|
<entry>UINT32</entry>
|
|
<entry>
|
|
<para>The reason the notification was closed.</para>
|
|
<para>1 - The notification expired.</para>
|
|
<para>2 - The notification was dismissed by the user.</para>
|
|
<para>3 - The notification was closed by a call to
|
|
<literal>CloseNotification</literal>.</para>
|
|
<para>4 - Undefined/reserved reasons.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
The ID specified in the signal is invalidated
|
|
<emphasis>before</emphasis> the signal is sent and may not be used
|
|
in any further communications with the server.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="signal-action-invoked">
|
|
<title><literal>org.freedesktop.Notifications.ActionInvoked</literal></title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>
|
|
<function>org.freedesktop.Notifications.ActionInvoked</function>
|
|
</funcdef>
|
|
<paramdef>UINT32 <parameter>id</parameter></paramdef>
|
|
<!-- <paramdef>BOOL <parameter>default_action</parameter></paramdef> -->
|
|
<paramdef>UINT32 <parameter>action_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This signal is emitted when one of the following occurs:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The user performs some global "invoking" action upon a notification.
|
|
For instance, clicking somewhere on the notification itself.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The user invokes a specific action as specified in the original
|
|
Notify request. For example, clicking on an action button.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<table>
|
|
<title>ActionInvoked Parameters</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><parameter>id</parameter></entry>
|
|
<entry>UINT32</entry>
|
|
<entry>
|
|
The ID of the notification emitting the ActionInvoked signal.
|
|
</entry>
|
|
</row>
|
|
<!--
|
|
<row>
|
|
<entry><parameter>default_action</parameter></entry>
|
|
<entry>BOOL</entry>
|
|
<entry>
|
|
<constant>TRUE</constant> if the default action was invoked.
|
|
The default action is often a click on the notification. If this
|
|
is <constant>TRUE</constant>, the <parameter>action_id</parameter>
|
|
parameter is ignored.
|
|
</entry>
|
|
</row>
|
|
-->
|
|
<row>
|
|
<entry><parameter>action_id</parameter></entry>
|
|
<entry>UINT32</entry>
|
|
<entry>
|
|
The ID of the action invoked. A value of 0 means that the default
|
|
action was invoked, i.e., clicking the notification itself.
|
|
IDs greater than zero are the action IDs as defined by the
|
|
calling application.
|
|
<!--
|
|
This is ignored if
|
|
<parameter>default_action</parameter> is <constant>TRUE</constant>.
|
|
-->
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</article>
|