Notification¶

Description¶

Portal for sending notifications

This simple interface lets sandboxed applications send and withdraw notifications. It is not possible for the application to learn if the notification was actually presented to the user. Not a portal in the strict sense, since there is no user interaction.

Note that in contrast to most other portal requests, notifications are expected to outlast the running application. If a user clicks on a notification after the application has exited, it will get activated again.

Notifications can specify actions that can be activated by the user. Actions whose name starts with ‘app.’ are assumed to be exported (without the ‘app.’ prefix) and will be activated via D-Bus Activation using ActivateAction() method in the org.freedesktop.Application interface. An activation-token for XDG Activation and an application-defined target is passed when activating the action. Other actions are activated by sending the org.freedesktop.portal.Notification::ActionInvoked signal to the application.

This documentation describes version 2 of this interface.

Properties¶

org.freedesktop.portal.Notification:SupportedOptions¶

SupportedOptions readable a{sv}

Some properties in org.freedesktop.portal.Notification.AddNotification may have options advertised by the server.

Currently there are the following options the notification server can advertise:

category (as)

Categories that the notification server understands and supports.
button-purpose (as)

Button purposes that the notification server understands and supports. This is the list of options that can be used as purpose for buttons.

org.freedesktop.portal.Notification:version¶

version readable u

Methods¶

org.freedesktop.portal.Notification.AddNotification¶

AddNotification (
  IN id s,
  IN notification a{sv}
)

Sends a notification.

The ID can be used to later withdraw the notification. If the application reuses the same ID without withdrawing, the notification is updated with the new one. It’s possible to set show-as-new hint in the display-hint property to animate replacing the notification instead of updating it.

The format of the serialized notification is a vardict, with the following supported keys, all of which are optional:

title (s)

User-visible string to display as the title.

This should be a short string, if it doesn’t fit the UI it may be truncated to fit on a single line.
body (s)

User-visible string to display as the body.

This can be a long string but if it doesn’t fit the UI it may be wrapped or/and truncated.
markup-body (s)

The same as body but with support for markup formatting. The markup is XML-based and supports a small subset of HTML <b>...</b>, <i>...</i> and <a href="...">...</a>.

Any markup not supported, e.g. new lines, will be removed from the string. In the future, the set of supported markup may be extended.

This can be a long string but if it doesn’t fit the UI it may be wrapped or/and truncated.
icon (v)

A serialized icon to add to the notification. The format for serialized icon is a tuple (sv) with the following supported keys:
- themed (as)
  
  A themed icon containing an array of strings with the icon names.
  
  This is the same format as a serialized GThemedIcon at the moment, but this interoperability may change in the future.
- bytes (ay)
  
  Since version 2, this is deprecated and should not be used. Please use the themed or file-descriptor option to set an icon.
  
  A bytes icon containing a bytestring with the icon data in png, jpeg or svg form.
  
  This is the same format as a serialized GBytesIcon at the moment, but this interoperability may change in the future.
- file-descriptor (h)
  
  A file descriptor to an image file in png, jpeg or svg form. The file-descriptor used needs to be sealable, currently this is only possible for file descriptors created with memfd_create() with the MFD_ALLOW_SEALING flag set.
For historical reasons, it is also possible to send a simple string for themed icons with a single icon name.

There may be further restrictions on the supported kinds of icons.
sound (v)

A serialized sound to add to the notification. Supported sound formats are ogg/opus, ogg/vorbis and wav/pcm.

The format for serialized sound is a tuple (sv) with the following supported keys:
- file-descriptor (h)
  
  A file descriptor to a sound file. The file-descriptor used needs to be sealable, currently this is only possible for file descriptors created with memfd_create() with the MFD_ALLOW_SEALING flag set.
To play the default sound the string default can be passed. To play no sound at all the string silent can be passed. If this property isn’t specified the notification server can decide whether to play a sound.

There may be further restrictions on the supported kinds of sounds.
priority (s)

The priority for the notification. Supported values:
- low
- normal
- high
- urgent
default-action (s)

Name of an action that is exported by the application. This action will be activated when the user clicks on the notification.
default-action-target (v)

Target parameter to send along when activating the default action.
buttons (aa{sv})

Array of serialized buttons to add to the notification. The format for serialized buttons is a vardict with the following supported keys:
- label (s)
  
  User-visible label for the button. Mandatory, if no purpose is specified. It is strongly recommended to always provide sensible label. Buttons without a label are ignored by the server when it doesn’t understand the purpose or is needed to display the button.
- action (s)
  
  Name of an action that is exported by the application. The action will be activated when the user clicks on the button. Mandatory.
- target (v)
  
  Target parameter to send along when activating the action.
- purpose (s)
  
  The purpose of the button. This information may be used by the notification server to treat the button specially.
  
  Depending on the purpose other fields of the button may be ignored. If the server doesn’t understand the purpose it will be ignored and the button will be shown as a normal button.
  
  Most standardized hints are defined as part of a category. Additional purposes may be defined by notification servers using x-vendor prefix e.g. x-gnome.class.specific
  
  The following purposes are defined outside of a category:
  - system.custom-alert:
    
    Not a button in a strict sense. This action may be called, depending on system policies, automatically by the notification server whenever the notification is shown.
    
    This allows apps to use custom methods for notifying the user, for example, to play audio from a special source like a streaming service or a radio station.
    
    No label should be given when this purpose is used, so that the server can ignore the button if it doesn’t understand the purpose.
display-hint (as)

An array of ways to display the notification. If none are set, or the notification server has its own policy, it is free to decide how and where to display the notification.
- transient
  
  The notification is displayed only as a banner and won’t be kept by the server in a tray.
  
  It’s a programmer error to specify tray at the same time.
- tray
  
  No banner for the notification will be displayed and the notification is placed in the tray.
  
  It’s a programmer error to specify transient at the same time.
- persistent
  
  Make the notification persistent in the notification tray. The user can’t dismiss it using the usual close button or gesture.
  
  Apps are only allowed to display persistent notifications as long as they have a window. Once the last window of an app is closed the persistent notification will be removed.
- hide-on-lockscreen
  
  Don’t show the notification on the lockscreen.
- hide-content-on-lockscreen
  
  All content of the notification will be hidden on the lockscreen.
- show-as-new
  
  If a notification with the same id of the app exists already replace the previous notification, by removing the old notification (including animation, etc) and adding a new notification.
  
  If this hint isn’t specified the notification’s content is updated without any flickering.
category (s)

The category describes the content of a notification. A notification server may use this information to display the notification specially. Some categories also include button purposes that can be set for a button so that the notification can know the purpose of the button.

Additional categories and button purposes may be defined by notification servers using x-vendor prefix e.g. x-gnome.class.specific

The following categories are standarized so far:
- im.received
  
  Intended for instant messaging apps displaying notifications for new messages.
  
  This category has the following button purposes:
  - im.reply-with-text:
    
    Inline replies for instant messaging. The user-provided text will be added to the response.
    
    The user response (s) will be placed as the second value in the parameter array of exported actions. For non-exported actions it will be placed as the third value in the parameter array of org.freedesktop.portal.Notification::ActionInvoked.
- alarm.ringing
  
  Intended for alarm clock apps
- call.incoming
  
  Intended for call apps to notify the user about an incoming call.
  
  This category has the following button purposes:
  - call.accept:
    
    Accept the incoming call.
  - call.decline:
    
    Decline the incoming call.
- call.ongoing
  
  Intended for call apps while a call is ongoing.
  
  This type has the following button purposes:
- call.hang-up:
  
  Hang up the ongoing call.
  - call.enable-speakerphone:
    
    Enable the speakerphone for the ongoing call.
  - call.disable-speakerphone:
    
    Disable the speakerphone for the ongoing call.
- call.unanswered
  
  Intended to be used by call apps when a call was missed.
- weather.warning.extreme
  
  Intended to be used to display an extreme weather warning.
- cellbroadcast.danger.extreme
  
  Intended to be used to display extreme danger warnings broadcasted by the cell network.
- cellbroadcast.danger.severe
  
  Intended to be used to display severe danger warnings broadcasted by the cell network.
- cellbroadcast.amber-alert
  
  Intended to be used to display amber alerts broadcasted by the cell network.
- cellbroadcast.test
  
  Intended to be used to display tests broadcasted by the cell network.
- os.battery.low
  
  Intended to be used to indicate that the system is low on battery.
- browser.web-notification
  
  Intended to be used by browsers to mark notifications send by websites via the Notifications API.

id: Application-provided ID for this notification
notification: Vardict with the serialized notification

org.freedesktop.portal.Notification.RemoveNotification¶

RemoveNotification (
  IN id s
)

Withdraws a notification.

id: Application-provided ID for this notification

Signals¶

org.freedesktop.portal.Notification::ActionInvoked¶

ActionInvoked (
  id s,
  action s,
  parameter av
)

Send to the application when a non-exported action is activated.

The parameter contains the following values in order:

The target for the action, if one was specified.
The platform-data as vardict (a{sv}) containing an activation-token (s) for XDG Activation
The user response for an action based on the purpose if applicable.

id: the application-provided ID for the notification
action: the name of the action
parameter: an array containing additional information