jcarr
/
libnotify
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added the notification spec in docbook format. It's not finished. I'm just tired of working on it.

This commit is contained in:
Christian Hammond 2004-08-30 05:28:22 +00:00
parent 63480ac2bd
commit c9f2aac99a
3 changed files with 4048 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
ChangeLog
View File

@ -1,3 +1,10 @@
Sun Aug 29 22:27:42 PDT 2004 Christian Hammond <chipx86@gnupdate.org>
A docs/notification-spec.ps:
A docs/notification-spec.xml:
- Added the notification spec in docbook format. It's not finished.
I'm just tired of working on it.
Wed Jul 14 02:11:48 GMT 2004 Mike Hearn <mike@navi.cx>
* libnotify/notify.c: Use pointers instead of GINT_TO_POINTER
* tools/test-replace.c: Test replacing notifications

3252
docs/notification-spec.ps Normal file
View File

File diff suppressed because it is too large Load Diff

789
docs/notification-spec.xml Normal file
View File

@ -0,0 +1,789 @@
<?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>28 August 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>28 August 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 "/org/freedesktop/Notifications". This is the
only interface required by this version of the specification.
</para>
<para>
A notification has the following components:
</para>
<variablelist>
<varlistentry>
<term>Application Name</term>
<listitem>
<para>
Application name: This is the optional name of the application sending
the notification. This should be the application's formal name, rather
than some sort of ID.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Application Icon</term>
<listitem>
<para>
An optional byte array containing the application's icon.
This should be in PNG or GIF formats.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Application ID</term>
<listitem>
<para>
An optional byte array containing the application's icon.
This should be in PNG or GIF formats.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Replaces ID</term>
<listitem>
<para>
An optional ID of an existing notification that this
notification is intended to replace.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notification Type ID</term>
<listitem>
<para>
An optional ID representing the notification type. See
<xref linkend="notification-types"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Urgency Level</term>
<listitem>
<para>
The urgency of the notification. See <xref linkend="urgency-levels"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Summary</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Body</term>
<listitem>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>Images</term>
<listitem>
<para>
See <xref linkend="icons-sounds"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Sounds</term>
<listitem>
<para>
See <xref linkend="icons-sounds"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Actions</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Hints</term>
<listitem>
<para>
See <xref linkend="hints"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Expiration Time</term>
<listitem>
<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>
<para>
The expiration time should be respected by implementations, but this is
not required (this is for compatibility with KNotify).
</para>
</listitem>
</varlistentry>
</variablelist>
<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 GetCapabilities 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 instead
and the notification server is only used when available.
</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>
<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-sounds" xreflabel="Icons and Sounds">
<title>Icons and Sounds</title>
<para>
A notification can optionally include an array of images and/or a
single sound. The array of images specifies frames in an animation,
animations always loop. Implementations are free to ignore the
images and sound 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 (for instance a
<application>KNotify</application> bridge), 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>
<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>
<para>
A sound can be specified, this will be played by the notification
server when the notification is displayed.
<remark>Elaborate here!</remark>
</para>
</sect1>
<sect1 id="notification-types" xreflabel="Notification Types">
<title>Notification Types</title>
<para><remark>Write me!</remark></para>
</sect1>
<sect1 id="urgency-levels" xreflabel="Urgency Levels">
<title>Urgency Levels</title>
<para><remark>Write me!</remark></para>
</sect1>
<sect1 id="hints" xreflabel="Hints">
<title>Hints</title>
<para><remark>Write me!</remark></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>
<informaltable>
<tgroup cols="2">
<tbody>
<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>"sound"</literal></entry>
<entry>
The server will play the specified sound. Even if this cap is
missing, a sound may still be specified however the server is free
to ignore it.
</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>
</informaltable>
<para>
New vendor-specific caps may be specified as long as they start with
<literal>"x-vendorname"</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_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>STRING_OR_NIL <parameter>sound</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>
<row>
<entry>app_name</entry>
<entry>STRING or NIL</entry>
<entry>
The optional name of the application sending the notification.
</entry>
</row>
<row>
<entry>app_icon</entry>
<entry>BYTE_ARRAY or NIL</entry>
<entry>The optional program icon of the calling application.</entry>
</row>
<row>
<entry>replaces_id</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>notification_type</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>urgency_level</entry>
<entry>BYTE</entry>
<entry>The urgency level. See <xref linkend="urgency-levels"/>.</entry>
</row>
<row>
<entry>summary</entry>
<entry>STRING</entry>
<entry>The summary text briefly describing the notification.</entry>
</row>
<row>
<entry>body</entry>
<entry>STRING or NIL</entry>
<entry>The optional detailed body text.</entry>
</row>
<row>
<entry>images</entry>
<entry>ARRAY or NIL</entry>
<entry>
The optional array of images. See <xref linkend="icons-sounds"/>.
</entry>
</row>
<row>
<entry>sound</entry>
<entry>STRING</entry>
<entry>The optional sound file to play.</entry>
</row>
<row>
<entry>actions</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>hints</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>expire_time</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>BOOLEAN
<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 onger relevant, or to cancel a
notification with no expiration time.
</para>
<para>
The <literal>NotificationClosed</literal> signal is emitted by this
method.
</para>
<para>
This returns <constant>TRUE</constant> if the notification was closed.
If the notification didn't exist, this will return
<constant>FALSE</constant>. This can happen if the notification already
expired or was closed, or if the ID was simply invalid.
</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>
<row>
<entry>name</entry>
<entry>STRING</entry>
<entry>The product name of the server.</entry>
</row>
<row>
<entry>vendor</entry>
<entry>STRING</entry>
<entry>
The vendor name. For example, "KDE," "GNOME,"
"freedesktop.org," or "Microsoft."
</entry>
</row>
<row>
<entry>version</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 Return Values</title>
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<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 - "Other" 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>
</sect2>
</sect1>
</article>