From 4188fb54d32b4c35c248154ab30693c07003a9c3 Mon Sep 17 00:00:00 2001 From: Christian Hammond Date: Wed, 1 Sep 2004 07:41:05 +0000 Subject: [PATCH] Moved specification and ChangeLog documentation. --- ChangeLog | 7 + SPECIFICATION | 367 +------------------------------------------------- 2 files changed, 9 insertions(+), 365 deletions(-) diff --git a/ChangeLog b/ChangeLog index 19fd5e7..3113e39 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Wed Sep 01 00:39:23 PDT 2004 Christian Hammond + + * docs/ChangeLog: + * SPECIFICATION: + - Moved specification documentation. + - Moved specification ChangeLog. + Wed Sep 01 00:30:53 PDT 2004 Christian Hammond * docs/notification-spec.xml: diff --git a/SPECIFICATION b/SPECIFICATION index 91e3798..06563f2 100644 --- a/SPECIFICATION +++ b/SPECIFICATION @@ -1,366 +1,3 @@ -FreeDesktop proposed notifications spec -======================================= - -(c) 2004 Mike Hearn - 2004 Christian Hammond - -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: - -- ... - Bold -- ... - Italic -- ... - Underline -- ... - 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.