From 63480ac2bd2d0cb770c228c076ec5ad247d5ddb7 Mon Sep 17 00:00:00 2001 From: Christian Hammond Date: Wed, 11 Aug 2004 09:27:00 +0000 Subject: [PATCH] Many sections need to be filled out, but I've updated the notification spec a little to add some things I feel should be in there. I'll try to get to the details later, but I'm packing and getting ready to move. --- SPECIFICATION | 85 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 19 deletions(-) diff --git a/SPECIFICATION b/SPECIFICATION index 8c2f2f0..91e3798 100644 --- a/SPECIFICATION +++ b/SPECIFICATION @@ -10,7 +10,7 @@ v0.1: * Initial version v0.2: * Add replaces field to protocol - + --------------------------------------------------------------------- OVERVIEW @@ -55,6 +55,22 @@ 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 @@ -74,7 +90,7 @@ A notification has the following components: - An optional sound: See the ICONS/SOUNDS section below. -- An array of actions. The actions send a request message back to the +- 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 @@ -82,13 +98,15 @@ A notification has the following components: 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. + notification. The expiration time should be respected by implementations, but this is not required (this is for compatibility with KNotify). @@ -106,11 +124,9 @@ a notification while it's on-screen. BACKWARDS COMPATIBILITY -Prior art in this area is basically just the KNotify system. This -specification strives to be compatible with KNotify, however there is -still some semantic mismatch. 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 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. @@ -119,10 +135,6 @@ 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. -FIXME: is this enough? is it even worth trying to be compatible with -KNotify given how different these systems are? Might just be easier to -implement this protocol in KNotify itself as a separate thing. - MARKUP @@ -136,6 +148,8 @@ The following tags can optionally be supported: - ... - Underline - ... - Hyperlink +TODO: What else do we want here? + ICONS/SOUNDS @@ -170,6 +184,22 @@ types can be one of the following: 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. @@ -193,7 +223,7 @@ The following messages must be supported by all implementations. 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 @@ -219,17 +249,29 @@ The following messages must be supported by all implementations. 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 + 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. @@ -246,11 +288,16 @@ The following messages must be supported by all implementations. 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