refactor: object manager API (#438)

This makes the signature of addObjectManager() function overloads consistent with common API design of the library.

ChangeLog

@@ -263,6 +263,8 @@ v2.0.0
 - Introduce native integration for sd-event
 - Add method to get currently processed message also to `IConnection`
 - Add Slot-returning overloads of `callMethodAsync()` functions
+- Add Slot-returning overload of `addObjectManager` to the `IObject`
+- Add Slot-returning overload of `addObjectManager` to the `IConnection`
 - `[[nodiscard]]` attribute has been added to relevant API methods.
 - Add new `SDBUSCPP_SDBUS_LIB` CMake configuration variable determining which sd-bus library shall be picked
 - Switch to C++20 standard (but C++20 is not required, and the used C++20 features are conditionally compiled)

docs/using-sdbus-c++.md

@@ -1796,6 +1796,8 @@ sdbus-c++ v2 is a major release that comes with a number of breaking API/ABI/beh
 * `AdaptorInterfaces::getObjectPath()` was removed. It can be replaced with `AdaptorInterfaces::getObject().getObjectPath()`.
 * `createConnection()` has been removed. To create a connection to the system bus use `createSystemConnection()` instead.
 * `createDefaultBusConnection()` has been renamed to `createBusConnection()`.
+* `IObject::removeObjectManager()` and `IObject::hasObjectManager()` were removed. Clients should now use the slot-returning `IObject::addObjectManager()` to control the `ObjectManager` interface lifetime.
+* `floating_slot_t` tag was removed from `IConnection::addObjectManager()`, the function is now by default floating-slot-based.
 * Change in behavior: `Proxy`s now by default call `createBusConnection()` to get a connection when the connection is not provided explicitly by the caller, so they connect to either the session bus or the system bus depending on the context (as opposed to always to the system bus like before).
 * Callbacks taking `const sdbus::Error* error` were changed to take `std::optional<sdbus::Error>`, which better expresses the intent and meaning.
 * `getInterfaceName()`, `getMemberName()`, `getSender()`, `getPath()` and `getDestination()` methods of `Message` class now return `const char*` instead of `std::string`, for efficiency reasons.

include/sdbus-c++/IConnection.h

@@ -223,6 +223,7 @@ namespace sdbus {
 
         /*!
          * @brief Adds an ObjectManager at the specified D-Bus object path
+         * @param[in] objectPath Object path at which the ObjectManager interface shall be installed
          *
          * Creates an ObjectManager interface at the specified object path on
          * the connection. This is a convenient way to interrogate a connection
@@ -231,12 +232,29 @@ namespace sdbus {
          * This call creates a floating registration. The ObjectManager will
          * be there for the object path until the connection is destroyed.
          *
-         * Another, recommended way to add object managers is directly through
-         * IObject API.
+         * Another, recommended way to add object managers is directly through IObject API.
          *
          * @throws sdbus::Error in case of failure
          */
-        virtual void addObjectManager(const ObjectPath& objectPath, floating_slot_t) = 0;
+        virtual void addObjectManager(const ObjectPath& objectPath) = 0;
+
+        /*!
+         * @brief Adds an ObjectManager at the specified D-Bus object path
+         * @param[in] objectPath Object path at which the ObjectManager interface shall be installed
+         * @return Slot handle owning the registration
+         *
+         * Creates an ObjectManager interface at the specified object path on
+         * the connection. This is a convenient way to interrogate a connection
+         * to see what objects it has.
+         *
+         * This call returns an owning slot. The lifetime of the ObjectManager
+         * interface is bound to the lifetime of the returned slot instance.
+         *
+         * Another, recommended way to add object managers is directly through IObject API.
+         *
+         * @throws sdbus::Error in case of failure
+         */
+        [[nodiscard]] virtual Slot addObjectManager(const ObjectPath& objectPath, return_slot_t) = 0;
 
         /*!
          * @brief Installs a match rule for messages received on this bus connection

include/sdbus-c++/IObject.h

@@ -247,22 +247,28 @@ namespace sdbus {
          * the connection. This is a convenient way to interrogate a connection
          * to see what objects it has.
          *
+         * This call creates a so-called floating registration. This means that
+         * the ObjectManager interface stays there for the lifetime of the object.
+         *
          * @throws sdbus::Error in case of failure
          */
         virtual void addObjectManager() = 0;
 
         /*!
-         * @brief Removes an ObjectManager interface from the path of this D-Bus object
+         * @brief Adds an ObjectManager interface at the path of this D-Bus object
+         *
+         * @return Slot handle owning the registration
+         *
+         * Creates an ObjectManager interface at the specified object path on
+         * the connection. This is a convenient way to interrogate a connection
+         * to see what objects it has.
+         *
+         * The lifetime of the ObjectManager interface is bound to the lifetime
+         * of the returned slot instance.
          *
          * @throws sdbus::Error in case of failure
          */
-        virtual void removeObjectManager() = 0;
-
-        /*!
-         * @brief Tests whether ObjectManager interface is added at the path of this D-Bus object
-         * @return True if ObjectManager interface is there, false otherwise
-         */
-        [[nodiscard]] virtual bool hasObjectManager() const = 0;
+        [[nodiscard]] virtual Slot addObjectManager(return_slot_t) = 0;
 
         /*!
          * @brief Provides D-Bus connection used by the object

src/Connection.cpp

@@ -189,7 +189,7 @@ ISdBus& Connection::getSdBusInterface()
     return *sdbus_.get();
 }
 
-void Connection::addObjectManager(const ObjectPath& objectPath, floating_slot_t)
+void Connection::addObjectManager(const ObjectPath& objectPath)
 {
     auto r = sdbus_->sd_bus_add_object_manager(bus_.get(), nullptr, objectPath.c_str());
 

src/Connection.h

@@ -102,7 +102,7 @@ namespace sdbus::internal {
         bool processPendingEvent() override;
         Message getCurrentlyProcessedMessage() const override;
 
-        void addObjectManager(const ObjectPath& objectPath, floating_slot_t) override;
+        void addObjectManager(const ObjectPath& objectPath) override;
         Slot addObjectManager(const ObjectPath& objectPath, return_slot_t) override;
 
         void setMethodCallTimeout(uint64_t timeout) override;

src/IConnection.h

@@ -105,9 +105,6 @@ namespace sdbus::internal {
         virtual void emitInterfacesRemovedSignal( const ObjectPath& objectPath
                                                 , const std::vector<InterfaceName>& interfaces ) = 0;
 
-        using sdbus::IConnection::addObjectManager;
-        [[nodiscard]] virtual Slot addObjectManager(const ObjectPath& objectPath, return_slot_t) = 0;
-
         [[nodiscard]] virtual Slot registerSignalHandler( const char* sender
                                                         , const char* objectPath
                                                         , const char* interfaceName

src/Object.cpp

@@ -76,7 +76,7 @@ Slot Object::addVTable(InterfaceName interfaceName, std::vector<VTableItem> vtab
 void Object::unregister()
 {
     vtables_.clear();
-    removeObjectManager();
+    objectManagerSlot_.reset();
 }
 
 sdbus::Signal Object::createSignal(const InterfaceName& interfaceName, const SignalName& signalName)
@@ -141,14 +141,9 @@ void Object::addObjectManager()
     objectManagerSlot_ = connection_.addObjectManager(objectPath_, return_slot);
 }
 
-void Object::removeObjectManager()
-{
-    objectManagerSlot_.reset();
-}
-
-bool Object::hasObjectManager() const
+Slot Object::addObjectManager(return_slot_t)
 {
-    return objectManagerSlot_ != nullptr;
+    return connection_.addObjectManager(objectPath_, return_slot);
 }
 
 sdbus::IConnection& Object::getConnection() const

src/Object.h

@@ -66,8 +66,7 @@ namespace sdbus::internal {
         void emitInterfacesRemovedSignal(const std::vector<InterfaceName>& interfaces) override;
 
         void addObjectManager() override;
-        void removeObjectManager() override;
-        [[nodiscard]] bool hasObjectManager() const override;
+        [[nodiscard]] Slot addObjectManager(return_slot_t) override;
 
         [[nodiscard]] sdbus::IConnection& getConnection() const override;
         [[nodiscard]] const ObjectPath& getObjectPath() const override;