Moved specification and ChangeLog documentation.
This commit is contained in:
Christian Hammond
parent
bed9226908
commit
4188fb54d3
|
|
@ -1,3 +1,10 @@
|
|||
Wed Sep 01 00:39:23 PDT 2004 Christian Hammond <chipx86@gnupdate.org>
|
||||
|
||||
* docs/ChangeLog:
|
||||
* SPECIFICATION:
|
||||
- Moved specification documentation.
|
||||
- Moved specification ChangeLog.
|
||||
|
||||
Wed Sep 01 00:30:53 PDT 2004 Christian Hammond <chipx86@gnupdate.org>
|
||||
|
||||
* docs/notification-spec.xml:
|
||||
|
|
|
|||
367
SPECIFICATION
367
SPECIFICATION
|
|
@ -1,366 +1,3 @@
|
|||
FreeDesktop proposed notifications spec
|
||||
=======================================
|
||||
|
||||
(c) 2004 Mike Hearn <mike@navi.cx>
|
||||
2004 Christian Hammond <chipx86@chipx86.com>
|
||||
|
||||
ChangeLog:
|
||||
|
||||
v0.1:
|
||||
* Initial version
|
||||
v0.2:
|
||||
* Add replaces field to protocol
|
||||
|
||||
---------------------------------------------------------------------
|
||||
|
||||
OVERVIEW
|
||||
|
||||
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.
|
||||
|
||||
This specification explicitly does not include other types of
|
||||
notification presentation such as modal message boxes, window manager
|
||||
decorations or window list annotations.
|
||||
|
||||
Example use cases include:
|
||||
|
||||
* Presence changes in IM programs: for instance, MSN Messenger on
|
||||
Windows pioneered the use of passive popups to indicate presence
|
||||
changes.
|
||||
|
||||
* New mail notification
|
||||
|
||||
* Low disk space/battery warnings
|
||||
|
||||
|
||||
|
||||
BASIC DESIGN
|
||||
|
||||
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 DBUS interface.
|
||||
|
||||
On startup, a conforming implementation should take the
|
||||
"org.freedesktop.Notifications" 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.
|
||||
|
||||
The server should implement the "org.freedesktop.Notifications" interface on
|
||||
an object with the path "/org/freedesktop/Notifications". This is the
|
||||
only interface required by this version of the specification.
|
||||
|
||||
A notification has the following components:
|
||||
|
||||
- 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.
|
||||
|
||||
- Application icon: An optional byte array containing the application's icon.
|
||||
This should be in PNG or GIF formats.
|
||||
|
||||
- Replaces ID: An optional ID of an existing notification that this
|
||||
notification is intended to replace.
|
||||
|
||||
- Notification Type ID: An optional ID representing the notification type.
|
||||
See the NOTIFICATION TYPES section below.
|
||||
|
||||
- Urgency level: The urgency of the notification. See the URGENCY LEVELS
|
||||
section below.
|
||||
|
||||
- A summary: This is a single line overview of the notification. For
|
||||
instance "You have mail" or "A friend has come online". Tip: 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.
|
||||
|
||||
- An optional body: 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.
|
||||
|
||||
The text may contain simple markup as specified in the MARKUP
|
||||
section below. It must be encoded using UTF-8.
|
||||
|
||||
If the body is omitted just the summary is displayed.
|
||||
|
||||
- An optional array of images: See the ICONS/SOUNDS section below.
|
||||
|
||||
- An optional sound: See the ICONS/SOUNDS section below.
|
||||
|
||||
- An dictionary of actions. 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 the PROTOCOL section). 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.
|
||||
|
||||
- An optional dictionary of hints: See the HINTS section below.
|
||||
|
||||
- An expiration time: the timestamp in seconds since the epoch that the
|
||||
notification should close. If one wishes to have an expiration of 5 seconds
|
||||
from now, they must grab the current timestamp and add 5 seconds to it.
|
||||
|
||||
If zero, the notification's expiration time is dependent on the
|
||||
notification server's settings, and may vary for the type of
|
||||
notification.
|
||||
|
||||
The expiration time should be respected by implementations, but this is
|
||||
not required (this is for compatibility with KNotify).
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
BACKWARDS COMPATIBILITY
|
||||
|
||||
Clients should try and avoid making assumptions about the presentation and
|
||||
abilities of the notification server. The message content is the most
|
||||
important thing.
|
||||
|
||||
Clients can check with the server what capabilities are supported
|
||||
using the GetCapabilities message. See the PROTOCOL section.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
MARKUP
|
||||
|
||||
Description text may contain markup. The markup is XML-based, and consists
|
||||
of a small subset of HTML along with a few additional tags.
|
||||
|
||||
The following tags can optionally be supported:
|
||||
|
||||
- <b>...</b> - Bold
|
||||
- <i>...</i> - Italic
|
||||
- <u>...</u> - Underline
|
||||
- <a href="...">...</a> - Hyperlink
|
||||
|
||||
TODO: What else do we want here?
|
||||
|
||||
|
||||
ICONS/SOUNDS
|
||||
|
||||
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
|
||||
image/sound data, and implementations that support images may not
|
||||
support animation.
|
||||
|
||||
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
|
||||
KNotify bridge), only the primary frame will be used.
|
||||
|
||||
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:
|
||||
|
||||
* [string] Icon theme name. Any string that does not begin with the /
|
||||
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.
|
||||
|
||||
* [string] Absolute path. Any string that begins with a / will be
|
||||
used as an absolute file path. Implementations should support at
|
||||
minimum files of type image/png and image/svg.
|
||||
|
||||
* [binary] A data stream may be embedded in the message. This is
|
||||
assumed to be of type image/png.
|
||||
|
||||
A sound can be specified, this will be played by the notification
|
||||
server when the notification is displayed. FIXME: elaborate here.
|
||||
|
||||
|
||||
NOTIFICATION TYPES:
|
||||
|
||||
Write me.
|
||||
|
||||
|
||||
URGENCY LEVELS:
|
||||
|
||||
Write me.
|
||||
|
||||
|
||||
HINTS:
|
||||
|
||||
Write me.
|
||||
|
||||
|
||||
PROTOCOL
|
||||
|
||||
The following messages must be supported by all implementations.
|
||||
|
||||
* GetCapabilities
|
||||
|
||||
This message takes no parameters.
|
||||
|
||||
It returns an array of strings. Each string describes an optional
|
||||
capability implemented by the server. The following values are
|
||||
defined by this spec:
|
||||
|
||||
"body": Supports body text. Some implementations may only show the
|
||||
summary (for instance, onscreen displays, marquee/scrollers)
|
||||
|
||||
"markup": 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.
|
||||
|
||||
"static-image" : Supports display of exactly 1 frame of any given
|
||||
image array. This value is mutually exclusive with
|
||||
"multi-image", it is a protocol error for the
|
||||
server to specify both.
|
||||
|
||||
"multi-image": 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.
|
||||
|
||||
"sound": 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.
|
||||
|
||||
"actions": 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.
|
||||
|
||||
New vendor-specific caps may be specified as long as they start with
|
||||
"x-vendorname", so for instance "x-gnome-foo-cap". Caps may not
|
||||
contain spaces in their names (FIXME: this feels right but is it
|
||||
really necessary?)
|
||||
|
||||
* Notify
|
||||
|
||||
This message requires the following parameters in the exact order
|
||||
shown. For some parameters multiple types may be acceptable
|
||||
|
||||
STRING/NIL application name: the name of the application sending the
|
||||
notification.
|
||||
|
||||
BYTE ARRAY/NIL application icon: the optional icon for the calling
|
||||
application.
|
||||
|
||||
UINT32 replaces: if non-zero this is the 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.
|
||||
|
||||
STRING/NIL notification type: the type ID of the notification, for
|
||||
potential server categorization and logging purposes. See the
|
||||
NOTIFICATION TYPES section.
|
||||
|
||||
BYTE urgency: The urgency level:
|
||||
0 - low urgency
|
||||
1 - medium
|
||||
2 - high
|
||||
3 - critical
|
||||
|
||||
See the URGENCY LEVELS section for more information.
|
||||
|
||||
Other values should be treated as "medium" in this version of the spec.
|
||||
|
||||
STRING summary
|
||||
|
||||
STRING/NIL body: if nil the body is considered omitted.
|
||||
|
||||
ARRAY images: the array may be empty.
|
||||
|
||||
STRING/NIL sound: if nil the sound is considered omitted.
|
||||
|
||||
DICT actions: each dictionary key is the localized name of the
|
||||
action, and each key maps to a UINT32 containing an action
|
||||
code. This code will be reported back to the client if the action
|
||||
is invoked by the user.
|
||||
|
||||
DICT hints: optional hints that can be passed to the server from the
|
||||
client. Although clients and servers should never assume to support such
|
||||
hints, they can be used to pass along information such as the process
|
||||
PID or window ID. See the HINTS section.
|
||||
|
||||
UINT32/NIL expire time: if nil the notification never times out.
|
||||
If non-nil, a UNIX time_t (since the epoch) at which point the notification
|
||||
will be automatically closed. If zero, use the default server timeout.
|
||||
|
||||
|
||||
If replaces is NIL, return is a UINT32 that will never be reused
|
||||
within a session unless more than MAXINT notifications have been
|
||||
generated (ie an acceptable implementation for this is just an
|
||||
incrementing counter). The returned UINT32 will never be zero, as
|
||||
this is an invalid ID.
|
||||
|
||||
If replaces is not NIL, return is the same as replaces.
|
||||
|
||||
* CloseNotification
|
||||
|
||||
This message indicates that the notification should be removed from
|
||||
the users view. It can be used, for instance, if the event the
|
||||
notification pertains to is no longer relevant or to cancel a
|
||||
notification with no expiration. It takes one UINT32 parameter, the ID
|
||||
of the notificaton to cancel. The NotificationClosed signal is emitted by this
|
||||
method.
|
||||
|
||||
* GetServerInformation
|
||||
|
||||
This message takes no parameters, and returns the following values in an array:
|
||||
|
||||
STRING name: the product name of the server
|
||||
STRING vendor: "kde"/"freedesktop.org"/"Microsoft" etc etc
|
||||
STRING version: a version spec of arbitrary format
|
||||
|
||||
All implementations must emit the following signals:
|
||||
|
||||
* NotificationClosed
|
||||
|
||||
A completed notification is one that has timed out, or been
|
||||
dismissed by the user.
|
||||
|
||||
Has two parameters:
|
||||
|
||||
* UINT32 id: containing the ID of the notification that was
|
||||
completed.
|
||||
* UINT32 reason: 1 for expires, 2 for being dismissed by the user,
|
||||
3 for "other".
|
||||
|
||||
The ID specified in the signal is invalidated *before* the signal
|
||||
is sent and may not be used in any further communications with the
|
||||
server.
|
||||
|
||||
The following signals MAY be emitted by the server.
|
||||
|
||||
* Invoked
|
||||
|
||||
This signal is emitted when:
|
||||
|
||||
- The user performs some global "invoking" action upon a notification,
|
||||
for instance by clicking on its graphical representation
|
||||
- The user invokes a specific action as specified in the original
|
||||
Notify request, for example by clicking on the action button.
|
||||
|
||||
ActionInvoked has two parameters:
|
||||
|
||||
* UINT32 id: The ID of the notification containing the invoked action.
|
||||
|
||||
* UINT32 action_id: Zero means the default invoke action that can be
|
||||
performed on any notification. 1+ is the index in
|
||||
the actions array originally specified.
|
||||
|
||||
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.
|
||||
This document has moved.
|
||||
|
||||
Please see docs/ for the new version of the specification.
|
||||
|
|
|
|||
Loading…
Reference in New Issue