diff options
author | Kristóf Marussy <kristof@marussy.com> | 2023-03-15 17:26:13 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-03-15 17:26:13 +0100 |
commit | f1152d3dbb4c6deefea168d66f15f77b7155a5fe (patch) | |
tree | 22c27234b6e3a2dfe47ade037ece47b2533f7039 /docs/DBUS.md | |
parent | 6.2.6-nightly.5 [skip ci] (diff) | |
download | ferdium-app-f1152d3dbb4c6deefea168d66f15f77b7155a5fe.tar.gz ferdium-app-f1152d3dbb4c6deefea168d66f15f77b7155a5fe.tar.zst ferdium-app-f1152d3dbb4c6deefea168d66f15f77b7155a5fe.zip |
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>
Diffstat (limited to 'docs/DBUS.md')
-rw-r--r-- | docs/DBUS.md | 20 |
1 files changed, 20 insertions, 0 deletions
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 @@ | |||
1 | # D-Bus interface | ||
2 | |||
3 | Ferdium exposes an inter-process communication on Linux systems via [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/). | ||
4 | This allows integrating Ferdium with your desktop environment by displaying the number of unread notifications in a status area and muting or unmuting notations. | ||
5 | |||
6 | ## Desktop integration | ||
7 | |||
8 | As an example integration, the [`docs/dbus`](dbus) folder contains a module for status bars written in Python. | ||
9 | To run the example, you'll need Python 3.11 and the [`dbus-next`](https://pypi.org/project/dbus-next/) PyPI package. | ||
10 | |||
11 | The integration uses the [`FerdiumClient`](dbus/ferdium_client.py) client library, which is an asynchronous wrapper over the D-Bus interface. | ||
12 | 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. | ||
13 | |||
14 | 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. | ||
15 | |||
16 | ## Low-level API | ||
17 | |||
18 | 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. | ||
19 | |||
20 | 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`. | ||