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

- Added <img/> tag support in the markup section. 

- Detailed what markup is and what it is not, and its restrictions.
- Removed the High urgency level.
- Gave a better categorization to notification type formats.
- Added new notification types.
- Fixed notification expiration so it's a timeout rather than a timestamp.
This commit is contained in:
Christian Hammond 2004-09-25 07:23:17 +00:00
parent 5b02b5e988
commit 79889fefe6
2 changed files with 342 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/ChangeLog
View File

@ -1,3 +1,14 @@
Sat Sep 25 00:08:45 PDT 2004 Christian Hammond <chipx86@gnupdate.org>
* notification-spec.xml:
- Added <img/> tag support in the markup section.
- Detailed what markup is and what it is not, and its restrictions.
- Removed the High urgency level.
- Gave a better categorization to notification type formats.
- Added new notification types.
- Fixed notification expiration so it's a timeout rather than a
timestamp.
Fri Sep 03 22:26:31 PDT 2004 Christian Hammond <chipx86@gnupdate.org>
* notification-spec.xml:

408
docs/notification-spec.xml
View File

@ -7,7 +7,7 @@
<articleinfo>
<title>Desktop Notifications Specification</title>
<releaseinfo>Version 0.3</releaseinfo>
<date>28 August 2004</date>
<date>15 September 2004</date>
<authorgroup>
<author>
<firstname>Mike</firstname>
@ -29,9 +29,20 @@
</author>
</authorgroup>
<revhistory>
<!--
<revision>
<revnumber>0.4</revnumber>
<date>25 September 2004</date>
<authorinitials>cdh</authorinitials>
<revremark>
Added image support in markup, and made the restrictions on markup more
clear. Removed the High urgency. Added new notification types. Fixed
notification expiration.</revremark>
</revision>
-->
<revision>
<revnumber>0.3</revnumber>
<date>28 August 2004</date>
<date>15 September 2004</date>
<authorinitials>cdh</authorinitials>
<revremark>Added hint and notification type sections</revremark>
</revision>
@ -169,11 +180,11 @@
implementations are free to word wrap them as they see fit.
</para>
<para>
The text may contain simple markup as specified in
The body 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.
If the body is omitted, just the summary is displayed.
</para>
</entry>
</row>
@ -198,12 +209,21 @@
<entry>See <xref linkend="hints"/>.</entry>
</row>
<row>
<entry>Expiration Time</entry>
<entry>Expires</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.
A boolean flag indicating whether or not this notification should
automatically expire.
</para>
</entry>
</row>
<row>
<entry>Expiration Timeout</entry>
<entry>
<para>
The timeout time in seconds since the display of the notification at
which the notification should automatically close. This is ignored
if the expires flag is set to false.
</para>
<para>
If zero, the notification's expiration time is dependent on the
@ -215,7 +235,6 @@
</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
@ -223,7 +242,7 @@
exceeded.
</para>
<para>
This can be used to hide the notification before the expiration time
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.
@ -291,24 +310,83 @@
</entry>
<entry>Hyperlink</entry>
</row>
<row>
<entry>
<sgmltag class="emptytag">img src="..." alt="..."</sgmltag>
</entry>
<entry>Image</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<remark>
What else do we want here? We're going to want more tags
for sure.
</remark>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<sect2 id="hyperlinks" xreflabel="Hyperlinks">
<title>Hyperlinks</title>
<para>
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.
</para>
<para>
Hyperlinked text should appear in the standard blue underline format.
</para>
<para>
Hyperlinks cannot function as a replacement for actions. They are
used to link to local directories or remote sites using standard URI
schemes.
</para>
<para>
Implementations are not required to support hyperlinks.
</para>
</sect2>
<sect2 id="images" xreflabel="Images">
<title>Images</title>
<para>
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 <literal>alt="..."</literal> attribute.
</para>
<para>
Image data cannot be embedded in the message itself. Images referenced
must always be local files.
</para>
<para>
Implementations are not required to support images.
</para>
</sect2>
</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.
A notification can optionally include an array of images for use as an
icon representing the notification. 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
@ -367,16 +445,170 @@
<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>
Notification types are in
<literal><replaceable>class.specific</replaceable></literal> form.
<literal>class</literal> specifies the generic type of notification, and
<literal>specific</literal> specifies the more specific type of
notification.
</para>
<para>
If a specific type of notification does not exist for your notification,
but the generic kind does, a notification of type
<literal><replaceable>class</replaceable></literal> is acceptable.
</para>
<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>class</replaceable>.<replaceable>name</replaceable></literal>."
</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>"device"</literal></entry>
<entry>
A generic device-related notification that doesn't fit into
any other category.
</entry>
</row>
<row>
<entry><literal>"device.added"</literal></entry>
<entry>A device, such as a USB device, was added to the system.</entry>
</row>
<row>
<entry><literal>"device.error"</literal></entry>
<entry>A device had some kind of error.</entry>
</row>
<row>
<entry><literal>"device.removed"</literal></entry>
<entry>
A device, such as a USB device, was removed from the system.
</entry>
</row>
<row>
<entry><literal>"email"</literal></entry>
<entry>
A generic e-mail-related notification that doesn't fit into any
other category.
</entry>
</row>
<row>
<entry><literal>"email.arrived"</literal></entry>
<entry>A new e-mail notification.</entry>
</row>
<row>
<entry><literal>"email.bounced"</literal></entry>
<entry>A notification stating that an e-mail has bounced.</entry>
</row>
<row>
<entry><literal>"im"</literal></entry>
<entry>
A generic instant message-related notification that doesn't fit
into any other category.
</entry>
</row>
<row>
<entry><literal>"im.error"</literal></entry>
<entry>An instant message error notification.</entry>
</row>
<row>
<entry><literal>"im.received"</literal></entry>
<entry>A received instant message notification.</entry>
</row>
<row>
<entry><literal>"network"</literal></entry>
<entry>
A generic network notification that doesn't fit into any other
category.
</entry>
</row>
<row>
<entry><literal>"network.connected"</literal></entry>
<entry>
A network connection notification, such as successful sign-on to a
network service. This should not be confused with
<literal>device.added</literal> for new network devices.
</entry>
</row>
<row>
<entry><literal>"network.disconnected"</literal></entry>
<entry>
A network disconnected notification. This should not be confused with
<literal>device.removed</literal> for disconnected network devices.
</entry>
</row>
<row>
<entry><literal>"network.error"</literal></entry>
<entry>
A network-related or connection-related error.
</entry>
</row>
<row>
<entry><literal>"presence"</literal></entry>
<entry>
A generic presence change notification that doesn't fit into
any other category, such as going away or idle.
</entry>
</row>
<row>
<entry><literal>"presence.offline"</literal></entry>
<entry>An offline presence change notification.</entry>
</row>
<row>
<entry><literal>"presence.online"</literal></entry>
<entry>An online presence change notification.</entry>
</row>
<row>
<entry><literal>"transfer"</literal></entry>
<entry>
A generic file transfer or download notification that doesn't fit
into any other category.
</entry>
</row>
<row>
<entry><literal>"transfer.complete"</literal></entry>
<entry>A file transfer or download complete notification.</entry>
</row>
<row>
<entry><literal>"transfer.error"</literal></entry>
<entry>A file transfer or download error.</entry>
</row>
</tbody>
</tgroup>
</table>
</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
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.
</para>
<para>Urgency levels are defined as follows:</para>
@ -385,8 +617,8 @@
<tgroup cols="2">
<thead>
<row>
<entry>Level</entry>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody valign="top">
@ -396,14 +628,10 @@
</row>
<row>
<entry>1</entry>
<entry>Medium (Normal)</entry>
<entry>Normal</entry>
</row>
<row>
<entry>2</entry>
<entry>High</entry>
</row>
<row>
<entry>3</entry>
<entry>Critical</entry>
</row>
</tbody>
@ -416,10 +644,15 @@
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.
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.
</para>
<para>
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.
</para>
</sect1>
@ -427,15 +660,24 @@
<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. One such example would be the
window ID.
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>
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>
<para>
The following table lists the standard hints as defined by this
specification. Future hints may be proposed and added to this list
@ -453,28 +695,15 @@
</thead>
<tbody valign="top">
<row>
<entry><literal>"winid"</literal></entry>
<entry>UINT32</entry>
<entry><literal>"soundfile"</literal></entry>
<entry>string</entry>
<entry>
The Window ID that sent the notification. This may be used,
for example, to flash the window.
The path to a sound file to play when the notification pops up.
</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">
@ -509,6 +738,14 @@
<title>Server Capabilities</title>
<tgroup cols="2">
<tbody valign="top">
<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>
<row>
<entry><literal>"body"</literal></entry>
<entry>
@ -517,7 +754,19 @@
</entry>
</row>
<row>
<entry><literal>"markup"</literal></entry>
<entry><literal>"body-hyperlinks"</literal></entry>
<entry>
The server supports hyperlinks in the notifications.
</entry>
</row>
<row>
<entry><literal>"body-images"</literal></entry>
<entry>
The server supports images in the notifications.
</entry>
</row>
<row>
<entry><literal>"body-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
@ -525,29 +774,21 @@
</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><literal>"icon-multi"</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.
this cap and/or <literal>"icon-static"</literal> 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><literal>"icon-static"</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.
Supports display of exactly 1 frame of any given image array.
This value is mutually exclusive with
<literal>"icon-multi"</literal>, it is a protocol error for the
server to specify both.
</entry>
</row>
</tbody>
@ -579,7 +820,8 @@
<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>
<paramdef>BOOL <parameter>expires</parameter></paramdef>
<paramdef>UINT32 <parameter>expire_timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@ -674,15 +916,27 @@
</entry>
</row>
<row>
<entry><parameter>expire_time</parameter></entry>
<entry>UINT32 or NIL</entry>
<entry><parameter>expires</parameter></entry>
<entry>BOOL</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.
A boolean flag indicating whether or not this notification should
automatically expire.
</entry>
</row>
<row>
<entry><parameter>expire_timeout</parameter></entry>
<entry>UINT32</entry>
<entry>
<para>
The timeout time in seconds since the display of the notification at
which the notification should automatically close. This is ignored
if the expires flag is set to false.
</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>