Basic D-Bus API (#866)

* feat: basic D-Bus API

Expose muted state and the number of unread message over D-Bus when
running on Linux. This is useful for, e.g., displaying notifications on
a window manager status bar.

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* docs: create docs directory

Move the documentation to a separate directory so that new documentation
can be added into one place.

We keep the following files still in the repository root by convention:

* CHANGELOG.md
* CODE_OF_CONDUCT.md
* CONTRIBUTING.md
* LICENSE.md
* README.md
* SECURITY.md

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* docs: D-Bus usage example

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* fix: remove unneeded D-Bus signals

Only notify clients that the message counts or the mute status has
changed if there actually was a change.

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* docs: rewrite sample bar client

* docs: better unread --services help

* docs: update dbus docs

* docs: use ferdium-dbus in dbus bar example

* docs: make command argument required in bar example

---------

Signed-off-by: Kristóf Marussy <kristof@marussy.com>
Co-authored-by: Victor Bonnelle <victor.bonnelle@protonmail.com>

1 files changed, 80 insertions, 0 deletions

diff --git a/docs/dbus/org.ferdium.Ferdium.xml b/docs/dbus/org.ferdium.Ferdium.xml
new file mode 100644
index 000000000..8c66a9e21
--- /dev/null
+++ b/docs/dbus/org.ferdium.Ferdium.xml
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+  <!--
+    org.ferdium.Ferdium:
+    @short_description: Control Ferdium from the desktop
+
+    Interface for accessing Ferdium notification state, allowing notification
+    counts to be displayed in the desktop (e.g., on a status bar) and updating
+    the muted state of notifications.
+
+    The #org.ferdium.UnreadDirectMessageCount,
+    #org.ferdium.UnreadIndirectMessageCount, and #org.ferdium.UnreadServices
+    are affected by notification muting and hiding settings of Ferdium.
+    In particular, they are not updated if #org.ferdium.Muted is #TRUE.
+    Moreover, services with muted notifications or hidden indirect message
+    counts will not appear in the respective counts.
+    This behavior is consistent with the behavior of the Ferdium tray icon.
+  -->
+  <interface name="org.ferdium.Ferdium">
+    <!--
+      ToggleMute:
+
+      Toggles the muted state of notifcations.
+
+      Use the #org.ferdium.Ferdium.Muted property to get or set the current
+      muted state.
+    -->
+    <method name="ToggleMute" />
+    <!--
+      ToggleWindow:
+
+      Brings the Ferdium window into the foreground if it is not currently
+      focused. Hides the Ferdium window if is is currently focused.
+
+      Calling this method is equivalent to clicking on the Ferdium tray icon.
+    -->
+    <method name="ToggleWindow" />
+    <!--
+      Muted:
+
+      Gets or sets the current muted state of notifications.
+
+      #TRUE if notifications are currently muted, #FALSE otherwise.
+    -->
+    <property name="Muted" type="b" access="readwrite" />
+    <!--
+      UnreadDirectMessageCount:
+
+      The number of unread direct messages.
+    -->
+    <property name="UnreadDirectMessageCount" type="u" access="read" />
+    <!--
+      UnreadIndirectMessageCount:
+
+      The number of unread indirect messages.
+    -->
+    <property name="UnreadIndirectMessageCount" type="u" access="read" />
+    <!--
+      UnreadServices:
+
+      The list of services with unread messages.
+
+      The value of this property is an array of structs corresponding to each
+      service with unread messages.
+      The elements of a struct are the following:
+
+      1. The name of the service.
+
+      2. The number of unread direct messages of the service.
+
+      3. The number of unread indirect messages of the service.
+
+      Services with no unread direct or indirect messages (i.e., structs with
+      the second and third element set to 0) are omitted from the array.
+    -->
+    <property name="UnreadServices" type="a(suu)" access="read" />
+  </interface>
+</node>