+++ /dev/null
- Desktop Notifications Specification
-
- Mike Hearn
-
- <[1]mike@navi.cx>
-
-
- Christian Hammond
-
- <[2]chipx86@chipx86.com>
-
-
- Version 0.9
-
- Revision History
- Revision 0.9 15 January 2006 Revised by: cdh
- Clarify the naming for the application IDs. Put back a number of things
- that probably shouldn't have been removed from the spec.
- Revision 0.8 23 September 2005 Revised by: J5
- Major overhaul of spec to work with the newer D-Bus recursive type system.
- Simplify protocol. Changed the verbage notification type to category
- Revision 0.7 28 July 2005 Revised by: cdh
- Added "x" and "y" hints. Talk about the variant type for hint values.
- Revision 0.6 1 April 2005 Revised by: cdh
- Updated to work with D-BUS 0.31+.
- Revision 0.5 2 October 2004 Revised by: cdh
- Added a "suppress-sound" hint. Added a "sound" capability. Renamed the
- "soundfile" hint to sound-file".
- Revision 0.4 29 September 2004 Revised by: cdh
- Added image support in markup, and made the restrictions on markup more
- clear. Removed the High urgency. Added new notification types. Fixed
- notification expiration.
- Revision 0.3 15 September 2004 Revised by: cdh
- Added hint and notification type sections
- Revision 0.2 foo Revised by: mh
- Added replaces field to protocol
- Revision 0.1 foo Revised by: mh
- Initial version
-
- --------------------------------------------------------------------------
-
- Table of Contents
-
- 1. [3]Introduction
-
- 2. [4]Basic Design
-
- 3. [5]Backwards Compatibility
-
- 4. [6]Markup
-
- 4.1. [7]Hyperlinks
-
- 4.2. [8]Images
-
- 5. [9]Icons
-
- 6. [10]Categories
-
- 7. [11]Urgency Levels
-
- 8. [12]Hints
-
- 9. [13]D-BUS Protocol
-
- 9.1. [14]Message commands
-
- 9.1.1.
- [15]org.freedesktop.Notifications.GetCapabilities
-
- 9.1.2. [16]org.freedesktop.Notifications.Notify
-
- 9.1.3.
- [17]org.freedesktop.Notifications.CloseNotification
-
- 9.1.4.
- [18]org.freedesktop.Notifications.GetServerInformation
-
- 9.2. [19]Signals
-
- 9.2.1.
- [20]org.freedesktop.Notifications.NotificationClosed
-
- 9.2.2.
- [21]org.freedesktop.Notifications.ActionInvoked
-
-1. Introduction
-
- 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.
-
- * Scheduled alarm
-
- * Completed file transfer
-
- * New mail notification
-
- * Low disk space/battery warnings
-
- --------------------------------------------------------------------------
-
-2. 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 D-BUS
- 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:
-
- Table 1. Notification Components
-
- +------------------------------------------------------------------------+
- | Component | Description |
- |--------------------+---------------------------------------------------|
- | | This is the optional name of the application |
- | | sending the notification. This should be the |
- | Application Name | application's formal name, rather than some sort |
- | | of ID. An example would be "FredApp E-Mail |
- | | Client," rather than "fredapp-email-client." |
- |--------------------+---------------------------------------------------|
- | Replaces ID | An optional ID of an existing notification that |
- | | this notification is intended to replace. |
- |--------------------+---------------------------------------------------|
- | | The notification icon. This is represented |
- | | either as a URI (file:// is the only URI schema |
- | Notification Icon | supported right now) or a name in a |
- | | freedesktop.org-compliant icon theme (not a GTK+ |
- | | stock ID). |
- |--------------------+---------------------------------------------------|
- | | This is a single line overview of the |
- | | notification. For instance, "You have mail" or "A |
- | | friend has come online". It should generally not |
- | Summary | 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. |
- |--------------------+---------------------------------------------------|
- | | |
- | | |
- | | 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. |
- | Body | |
- | | The body may contain simple markup as specified |
- | | in [22]Markup. It must be encoded using UTF-8. |
- | | |
- | | If the body is omitted, just the summary is |
- | | displayed. |
- |--------------------+---------------------------------------------------|
- | | |
- | | |
- | | 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 [23]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 |
- | Actions | notification popup. |
- | | |
- | | Actions are sent over as a list of pairs. Each |
- | | even element in the list (starting at index 0) |
- | | represents the identifier for the action. Each |
- | | odd element in the list is the localized string |
- | | that will be displayed to the user. |
- | | |
- | | The default action (usually invoked my clicking |
- | | the notification) should have a key named |
- | | "default". The name can be anything, though |
- | | implementations are free not to display it. |
- |--------------------+---------------------------------------------------|
- | | |
- | | |
- | | See [24]Hints. |
- | | |
- | | Beyond the core protocol is the hints table. A |
- | | couple of core elements have been moved to hints |
- | | mostly because in a huge number of cases their |
- | | default values would be sufficient. The elements |
- | | moved to hints are: |
- | | |
- | | Elements Moved to Hints |
- | | |
- | | Element: Category ID |
- | | |
- | Hints | Description: An optional ID representing the type |
- | | of notification (the name has been changed from |
- | | Notification Type ID in pervious versions). See |
- | | [25]Categories. |
- | | |
- | | Element: Urgency Level |
- | | |
- | | Description: The urgency of the notification. See |
- | | [26]Urgency Levels. (Defaults to 1 - Normal) |
- | | |
- | | Element: Icon Data |
- | | |
- | | Description: Instead of overloading the icon |
- | | field we now have an icon_data field that is used |
- | | when icon is blank. |
- |--------------------+---------------------------------------------------|
- | | |
- | | |
- | | The timeout time in milliseconds since the |
- | | display of the notification at which the |
- | | notification should automatically close. |
- | Expiration Timeout | |
- | | If -1, the notification's expiration time is |
- | | dependent on the notification server's settings, |
- | | and may vary for the type of notification. |
- | | |
- | | If 0, the notification never expires. |
- +------------------------------------------------------------------------+
-
- 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 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.
-
- --------------------------------------------------------------------------
-
-3. 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 [27]Protocol.
-
- 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 in the case that
- the notification server does not support this feature.
-
- --------------------------------------------------------------------------
-
-4. Markup
-
- Body 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 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.
-
- +------------------------------------------+
- | <b> ... </b> | Bold |
- |------------------------------+-----------|
- | <i> ... </i> | Italic |
- |------------------------------+-----------|
- | <u> ... </u> | Underline |
- |------------------------------+-----------|
- | <a href="..."> ... </a> | Hyperlink |
- |------------------------------+-----------|
- | <img src="..." alt="..."/> | Image |
- +------------------------------------------+
-
- 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.
-
- 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.
-
- 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.
-
- --------------------------------------------------------------------------
-
- 4.1. Hyperlinks
-
- 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.
-
- Hyperlinked text should appear in the standard blue underline format.
-
- Hyperlinks cannot function as a replacement for actions. They are used
- to link to local directories or remote sites using standard URI schemes.
-
- Implementations are not required to support hyperlinks.
-
- --------------------------------------------------------------------------
-
- 4.2. Images
-
- 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 alt="..." attribute.
-
- Image data cannot be embedded in the message itself. Images referenced
- must always be local files.
-
- Implementations are not required to support images.
-
- --------------------------------------------------------------------------
-
-5. Icons
-
- A notification can optionally have an icon specified by the Notification
- Icon field or by the icon_data hint.
-
- The icon_data field should be a raw image data structure of signature
- (iiibiiay) which describes the width, height, rowstride, has alpha, bits
- per sample, channels and image data respectively.
-
- --------------------------------------------------------------------------
-
-6. Categories
-
- Notifications can optionally have a type indicator. Although neither
- client or nor server must support this, some may choose to. Those servers
- implementing categories may use them to intelligently display the
- notification in a certain way, or group notifications of similar types.
-
- Categories are in class.specific form. class specifies the generic type
- of notification, and specific specifies the more specific type of
- notification.
-
- If a specific type of notification does not exist for your notification,
- but the generic kind does, a notification of type class is acceptable.
-
- Third parties, when defining their own categories, should discuss the
- possibility of standardizing on the hint with other parties, preferably in
- a place such as the [28]xdg mailing list at [29]freedesktop.org. If it
- warrants a standard, it will be added to the table above. If no consensus
- is reached, the category should be in the form of "x-vendor.class.name."
-
- The following table lists standard notifications as defined by this
- spec. More will be added in time.
-
- Table 2. Categories
-
- +------------------------------------------------------------------------+
- | Type | Description |
- |------------------------+-----------------------------------------------|
- | "device" | A generic device-related notification that |
- | | doesn't fit into any other category. |
- |------------------------+-----------------------------------------------|
- | "device.added" | A device, such as a USB device, was added to |
- | | the system. |
- |------------------------+-----------------------------------------------|
- | "device.error" | A device had some kind of error. |
- |------------------------+-----------------------------------------------|
- | "device.removed" | A device, such as a USB device, was removed |
- | | from the system. |
- |------------------------+-----------------------------------------------|
- | "email" | A generic e-mail-related notification that |
- | | doesn't fit into any other category. |
- |------------------------+-----------------------------------------------|
- | "email.arrived" | A new e-mail notification. |
- |------------------------+-----------------------------------------------|
- | "email.bounced" | A notification stating that an e-mail has |
- | | bounced. |
- |------------------------+-----------------------------------------------|
- | | A generic instant message-related |
- | "im" | notification that doesn't fit into any other |
- | | category. |
- |------------------------+-----------------------------------------------|
- | "im.error" | An instant message error notification. |
- |------------------------+-----------------------------------------------|
- | "im.received" | A received instant message notification. |
- |------------------------+-----------------------------------------------|
- | "network" | A generic network notification that doesn't |
- | | fit into any other category. |
- |------------------------+-----------------------------------------------|
- | | A network connection notification, such as |
- | "network.connected" | successful sign-on to a network service. This |
- | | should not be confused with device.added for |
- | | new network devices. |
- |------------------------+-----------------------------------------------|
- | | A network disconnected notification. This |
- | "network.disconnected" | should not be confused with device.removed |
- | | for disconnected network devices. |
- |------------------------+-----------------------------------------------|
- | "network.error" | A network-related or connection-related |
- | | error. |
- |------------------------+-----------------------------------------------|
- | | A generic presence change notification that |
- | "presence" | doesn't fit into any other category, such as |
- | | going away or idle. |
- |------------------------+-----------------------------------------------|
- | "presence.offline" | An offline presence change notification. |
- |------------------------+-----------------------------------------------|
- | "presence.online" | An online presence change notification. |
- |------------------------+-----------------------------------------------|
- | | A generic file transfer or download |
- | "transfer" | notification that doesn't fit into any other |
- | | category. |
- |------------------------+-----------------------------------------------|
- | "transfer.complete" | A file transfer or download complete |
- | | notification. |
- |------------------------+-----------------------------------------------|
- | "transfer.error" | A file transfer or download error. |
- +------------------------------------------------------------------------+
-
- --------------------------------------------------------------------------
-
-7. Urgency Levels
-
- Notifications have an urgency level associated with them. This defines
- 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.
-
- Urgency levels are defined as follows:
-
- Table 3. Urgency Levels
-
- +--------------------+
- | Type | Description |
- |------+-------------|
- | 0 | Low |
- |------+-------------|
- | 1 | Normal |
- |------+-------------|
- | 2 | Critical |
- +--------------------+
-
- Developers must use their own judgement when deciding the urgency of a
- notification. Typically, if the majority of programs are using the same
- level for a specific type of urgency, other applications should follow
- 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.
-
- 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.
-
- --------------------------------------------------------------------------
-
-8. Hints
-
- Hints are a way to provide extra data to a notification server that the
- server may be able to make use of.
-
- 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.
-
- 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 [30]xdg mailing list at [31]freedesktop.org. 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 "x-vendor-name."
-
- The value type for the hint dictionary in D-BUS is of the
- DBUS_TYPE_VARIANT container type. This allows different data types
- (string, integer, boolean, etc.) to be used for hints. When adding a
- dictionary of hints, this type must be used, rather than putting the
- actual hint value in as the dictionary value.
-
- The following table lists the standard hints as defined by this
- specification. Future hints may be proposed and added to this list over
- time. Once again, implementations are not required to support these.
-
- Table 4. Standard Hints
-
- +------------------------------------------------------------------------+
- | Name | Value Type | Description |
- |------------------+------------+----------------------------------------|
- | "urgency" | byte | The urgency level. |
- |------------------+------------+----------------------------------------|
- | "category" | string | The type of notification this is. |
- |------------------+------------+----------------------------------------|
- | | | This specifies the name of the |
- | | | desktop filename representing the |
- | | | calling program. This should be the |
- | | | same as the prefix used for the |
- | "desktop-entry"> | string | application's .desktop file. An |
- | | | example would be "rhythmbox" from |
- | | | "rhythmbox.desktop". This can be used |
- | | | by the daemon to retrieve the correct |
- | | | icon for the application, for logging |
- | | | purposes, etc. |
- |------------------+------------+----------------------------------------|
- | | | This is a raw data image format |
- | | | which describes the width, height, |
- | "image_data" | (iiibiiay) | rowstride, has alpha, bits per sample, |
- | | | channels and image data respectively. |
- | | | We use this value if the icon field is |
- | | | left blank. |
- |------------------+------------+----------------------------------------|
- | "sound-file" | string | The path to a sound file to play |
- | | | when the notification pops up. |
- |------------------+------------+----------------------------------------|
- | | | Causes the server to suppress |
- | | | playing any sounds, if it has that |
- | "suppress-sound" | boolean | ability. This is usually set when the |
- | | | client itself is going to play its own |
- | | | sound. |
- |------------------+------------+----------------------------------------|
- | | | Specifies the X location on the |
- | "x" | int | screen that the notification should |
- | | | point to. The "y" hint must also be |
- | | | specified. |
- |------------------+------------+----------------------------------------|
- | | | Specifies the Y location on the |
- | "y" | int | screen that the notification should |
- | | | point to. The "x" hint must also be |
- | | | specified. |
- +------------------------------------------------------------------------+
-
- --------------------------------------------------------------------------
-
-9. D-BUS Protocol
-
- The following messages must be supported by all implementations.
-
- --------------------------------------------------------------------------
-
- 9.1. Message commands
-
- 9.1.1. org.freedesktop.Notifications.GetCapabilities
-
- STRING_ARRAY org.freedesktop.Notifications.GetCapabilities (void);
-
- 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:
-
- Table 5. Server Capabilities
-
- +------------------------------------------------------------------------+
- | | The server will provide the specified actions to |
- | "actions" | 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 body text. Some implementations may |
- | "body" | only show the summary (for instance, onscreen |
- | | displays, marquee/scrollers) |
- |-------------------+----------------------------------------------------|
- | "body-hyperlinks" | The server supports hyperlinks in the |
- | | notifications. |
- |-------------------+----------------------------------------------------|
- | "body-images" | The server supports images in the notifications. |
- |-------------------+----------------------------------------------------|
- | | Supports markup in the body text. If marked up |
- | "body-markup" | 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. |
- |-------------------+----------------------------------------------------|
- | | The server will render an animation of all the |
- | | frames in a given image array. The client may |
- | "icon-multi" | still specify multiple frames even if this cap |
- | | and/or "icon-static" is missing, however the |
- | | server is free to ignore them and use only the |
- | | primary frame. |
- |-------------------+----------------------------------------------------|
- | | Supports display of exactly 1 frame of any given |
- | "icon-static" | image array. This value is mutually exclusive with |
- | | "icon-multi", it is a protocol error for the |
- | | server to specify both. |
- |-------------------+----------------------------------------------------|
- | | The server supports sounds on notifications. If |
- | "sound" | returned, the server must support the "sound-file" |
- | | and "suppress-sound" hints. |
- +------------------------------------------------------------------------+
-
- New vendor-specific caps may be specified as long as they start with
- "x-vendor". For instance, "x-gnome-foo-cap". Capability names must not
- contain spaces. They are limited to alpha-numeric characters and dashes
- ("-").
-
- --------------------------------------------------------------------------
-
- 9.1.2. org.freedesktop.Notifications.Notify
-
- UINT32 org.freedesktop.Notifications.Notify (STRING app_name, UINT32
- replaces_id, STRING app_icon, STRING summary, STRING body, ARRAY actions,
- DICT hints, INT32 expire_timeout);
-
- Sends a notification to the notification server.
-
- Table 6. Notify Parameters
-
- +------------------------------------------------------------------------+
- | Name | Type | Description |
- |----------------+--------+----------------------------------------------|
- | app_name | STRING | The optional name of the application |
- | | | sending the notification. Can be blank. |
- |----------------+--------+----------------------------------------------|
- | | | The optional notification ID that this |
- | | | notification replaces. The server must |
- | | | atomically (ie with no flicker or other |
- | | | visual cues) replace the given notification |
- | replaces_id | UINT32 | with this one. This allows clients to |
- | | | effectively modify the notification while |
- | | | it's active. A value of value of 0 means |
- | | | that this notification won't replace any |
- | | | existing notifications. |
- |----------------+--------+----------------------------------------------|
- | | | The optional program icon of the calling |
- | app_icon | STRING | application. See [32]Icons. Can be an empty |
- | | | string, indicating no icon. |
- |----------------+--------+----------------------------------------------|
- | summary | STRING | The summary text briefly describing the |
- | | | notification. |
- |----------------+--------+----------------------------------------------|
- | body | STRING | The optional detailed body text. Can be |
- | | | empty. |
- |----------------+--------+----------------------------------------------|
- | | | Actions are sent over as a list of pairs. |
- | | | Each even element in the list (starting at |
- | actions | ARRAY | index 0) represents the identifier for the |
- | | | action. Each odd element in the list is the |
- | | | localized string that will be displayed to |
- | | | the user. |
- |----------------+--------+----------------------------------------------|
- | | | Optional hints that can be passed to the |
- | | | server from the client program. Although |
- | | | clients and servers should never assume each |
- | hints | DICT | 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 |
- | | | [33]Hints. Can be empty. |
- |----------------+--------+----------------------------------------------|
- | | | |
- | | | |
- | | | The timeout time in milliseconds since the |
- | | | display of the notification at which the |
- | expire_timeout | INT32 | notification should automatically close. |
- | | | |
- | | | If -1, the notification's expiration time |
- | | | is dependent on the notification server's |
- | | | settings, and may vary for the type of |
- | | | notification. If 0, never expire. |
- +------------------------------------------------------------------------+
-
- If replaces_id is 0, the return value is a UINT32 that represent the
- notification. It is unique, and will not be reused unless a MAXINT 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.
-
- If replaces_id is not 0, the returned value is the same value as
- replaces_id.
-
- --------------------------------------------------------------------------
-
- 9.1.3. org.freedesktop.Notifications.CloseNotification
-
- void org.freedesktop.Notifications.CloseNotification (UINT32 id);
-
- 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 longer relevant, or to cancel a
- notification with no expiration time.
-
- The NotificationClosed signal is emitted by this method.
-
- If the notification no longer exists, an empty D-BUS Error message is
- sent back.
-
- --------------------------------------------------------------------------
-
- 9.1.4. org.freedesktop.Notifications.GetServerInformation
-
- void org.freedesktop.Notifications.GetServerInformation (out STRING
- name, out STRING vendor, out STRING version);
-
- This message returns the information on the server. Specifically, the
- server name, vendor, and version number.
-
- Table 7. GetServerInformation Return Values
-
- +------------------------------------------------------------------------+
- | Name | Type | Description |
- |---------+--------+-----------------------------------------------------|
- | name | STRING | The product name of the server. |
- |---------+--------+-----------------------------------------------------|
- | vendor | STRING | The vendor name. For example, "KDE," "GNOME," |
- | | | "freedesktop.org," or "Microsoft." |
- |---------+--------+-----------------------------------------------------|
- | version | STRING | The server's version number. |
- +------------------------------------------------------------------------+
-
- --------------------------------------------------------------------------
-
- 9.2. Signals
-
- 9.2.1. org.freedesktop.Notifications.NotificationClosed
-
- org.freedesktop.Notifications.NotificationClosed (UINT32 id, UINT32
- reason);
-
- A completed notification is one that has timed out, or has been
- dismissed by the user.
-
- Table 8. NotificationClosed Parameters
-
- +------------------------------------------------------------------------+
- | Name | Type | Description |
- |--------+--------+------------------------------------------------------|
- | id | UINT32 | The ID of the notification that was closed. |
- |--------+--------+------------------------------------------------------|
- | | | |
- | | | |
- | | | The reason the notification was closed. |
- | | | |
- | | | 1 - The notification expired. |
- | reason | UINT32 | |
- | | | 2 - The notification was dismissed by the user. |
- | | | |
- | | | 3 - The notification was closed by a call to |
- | | | CloseNotification. |
- | | | |
- | | | 4 - Undefined/reserved reasons. |
- +------------------------------------------------------------------------+
-
- 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.
-
- --------------------------------------------------------------------------
-
- 9.2.2. org.freedesktop.Notifications.ActionInvoked
-
- org.freedesktop.Notifications.ActionInvoked (UINT32 id, STRING
- action_key);
-
- This signal is emitted when one of the following occurs:
-
- * The user performs some global "invoking" action upon a notification.
- For instance, clicking somewhere on the notification itself.
-
- * The user invokes a specific action as specified in the original
- Notify request. For example, clicking on an action button.
-
- Table 9. ActionInvoked Parameters
-
- +------------------------------------------------------------------------+
- | Name | Type | Description |
- |------------+--------+--------------------------------------------------|
- | id | UINT32 | The ID of the notification emitting the |
- | | | ActionInvoked signal. |
- |------------+--------+--------------------------------------------------|
- | action_key | STRING | The key of the action invoked. These match the |
- | | | keys sent over in the list of actions. |
- +------------------------------------------------------------------------+
-
- [34]Note 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.
-
-References
-
- Visible links
- 1. mailto:mike@navi.cx
- 2. mailto:chipx86@chipx86.com
- 3. file:///tmp/html-A2Tahl#introduction
- 4. file:///tmp/html-A2Tahl#basic-design
- 5. file:///tmp/html-A2Tahl#backwards-compat
- 6. file:///tmp/html-A2Tahl#markup
- 7. file:///tmp/html-A2Tahl#hyperlinks
- 8. file:///tmp/html-A2Tahl#images
- 9. file:///tmp/html-A2Tahl#icons
- 10. file:///tmp/html-A2Tahl#categories
- 11. file:///tmp/html-A2Tahl#urgency-levels
- 12. file:///tmp/html-A2Tahl#hints
- 13. file:///tmp/html-A2Tahl#protocol
- 14. file:///tmp/html-A2Tahl#commands
- 15. file:///tmp/html-A2Tahl#command-get-capabilities
- 16. file:///tmp/html-A2Tahl#command-notify
- 17. file:///tmp/html-A2Tahl#command-close-notification
- 18. file:///tmp/html-A2Tahl#command-get-server-information
- 19. file:///tmp/html-A2Tahl#signals
- 20. file:///tmp/html-A2Tahl#signal-notification-closed
- 21. file:///tmp/html-A2Tahl#signal-action-invoked
- 22. file:///tmp/html-A2Tahl#markup
- 23. file:///tmp/html-A2Tahl#protocol
- 24. file:///tmp/html-A2Tahl#hints
- 25. file:///tmp/html-A2Tahl#categories
- 26. file:///tmp/html-A2Tahl#urgency-levels
- 27. file:///tmp/html-A2Tahl#protocol
- 28. http://freedesktop.org/mailman/listinfo/xdg
- 29. http://freedesktop.org/
- 30. http://freedesktop.org/mailman/listinfo/xdg
- 31. http://freedesktop.org/
- 32. file:///tmp/html-A2Tahl#icons
- 33. file:///tmp/html-A2Tahl#hints
--- /dev/null
+<?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 1.2</releaseinfo>
+ <date>28 October 2010</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>
+ <author>
+ <firstname>William Jon</firstname>
+ <surname>McCann</surname>
+ <affiliation>
+ <address>
+ <email>jmccann@redhat.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ </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 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>Messages from chat programs</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 <literal>"/org/freedesktop/Notifications"</literal>.
+ This is the only interface required by this version of the specification.
+ </para>
+ <para>
+ A notification has the following components:
+ </para>
+ <table>
+ <title>Notification Components</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Component</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row>
+ <entry>Application Name</entry>
+ <entry>
+ 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. An example would be "FredApp E-Mail Client," rather than
+ "fredapp-email-client."
+ </entry>
+ </row>
+ <row>
+ <entry>Replaces ID</entry>
+ <entry>
+ An optional ID of an existing notification that this
+ notification is intended to replace.
+ </entry>
+ </row>
+ <row>
+ <entry>Notification Icon</entry>
+ <entry>
+ The notification icon. See <xref linkend="icons-and-images-formats"/>.
+ </entry>
+ </row>
+ <row>
+ <entry>Summary</entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+ <row>
+ <entry>Body</entry>
+ <entry>
+ <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 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.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>Actions</entry>
+ <entry>
+ <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>
+ <para>
+ Actions are sent over as a list of pairs. Each even element in the
+ list (starting at index 0) represents the identifier for the action.
+ Each odd element in the list is the localized string that will be
+ displayed to the user.
+ </para>
+ <para>
+ The default action (usually invoked my clicking the notification)
+ should have a key named <literal>"default"</literal>. The name can
+ be anything, though implementations are free not to display it.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>Hints</entry>
+ <entry>
+ <para>
+ Hints are a way to provide extra data to a notification server that
+ the server may be able to make use of.
+ </para>
+ <para>See <xref linkend="hints"/> for a list of available hints.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>Expiration Timeout</entry>
+ <entry>
+ <para>
+ The timeout time in milliseconds since the display of the notification
+ at which the notification should automatically close.
+ </para>
+ <para>
+ If -1, the notification's expiration time is dependent on the
+ notification server's settings, and may vary for the type of
+ notification.
+ </para>
+ <para>
+ If 0, the notification never expires.
+ </para>
+ </entry>
+ </row>
+ </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
+ 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 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.
+ </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 <literal>GetCapabilities</literal> 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 in the
+ case that the notification server does not support this feature.
+ </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 valign="top">
+ <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>
+ <row>
+ <entry>
+ <sgmltag class="emptytag">img src="..." alt="..."</sgmltag>
+ </entry>
+ <entry>Image</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ 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-and-images" xreflabel="Icons and Images">
+ <title>Icons and Images</title>
+ <para>
+ A notification can optionally have an associated icon and/or image.
+ </para>
+ <para>
+ The icon is defined by the "app_icon" parameter.
+ The image can be defined by the "image-path", the "image-data" hint or the
+ deprecated "icon_data" hint.
+ </para>
+ <sect2>
+ <title>Priorities</title>
+ <para>
+ An implementation which only displays one image or icon must choose which one
+ to display using the following order:
+ <orderedlist>
+ <listitem><para>"image-data"</para></listitem>
+ <listitem><para>"image-path"</para></listitem>
+ <listitem><para>app_icon parameter</para></listitem>
+ <listitem><para>for compatibility reason, "icon_data"</para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ An implementation which can display both the image and icon must show the
+ icon from the "app_icon" parameter and choose which image to display using
+ the following order:
+ <orderedlist>
+ <listitem><para>"image-data"</para></listitem>
+ <listitem><para>"image-path"</para></listitem>
+ <listitem><para>for compatibility reason, "icon_data"</para></listitem>
+ </orderedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="icons-and-images-formats" xreflabel="Icons and Images Formats">
+ <title>Formats</title>
+ <para>
+ The "image-data" and "icon_data" hints should be a DBus structure
+ of signature (iiibiiay). The components of this structure are as follows:
+ <orderedlist>
+ <listitem><para>width (i): Width of image in pixels</para></listitem>
+ <listitem><para>height (i): Height of image in pixels</para></listitem>
+ <listitem><para>rowstride (i): Distance in bytes between row starts</para></listitem>
+ <listitem><para>has_alpha (b): Whether the image has an alpha channel</para></listitem>
+ <listitem><para>bits_per_sample (i): Must always be 8</para></listitem>
+ <listitem><para>channels (i): If has_alpha is TRUE, must be 4, otherwise 3</para></listitem>
+ <listitem><para>data (ay): The image data, in RGB byte order</para></listitem>
+ </orderedlist>
+ This image format is derived from <ulink url="http://developer.gnome.org/gdk-pixbuf/stable/">gdk-pixbuf</ulink>.
+ </para>
+ <para>
+ The "app_icon" parameter and "image-path" hint should be either an URI
+ (file:// is the only URI schema supported right now) or a name in a
+ freedesktop.org-compliant icon theme (not a GTK+ stock ID).
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="categories" xreflabel="Categories">
+ <title>Categories</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 categories may use them to intelligently display
+ the notification in a certain way, or group notifications of similar
+ types.
+ </para>
+ <para>
+ Categories 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 categories, 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 category 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>Categories</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, "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>
+ <table>
+ <title>Urgency Levels</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row>
+ <entry>0</entry>
+ <entry>Low</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>Normal</entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>Critical</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Developers must use their own judgement when deciding the urgency of a
+ notification. Typically, if the majority of programs are using the same
+ level for a specific type of urgency, other applications should follow
+ them.
+ </para>
+ <para>
+ 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>
+
+ <sect1 id="hints" xreflabel="Hints">
+ <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.
+ </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 value type for the hint dictionary in D-BUS is of the
+ <literal>DBUS_TYPE_VARIANT</literal> container type. This allows different
+ data types (string, integer, boolean, etc.) to be used for hints. When
+ adding a dictionary of hints, this type must be used, rather than putting
+ the actual hint value in as the dictionary value.
+ </para>
+ <para>
+ The following table lists the standard hints as defined by this
+ specification. Future hints may be proposed and added to this list
+ over time. Once again, implementations are not required to support these.
+ </para>
+ <table>
+ <title>Standard Hints</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Value Type</entry>
+ <entry>Description</entry>
+ <entry>Spec Version</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row>
+ <entry><literal>"action-icons"</literal></entry>
+ <entry>boolean</entry>
+ <entry>
+ When set, a server that has the "action-icons" capability will
+ attempt to interpret any action identifier as a named icon.
+ The localized display name will be used to annotate the icon
+ for accessibility purposes. The icon name should be compliant
+ with the Freedesktop.org Icon Naming Specification.
+ </entry>
+ <entry>>= 1.2</entry>
+ </row>
+ <row>
+ <entry><literal>"category"</literal></entry>
+ <entry>string</entry>
+ <entry>
+ The type of notification this is.
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><literal>"desktop-entry"</literal></entry>
+ <entry>string</entry>
+ <entry>
+ This specifies the name of the desktop filename representing the
+ calling program. This should be the same as the prefix used for the
+ application's .desktop file. An example would be "rhythmbox" from
+ "rhythmbox.desktop". This can be used by the daemon to retrieve the
+ correct icon for the application, for logging purposes, etc.
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><literal>"image-data"</literal></entry>
+ <entry>(iiibiiay)</entry>
+ <entry>
+ This is a raw data image format which describes the width, height,
+ rowstride, has alpha, bits per sample, channels and image data
+ respectively.
+ </entry>
+ <entry>>= 1.2</entry>
+ </row>
+ <row>
+ <entry><literal>"image_data"</literal></entry>
+ <entry>(iiibiiay)</entry>
+ <entry>
+ <emphasis>Deprecated</emphasis>. Use image-data instead.
+ </entry>
+ <entry>= 1.1</entry>
+ </row>
+ <row>
+ <entry><literal>"image-path"</literal></entry>
+ <entry>string</entry>
+ <entry>
+ Alternative way to define the notification image. See <xref linkend="icons-and-images"/>.
+ </entry>
+ <entry>>= 1.2</entry>
+ </row>
+ <row>
+ <entry><literal>"image_path"</literal></entry>
+ <entry>string</entry>
+ <entry>
+ <emphasis>Deprecated</emphasis>. Use image-path instead.
+ </entry>
+ <entry>= 1.1</entry>
+ </row>
+ <row>
+ <entry><literal>"icon_data"</literal></entry>
+ <entry>(iiibiiay)</entry>
+ <entry>
+ <emphasis>Deprecated</emphasis>. Use image-data instead.
+ </entry>
+ <entry>< 1.1</entry>
+ </row>
+ <row>
+ <entry><literal>"resident"</literal></entry>
+ <entry>boolean</entry>
+ <entry>
+ When set the server will not automatically remove the
+ notification when an action has been invoked. The notification
+ will remain resident in the server until it is explicitly
+ removed by the user or by the sender. This hint is likely only
+ useful when the server has the "persistence" capability.
+ </entry>
+ <entry>>= 1.2</entry>
+ </row>
+ <row>
+ <entry><literal>"sound-file"</literal></entry>
+ <entry>string</entry>
+ <entry>
+ The path to a sound file to play when the notification pops up.
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><literal>"sound-name"</literal></entry>
+ <entry>string</entry>
+ <entry>
+ A themeable named sound from the freedesktop.org
+ <ulink url="http://0pointer.de/public/sound-naming-spec.html">sound naming specification</ulink>
+ to play when the notification pops up. Similar to icon-name, only for
+ sounds. An example would be "message-new-instant".
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><literal>"suppress-sound"</literal></entry>
+ <entry>boolean</entry>
+ <entry>
+ Causes the server to suppress playing any sounds, if it has that
+ ability. This is usually set when the client itself is going to
+ play its own sound.
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><literal>"transient"</literal></entry>
+ <entry>boolean</entry>
+ <entry>
+ When set the server will treat the notification as transient
+ and by-pass the server's persistence capability, if it should
+ exist.
+ </entry>
+ <entry>>= 1.2</entry>
+ </row>
+ <row>
+ <entry><literal>"x"</literal></entry>
+ <entry>int</entry>
+ <entry>
+ Specifies the X location on the screen that the notification should
+ point to. The <literal>"y"</literal> hint must also be specified.
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><literal>"y"</literal></entry>
+ <entry>int</entry>
+ <entry>
+ Specifies the Y location on the screen that the notification should
+ point to. The <literal>"x"</literal> hint must also be specified.
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><literal>"urgency"</literal></entry>
+ <entry>byte</entry>
+ <entry>
+ The urgency level.
+ </entry>
+ <entry/>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </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>
+ <table>
+ <title>Server Capabilities</title>
+ <tgroup cols="2">
+ <tbody valign="top">
+ <row>
+ <entry><literal>"action-icons"</literal></entry>
+ <entry>
+ Supports using icons instead of text for displaying actions.
+ Using icons for actions must be enabled on a per-notification
+ basis using the "action-icons" hint.
+ </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>
+ <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>"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
+ through as regular text so must be stripped clientside.
+ </entry>
+ </row>
+ <row>
+ <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 <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>"icon-static"</literal></entry>
+ <entry>
+ 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>
+ <row>
+ <entry><literal>"persistence"</literal></entry>
+ <entry>
+ The server supports persistence of notifications.
+ Notifications will be retained until they are acknowledged or
+ removed by the user or recalled by the sender. The presence
+ of this capability allows clients to depend on the server to
+ ensure a notification is seen and eliminate the need for
+ the client to display a reminding function (such as a status
+ icon) of its own.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>"sound"</literal></entry>
+ <entry>
+ The server supports sounds on notifications. If returned, the
+ server must support the <literal>"sound-file"</literal> and
+ <literal>"suppress-sound"</literal> hints.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ New vendor-specific caps may be specified as long as they start with
+ <literal>"x-<replaceable>vendor</replaceable>"</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 <parameter>app_name</parameter></paramdef>
+ <paramdef>UINT32 <parameter>replaces_id</parameter></paramdef>
+ <paramdef>STRING <parameter>app_icon</parameter></paramdef>
+ <paramdef>STRING <parameter>summary</parameter></paramdef>
+ <paramdef>STRING <parameter>body</parameter></paramdef>
+ <paramdef>ARRAY <parameter>actions</parameter></paramdef>
+ <paramdef>DICT <parameter>hints</parameter></paramdef>
+ <paramdef>INT32 <parameter>expire_timeout</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 valign="top">
+ <row>
+ <entry><parameter>app_name</parameter></entry>
+ <entry>STRING</entry>
+ <entry>
+ The optional name of the application sending the notification.
+ Can be blank.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>replaces_id</parameter></entry>
+ <entry>UINT32</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. A value of
+ value of 0 means that this notification won't replace any
+ existing notifications.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>app_icon</parameter></entry>
+ <entry>STRING</entry>
+ <entry>
+ The optional program icon of the calling application. See <xref linkend="icons-and-images"/>.
+ Can be an empty string, indicating no icon.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>summary</parameter></entry>
+ <entry>STRING</entry>
+ <entry>The summary text briefly describing the notification.</entry>
+ </row>
+ <row>
+ <entry><parameter>body</parameter></entry>
+ <entry>STRING</entry>
+ <entry>The optional detailed body text. Can be empty.</entry>
+ </row>
+ <row>
+ <entry><parameter>actions</parameter></entry>
+ <entry>ARRAY</entry>
+ <entry>
+ Actions are sent over as a list of pairs. Each even element in
+ the list (starting at index 0) represents the identifier for the
+ action. Each odd element in the list is the localized string
+ that will be displayed to the user.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>hints</parameter></entry>
+ <entry>DICT</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"/>. Can be
+ empty.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>expire_timeout</parameter></entry>
+ <entry>INT32</entry>
+ <entry>
+ <para>
+ The timeout time in milliseconds since the display of the notification at
+ which the notification should automatically close.
+ </para>
+ <para>
+ If -1, the notification's expiration time is dependent on the
+ notification server's settings, and may vary for the type of
+ notification.
+
+ If 0, never expire.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ If <parameter>replaces_id</parameter> is 0, 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 0, 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>void
+ <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 longer relevant, or to cancel a
+ notification with no expiration time.
+ </para>
+ <para>
+ The <literal>NotificationClosed</literal> signal is emitted by this
+ method.
+ </para>
+ <para>
+ If the notification no longer exists, an empty D-BUS Error message is
+ sent back.
+ </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>
+ <paramdef>out STRING <parameter>spec_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 valign="top">
+ <row>
+ <entry><parameter>name</parameter></entry>
+ <entry>STRING</entry>
+ <entry>The product name of the server.</entry>
+ </row>
+ <row>
+ <entry><parameter>vendor</parameter></entry>
+ <entry>STRING</entry>
+ <entry>
+ The vendor name. For example, "KDE," "GNOME,"
+ "freedesktop.org," or "Microsoft."
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>version</parameter></entry>
+ <entry>STRING</entry>
+ <entry>The server's version number.</entry>
+ </row>
+ <row>
+ <entry><parameter>spec_version</parameter></entry>
+ <entry>STRING</entry>
+ <entry>The specification version the server is compliant with.</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 Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <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 - The notification was closed by a call to
+ <literal>CloseNotification</literal>.</para>
+ <para>4 - Undefined/reserved 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>
+
+ <sect3 id="signal-action-invoked">
+ <title><literal>org.freedesktop.Notifications.ActionInvoked</literal></title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>
+ <function>org.freedesktop.Notifications.ActionInvoked</function>
+ </funcdef>
+ <paramdef>UINT32 <parameter>id</parameter></paramdef>
+ <paramdef>STRING <parameter>action_key</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This signal is emitted when one of the following occurs:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The user performs some global "invoking" action upon a notification.
+ For instance, clicking somewhere on the notification itself.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The user invokes a specific action as specified in the original
+ Notify request. For example, clicking on an action button.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <table>
+ <title>ActionInvoked Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row>
+ <entry><parameter>id</parameter></entry>
+ <entry>UINT32</entry>
+ <entry>
+ The ID of the notification emitting the ActionInvoked signal.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>action_key</parameter></entry>
+ <entry>STRING</entry>
+ <entry>
+ The key of the action invoked. These match the keys sent over
+ in the list of actions.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ </sect3>
+ </sect2>
+ </sect1>
+</article>
projects / framework / uifw / edbus.git / commitdiff