Desktop Notifications Specification
Prev

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

`"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.
`"body"`	Supports body text. Some implementations may 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.
`"body-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.
`"icon-multi"`	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 `"icon-static"` is missing, however the server is free to ignore them and use only the primary frame.
`"icon-static"`	Supports display of exactly 1 frame of any given image array. This value is mutually exclusive with `"icon-multi"`, it is a protocol error for the server to specify both.
`"sound"`	The server supports sounds on notifications. If 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.
`replaces_id`	UINT32	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.
`app_icon`	STRING	The optional program icon of the calling application. See 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`	ARRAY	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.
`hints`	DICT	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 Hints. Can be empty.
`expire_timeout`	INT32	The timeout time in milliseconds since the display of the notification at which the 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.

Name	Type	Description
`id`	UINT32	The ID of the notification that was closed.
`reason`	UINT32	The reason the notification was closed. 1 - The notification expired. 2 - The notification was dismissed by the user. 3 - The notification was closed by a call to `CloseNotification`. 4 - Undefined/reserved reasons.

reason

UINT32

The reason the notification was closed.

1 - The notification expired.

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.

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.

Prev	Home
Hints