Desktop Notifications Specification
<<< Previous

D-BUS Protocol

The following messages must be supported by all implementations.

Message commands

`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 ("-").

`org.freedesktop.Notifications.Notify`

UINT32 org.freedesktop.Notifications.Notify (STRING app_name, BYTE_ARRAY_OR_STRING app_icon, UINT32 replaces_id, STRING notification_type, BYTE urgency_level, STRING summary, STRING body, ARRAY images, DICT actions, DICT hints, BOOL expires, UINT32 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.
`app_icon`	BYTE_ARRAY or STRING	The optional program icon of the calling application. This is in the same format as an image frame. See Icons. Can be an empty string, indicating no icon.
`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.
`notification_type`	STRING	The optional notification type ID, for potential server categorization and logging purposes. See Notification Types. Can be empty.
`urgency_level`	BYTE	The urgency level. See Urgency Levels.
`summary`	STRING	The summary text briefly describing the notification.
`body`	STRING	The optional detailed body text. Can be empty.
`images`	ARRAY	The optional array of images. See Icons. Can be empty.
`actions`	DICT	A dictionary key of actions. Each key is the localized name of the action, as it should appear to the user, and maps to a UINT32 value containing a program-specific action code. This code will be reported back to the program if the action is invoked by the user. Can be empty.
`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.
`expires`	BOOL	A boolean flag indicating whether or not this notification should automatically expire.
`expire_timeout`	UINT32	The timeout time in seconds since the display of the notification at which the notification should automatically close. This is ignored if the expires flag is set to false. If zero, the notification's expiration time is dependent on the notification server's settings, and may vary for the type of notification.

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.

`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.

`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.

Signals

`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.

`org.freedesktop.Notifications.ActionInvoked`

org.freedesktop.Notifications.ActionInvoked (UINT32 id, UINT32 action_id);

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_id`	UINT32	The ID of the action invoked. A value of 0 means that the default action was invoked, i.e., clicking the notification itself. IDs greater than zero are the action IDs as defined by the calling application.

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.