milfs-connect

A small Qt6/C++ library that lets independently-built desktop apps on this machine feel like one system: apps announce events (e.g. "a new photo was saved"), other apps subscribe and react live, and apps can deep-link into each other. No app needs to know about any other app's internals - they only agree on event-type names and payload shapes by convention.

Why

Built to connect Recamara (a camera app) and KaderGallery (a photo gallery), but nothing in this library is specific to either. Any future app links this and joins the same bus.

What it provides

• MilfsConnect::Presence - is another app installed (isInstalled), or currently running (isRunning, best-effort, requires the other app to own a party.milfs.<appId> D-Bus name).
• MilfsConnect::Bus - announce(eventType, payload) / subscribe(handler). Delivery is hybrid: every event is emitted live as a D-Bus signal and durably appended to a JSON-lines log (~/.local/share/milfs-connect/events.jsonl), so a subscriber that wasn't running when an event fired still catches up on its next subscribe() call (each subscriber's read position is tracked per-appId). The D-Bus signal is just a low-latency nudge to re-check the log; the log is the single source of truth for delivery and dedup, so nothing is delivered twice regardless of which path noticed it first.
• MilfsConnect::launch(appId, args) - resolve another app's .desktop entry and start it detached with the given arguments, for deep-linking.

Conventions

Producer/consumer apps agree on event shapes themselves; the library has no built-in knowledge of any specific event. The first one in use:

• media.added - {"path": "<abs path>", "mimeType": "<mime>", "sourceApp": "<appId>"}, announced by an app after it saves a new photo/video.

Apps that want to support being deep-linked to a specific item should accept a bare file path as their first CLI argument (i.e. myapp /abs/path/to/file), matching the existing %f/%u desktop-entry convention most apps already implement for "open with".

Using it

find_package(MilfsConnect REQUIRED)
target_link_libraries(your_app PRIVATE MilfsConnect::MilfsConnect)

#include <MilfsConnect/Connect.h>

MilfsConnect::Bus bus(QStringLiteral("your-app-id"));
bus.announce(QStringLiteral("media.added"), {
    {QStringLiteral("path"), path},
    {QStringLiteral("mimeType"), QStringLiteral("image/jpeg")},
    {QStringLiteral("sourceApp"), QStringLiteral("your-app-id")},
});

bus.subscribe([](const QString &appId, const QString &eventType, const QVariantMap &payload) {
    if (eventType == QStringLiteral("media.added")) {
        // ingest payload["path"]
    }
});

Building

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build