afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
Close stale issues and PRs / stale (push) Has been cancelled
429 lines
16 KiB
XML
429 lines
16 KiB
XML
<?xml version="1.0"?>
|
||
<!--
|
||
Copyright (C) 2016 Red Hat, Inc.
|
||
|
||
SPDX-License-Identifier: LGPL-2.1-or-later
|
||
|
||
This library is free software; you can redistribute it and/or
|
||
modify it under the terms of the GNU Lesser General Public
|
||
License as published by the Free Software Foundation; either
|
||
version 2.1 of the License, or (at your option) any later version.
|
||
|
||
This library is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public
|
||
License along with this library. If not, see <http://www.gnu.org/licenses/>.
|
||
|
||
Author: Matthias Clasen <mclasen@redhat.com>
|
||
-->
|
||
|
||
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
|
||
<!--
|
||
org.freedesktop.portal.Notification:
|
||
@short_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
|
||
<https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s08.html>`_
|
||
using ``ActivateAction()`` method in the
|
||
``org.freedesktop.Application`` interface. An `activation-token` for
|
||
`XDG Activation
|
||
<https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/xdg-activation-v1.xml>`_
|
||
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.
|
||
-->
|
||
<interface name="org.freedesktop.portal.Notification">
|
||
<!--
|
||
AddNotification:
|
||
@id: Application-provided ID for this notification
|
||
@notification: Vardict with the serialized notification
|
||
|
||
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 icon must pass
|
||
`icon validation <icons.html>`_ in order to be used. 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
|
||
<https://docs.gtk.org/gio/class.ThemedIcon.html>`_ 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.
|
||
|
||
This is the same format as a serialized `GBytesIcon
|
||
<https://docs.gtk.org/gio/class.BytesIcon.html>`_ 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 <https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API>`_.
|
||
-->
|
||
<method name="AddNotification">
|
||
<annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
|
||
<arg type="s" name="id" direction="in"/>
|
||
<annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap"/>
|
||
<arg type="a{sv}" name="notification" direction="in"/>
|
||
</method>
|
||
<!--
|
||
RemoveNotification:
|
||
@id: Application-provided ID for this notification
|
||
|
||
Withdraws a notification.
|
||
-->
|
||
<method name="RemoveNotification">
|
||
<arg type="s" name="id" direction="in"/>
|
||
</method>
|
||
|
||
<!--
|
||
SupportedOptions:
|
||
|
||
Some properties in :ref:`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`.
|
||
-->
|
||
<property name="SupportedOptions" type="a{sv}" access="read">
|
||
<annotation name="org.qtproject.QtDBus.QtTypeName" value="QVariantMap"/>
|
||
</property>
|
||
|
||
<!--
|
||
ActionInvoked:
|
||
@id: the application-provided ID for the notification
|
||
@action: the name of the action
|
||
@parameter: an array containing additional information
|
||
|
||
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
|
||
<https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/xdg-activation-v1.xml>`_
|
||
|
||
#. The user `response` for an action based on the purpose if applicable.
|
||
-->
|
||
<signal name="ActionInvoked">
|
||
<arg type="s" name="id"/>
|
||
<arg type="s" name="action"/>
|
||
<arg type="av" name="parameter"/>
|
||
</signal>
|
||
<property name="version" type="u" access="read"/>
|
||
</interface>
|
||
</node>
|