<?xml version="1.0"?>
<!--
 Copyright (C) 2016 Red Hat, Inc.

 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 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 and will be activated via the ActivateAction()
      method in the org.freedesktop.Application interface. Other
      actions are activated by sending the
      #org.freedeskop.portal.Notification::ActionInvoked signal
      to the application.

      This documentation describes version 1 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 replaced by the new one.

        The format of the serialized notification is a vardict, with
        the following supported keys, all of which are optional:
        <variablelist>
          <varlistentry>
            <term>title s</term>
            <listitem><para>
              User-visible string to display as the title.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>body s</term>
            <listitem><para>
              User-visible string to display as the body.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>icon v</term>
            <listitem><para>
              Serialized icon (see g_icon_serialize()).
            </para><para>
              The portal only accepts serialized GThemedIcon and GBytesIcons. Both of
              these have the form (sv). For themed icons, the string is "themed",
              and the value is an array of strings containing the icon names.
              For bytes icons, the string is "bytes", and the value is a bytestring
              containing the icon data in png, jpeg or svg form. For historical
              reasons, it is also possible to send a simple string for themed
              icons with a single icon name.
            </para>
            <para>
              There may be further restrictions on the supported kinds of icons.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>priority s</term>
            <listitem><para>
              The priority for the notification. Supported values: low, normal,
              high, urgent.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>default-action s</term>
            <listitem><para>
              Name of an action that is exported by the application. This
              action will be activated when the user clicks on the notification.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>default-action-target v</term>
            <listitem><para>
              Target parameter to send along when activating the default action.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>buttons aa{sv}</term>
            <listitem><para>
              Array of serialized buttons to add to the notification.
            </para></listitem>
          </varlistentry>
        </variablelist>

        The format for serialized buttons is a vardict with the following supported keys:
        <variablelist>
          <varlistentry>
            <term>label s</term>
            <listitem><para>
              User-visible label for the button. Mandatory.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>action s</term>
            <listitem><para>
              Name of an action that is exported by the application. The action
              will be activated when the user clicks on the button. Mandatory.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>target v</term>
            <listitem><para>
              Target parameter to send along when activating the action.
            </para></listitem>
          </varlistentry>
        </variablelist>
    -->
    <method name="AddNotification">
      <arg type="s" name="id" direction="in"/>
      <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>

    <!--
        ActionInvoked:
        @id: the application-provided ID for the notification
        @action: the name of the action
        @parameter: array which will contain the target parameter
          for the action, if one was specified

        Send to the application when a non-exported action is
        activated.
    -->
    <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>
