dbus.hpp

Go to the documentation of this file.

#pragma once
 
// Minimal session-bus D-Bus client over libdbus-1, loaded at runtime (no
// build-time libdbus-dev dependency, mirroring the libudev approach). Linux is
// the only real backend; on other platforms every call is an honest no-op
// (library_available() / connect_session() return false). Lives in
// core/platform — the lowest layer — so any subsystem can use it for
// session-bus IPC (xdg-desktop-portal file chooser / screenshot / notifications,
// etc.) without a build-time dependency or a layering cycle.
//
// Two consumption models live side by side here, deliberately kept separate:
//
//   * Portal CLIENT (file_chooser): a method call is sent and the reply / a
//     matching signal is awaited by *popping* messages off the incoming queue
//     (read_write + pop_message). pop_message removes a message BEFORE the
//     libdbus object-path dispatcher would ever see it.
//
//   * Object SERVER (register_object / emit_signal / dispatch): the app EXPORTS
//     objects and answers incoming method calls. This requires the libdbus
//     *dispatcher* to run so registered handlers fire — driven by dispatch(),
//     which calls dbus_connection_read_write_dispatch(). It must NOT be mixed
//     with the portal pop_message pump on the same pending traffic: pop_message
//     would steal the very method call a registered handler is meant to answer.
//
// The object-server layer is AT-SPI-agnostic generic infrastructure: it answers
// any registered object path, and is independently useful for MPRIS, desktop
// notifications, or AT-SPI accessibility export.
 
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
namespace pulp::platform {
 
class DBus {
public:
    DBus();
    ~DBus();

    static bool library_available();

    bool connect_session();

    bool connect_system();
 
    bool connected() const;

    bool connect_a11y_bus();

    bool a11y_connected() const;

    std::string unique_name() const;

    struct PortalResult {
        int response = 2;                  // portal "response" code
        std::vector<std::string> uris;     // results["uris"] (file:// URIs)
    };

    std::optional<PortalResult> file_chooser(
        const std::string& method,
        const std::string& title,
        const std::map<std::string, std::string>& options,
        const std::map<std::string, bool>& bool_options,
        int timeout_ms = 120000);
 
    // ── Object-server layer (generic, AT-SPI-agnostic) ──────────────────────
    //
    // A thin facade over the libdbus marshalling iterator. Reader walks an
    // incoming message's arguments; Writer appends arguments to a reply or a
    // signal. Both are non-owning views over the underlying DBusMessageIter and
    // are only valid for the duration of the call that produced them.

    class Reader {
    public:
        Reader() = default;

        bool read_string(std::string& out);
        bool read_int32(int& out);
        bool read_uint32(unsigned& out);
        bool read_double(double& out);
        bool read_byte(unsigned char& out);
        int arg_type() const;
        bool next();

        bool recurse(Reader& out_sub);
 
    private:
        friend class DBus;
        Reader(DBus* owner, void* iter) : owner_(owner), iter_(iter) {}
        // A recurse() sub-iterator owns its DBusMessageIter buffer; the parent
        // hands ownership to the sub-Reader so it outlives the call returning it.
        DBus* owner_ = nullptr;
        void* iter_ = nullptr;   // DBusMessageIter* (non-owning view)
        std::shared_ptr<void> owned_iter_;  // set only for recurse() sub-readers
    };

    class Writer {
    public:
        bool append_string(const std::string& s);
        bool append_object_path(const std::string& p);
        bool append_bool(bool v);
        bool append_int32(int v);
        bool append_uint32(unsigned v);
        bool append_double(double v);
        bool append_byte(unsigned char v);

        struct Container { void* iter = nullptr; bool open = false; };

        Container open_array(const std::string& element_signature);
        Container open_struct();
        Container open_variant(const std::string& value_signature);
        Container open_dict_entry();
        bool close_container(Container& c);

        Writer sub(Container& c);
 
    private:
        friend class DBus;
        Writer(DBus* owner, void* iter) : owner_(owner), iter_(iter) {}
        DBus* owner_ = nullptr;
        void* iter_ = nullptr;   // DBusMessageIter*
    };

    class CallContext {
    public:
        const std::string& path() const { return path_; }
        const std::string& interface() const { return interface_; }
        const std::string& member() const { return member_; }
        const std::string& sender() const { return sender_; }

        Reader& args() { return reader_; }

        Writer reply();
        void error(const std::string& name, const std::string& message);
 
    private:
        friend class DBus;
        CallContext(DBus* owner, void* msg, void* args_iter)
            : owner_(owner), msg_(msg), reader_(owner, args_iter) {}
        DBus* owner_ = nullptr;
        void* msg_ = nullptr;          // incoming DBusMessage*
        void* reply_msg_ = nullptr;    // DBusMessage* built by reply()/error()
        void* reply_iter_ = nullptr;   // heap append-iterator for reply(), freed
                                       // by the server after the message is sent
        bool answered_ = false;
        std::string path_, interface_, member_, sender_;
        Reader reader_;
    };

    using IncomingHandler = std::function<bool(CallContext& ctx)>;

    bool register_object(const std::string& path, IncomingHandler handler);
    bool unregister_object(const std::string& path);

    bool emit_signal(const std::string& path, const std::string& interface,
                     const std::string& member,
                     const std::function<void(Writer&)>& build_args);

    bool dispatch(int timeout_ms = 0);

    bool call_method(const std::string& destination, const std::string& path,
                     const std::string& interface, const std::string& member,
                     const std::function<void(Writer&)>& build_args,
                     const std::function<void(Reader&)>& read_reply,
                     int timeout_ms = 5000);
 
    // ── Signal subscription (broadcast, BYPASSES the object-path vtable) ─────
    //
    // D-Bus signals are broadcast messages, not method calls: they never reach
    // the object-path vtable / trampoline (which only routes method calls).
    // Receiving them requires (a) an org.freedesktop.DBus match rule so the
    // broker delivers them to this connection, and (b) a libdbus connection
    // FILTER that inspects each incoming message. Both are installed here.
    // Matching signals are routed to handlers during dispatch().

    using SignalHandler = std::function<void(const std::string& path,
                                             const std::string& interface,
                                             const std::string& member,
                                             Reader& args)>;

    unsigned add_signal_handler(const std::string& interface,
                                const std::string& member,
                                SignalHandler handler);
    bool remove_signal_handler(unsigned token);

    bool get_managed_objects(const std::string& destination,
                             const std::string& path,
                             const std::function<void(const std::string& obj_path,
                                                      const std::string& interface)>& per_object,
                             int timeout_ms = 5000);
 
    DBus(const DBus&) = delete;
    DBus& operator=(const DBus&) = delete;
 
private:
    bool connect_bus(int bus_type);
 
    struct Impl;
    Impl* impl_ = nullptr;
};

std::string file_uri_to_path(const std::string& uri);
 
}  // namespace pulp::platform