org.freedesktop.portal.Notification.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>