From f1152d3dbb4c6deefea168d66f15f77b7155a5fe Mon Sep 17 00:00:00 2001 From: Kristóf Marussy Date: Wed, 15 Mar 2023 17:26:13 +0100 Subject: Basic D-Bus API (#866) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * 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 * docs: D-Bus usage example Signed-off-by: Kristóf Marussy * 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 * 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 Co-authored-by: Victor Bonnelle --- docs/DBUS.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/DBUS.md (limited to 'docs/DBUS.md') diff --git a/docs/DBUS.md b/docs/DBUS.md new file mode 100644 index 000000000..ffbd61f4b --- /dev/null +++ b/docs/DBUS.md @@ -0,0 +1,20 @@ +# D-Bus interface + +Ferdium exposes an inter-process communication on Linux systems via [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/). +This allows integrating Ferdium with your desktop environment by displaying the number of unread notifications in a status area and muting or unmuting notations. + +## Desktop integration + +As an example integration, the [`docs/dbus`](dbus) folder contains a module for status bars written in Python. +To run the example, you'll need Python 3.11 and the [`dbus-next`](https://pypi.org/project/dbus-next/) PyPI package. + +The integration uses the [`FerdiumClient`](dbus/ferdium_client.py) client library, which is an asynchronous wrapper over the D-Bus interface. +It illustrates multiple advanced concepts, such as asynchronous communication with Ferdium via `asyncio` and polling the session D-Bus to see if Ferdium is running. + +The [`ferdium_bar.py`](dbus/ferdium_bar.py) implements a bar module to use with status bars such as waybar or polybar. See `ferdium_bar.py --help` and `ferdium_bar.py unread --help` for further indications on how to use it. + +## Low-level API + +The low-level API exposed over D-Bus is documented in [`org.ferdium.Ferdium.xml](docs/org.ferdium.Ferdium.xml) with standard D-Bus introspection syntax. + +Ferdium will take ownership of the bus name `org.ferdium.Ferdium` and expose and object implementing the `org.ferdium.Ferdium` interface at the object path `/org/ferdium`. -- cgit v1.2.3-70-g09d2