WIP: write notification specs v2

data/org.freedesktop.portal.Notification.xml

@@ -58,6 +58,16 @@
         The format of the serialized notification is a vardict, with
         the following supported keys, all of which are optional:
 
+        * ``application-id`` (``s``)
+
+          An optional application id. 
+          This can be the flatpak application id including a postfix.
+          E.g ``org.libreoffice.LibreOffice.Writer` where 
+          ``org.libreoffice.LibreOffice`` is the flatpak application id.
+
+          If this property isn't set it will be picked up from the flatpak.
+          See `Application IDs <https://flatpak-docs.readthedocs.io/en/latest/conventions.html>`_.
+
         * ``title`` (``s``)
 
           User-visible string to display as the title.
@@ -95,29 +105,6 @@
 
           There may be further restrictions on the supported kinds of icons.
 
-        * ``sound`` (``v``)
-
-          A serialized sound to add to the notification. The format for
-          serialized sound is a tuple (sv) with the following supported keys:
-
-          * ``themed`` (``as``)
-
-            A themed sound containing an array of strings with the themeable
-            named sound icon names, similar to an icon names.
-
-          * ``bytes`` (``ay``)
-
-            A bytes sound containing a bytestring with the sound data.
-
-            This is the same format as a serialized `GBytesIcon
-            <https://docs.gtk.org/gio/class.BytesIcon.html>`_.
-
-          * ``file-descriptor`` (``h``)
-
-            A file descriptor to a sound file.
-
-          There may be further restrictions on the supported kinds of sounds.
-
         * ``priority`` (``s``)
 
           The priority for the notification. Supported values:
@@ -153,12 +140,154 @@
           * ``target`` (``v``)
 
             Target parameter to send along when activating the action.
+
+        * ``presentation-hints`` (``a{sv}``)
+
+            Presentation hints allow specifing how a notification should be presented. 
+            This are suggestions to the system and it may ignore any hint.
+
+          * ``content`` (``s``)
+
+            The content hint describes the type of content of a notification.
+            A notification server may use this information to display the 
+            notification in a special way.
+
+            The following types are defined by the protocol so far:
+          
+            * im.message
+            * alarm.ringing
+            * call.incoming
+            * call.ongoing
+            * call.missed
+            * weather.warning.extreme
+            * cellbroadcast.danger.extreme
+            * cellbroadcast.danger.severe
+            * cellbroadcast.amberalert
+            * cellbroadcast.test
+            * os.battery.low
+            * browser.webNotification
+
+            Additional types may be defined with a vendor specific prefix in from of "x-vendor"
+
+          * ``sound`` (``v``)
+
+          A serialized sound to add to the notification. The format for
+          serialized sound is a tuple (sv) with the following supported keys:
+
+          * ``themed`` (``as``)
+
+            A themed sound containing an array of strings with the themeable
+            named sound icon names, similar to an icon names.
+
+          * ``bytes`` (``ay``)
+
+            A bytes sound containing a bytestring with the sound data.
+
+            This is the same format as a serialized `GBytesIcon
+            <https://docs.gtk.org/gio/class.BytesIcon.html>`_.
+
+          * ``file-descriptor`` (``h``)
+
+            A file descriptor to a sound file.
+          
+          * ``silent``
+
+            A "silent" sound indicating that no sound should be played for the notification
+
+          There may be further restrictions on the supported kinds of sounds.
+ 
+          * ``vibration`` (``au``)
+
+            Vibration pattern is an array of uint32 to describing 
+            alternating periods in which the device should vibrate and not vibrate in millisecounds.
+            This array can contain a odd number of items since the last non vibrating period can be omitted.
+            
+            An empty array indicates to ignore system settings and don't vibrate.
+
+            This similar API to `Web Vibration API <https://developer.mozilla.org/en-US/docs/Web/API/Vibration_API>`_.
+
+          * ``led-color`` (``(yyyy)``)
+
+            Notification LED color as 4 bytes value ```(red, green, blue, alpha)```.
+                      
+            A tuple of ``(0000)`` indicates to ignore system settings and don't turn on the LED.
+            
+          * ``no-banner`` (``b``)
+
+            If a notification is ``transient`` only a banner is show. 
+            FIXME: THIS feels like more explicit urgency and should 
+            probably an enum with only-banner.
+
+          * ``only-banner`` (``b``)
+
+            If a notification has this hint set to ``true`` only a banner is show.
       -->
     <method name="AddNotification">
       <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
       <arg type="s" name="id" direction="in"/>
       <arg type="a{sv}" name="notification" direction="in"/>
     </method>
+
+    <!--
+      ListSupportedProperties:
+
+      Returns a list of supported properties with 
+      specifc sub-properties if applicable for the specific property.
+
+      Applications only need to check this list for support of a property
+      if they want to implement a fallback for it to ensure that user is
+      correctly notified.
+
+      The server will probably only return a subset, 
+      including the supported properties, of the following list:
+
+      * ``application-id``
+      * ``title``
+      * ``body``
+      * ``icon``
+        - ``themed``
+        - ``bytes``
+        - ``file-descriptor``
+      * ``priority`` (``as``)
+        - ``low``
+        - ``normal``
+        - ``high``
+        - ``urgent``
+      * ``default-action``
+      * ``default-action-target``
+      * ``buttons`` (``a{smv}``)
+        - ``label``
+        - ``action``
+        - ``target``
+      * ``presentation-hints`` (``a{smv}``)
+        * ``content`` (``as``)
+          * im.message
+          * alarm.ringing
+          * call.incoming
+          * call.ongoing
+          * call.missed
+          * weather.warning.extreme
+          * cellbroadcast.danger.extreme
+          * cellbroadcast.danger.severe
+          * cellbroadcast.amberalert
+          * cellbroadcast.test
+          * os.battery.low
+          * browser.webNotification
+
+        * ``sound`` (``a{smv}``)
+          * ``themed``
+          * ``bytes``
+          * ``file-descriptor``
+          * ``silent``
+        * ``vibration``
+        * ``led-color`
+        * ``no-banner``
+        * ``only-banner``
+    -->
+    <method name="ListSupportedProperties">
+      <arg type="a{smv}" name="supported-properties" direction="out"/>
+    </method>
+
     <!--
         RemoveNotification:
         @id: Application-provided ID for this notification
@@ -178,7 +307,7 @@
         Send to the application when a non-exported action is
         activated.
     -->
-    <signal name="ActionInvoked">
+    <signal name="ActionInvoked" org.freedesktop.DBus.Deprecated=true>
       <arg type="s" name="id"/>
       <arg type="s" name="action"/>
       <arg type="av" name="parameter"/>