From e62525ca4f316a804652b176828b64d93a579dde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanislav=20Angelovi=C4=8D?= Date: Fri, 16 Feb 2024 09:27:45 +0100 Subject: [PATCH] chore: reorder some API functions (#404) In sdbus-c++ v1, new virtual functions (e.g. overloads of existing virtual functions) were always placed at the end of the class to keep backwards ABI compatibility. Now, with v2, these functions are reordered and functions forming a logical group are together. --- CMakeLists.txt | 6 +-- include/sdbus-c++/IObject.h | 42 ++++++++--------- include/sdbus-c++/IProxy.h | 94 ++++++++++++++++++------------------- 3 files changed, 70 insertions(+), 72 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 3ee8100..8ea41d8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -17,8 +17,7 @@ if(SDBUSCPP_BUILD_LIBSYSTEMD) set(SDBUSCPP_LIBSYSTEMD_VERSION "242" CACHE STRING "libsystemd version (>=239) to build and incorporate into libsdbus-c++") set(SDBUSCPP_LIBSYSTEMD_EXTRA_CONFIG_OPTS "" CACHE STRING "Additional configuration options to be passed as-is to libsystemd build system") endif() -option(SDBUSCPP_INSTALL "Enable installation of sdbus-c++ (downstream projects embedding sdbus-c++ may want to turn this OFF)" ON) #TODO: new, honor -# TODO: Continue here with search&replace old names with new names +option(SDBUSCPP_INSTALL "Enable installation of sdbus-c++ (downstream projects embedding sdbus-c++ may want to turn this OFF)" ON) option(SDBUSCPP_BUILD_TESTS "Build tests" OFF) if (SDBUSCPP_BUILD_TESTS) option(SDBUSCPP_BUILD_PERF_TESTS "Build also sdbus-c++ performance tests" OFF) # tranferred from tests/cmake @@ -27,10 +26,9 @@ if (SDBUSCPP_BUILD_TESTS) set(SDBUSCPP_GOOGLETEST_VERSION 1.10.0 CACHE STRING "Version of gmock library to use") # tranferred from tests/cmake set(SDBUSCPP_GOOGLETEST_GIT_REPO "https://github.com/google/googletest.git" CACHE STRING "A git repo to clone and build googletest from if gmock is not found in the system") # tranferred from tests/cmake endif() -# TODO: add more embedded options from sub=-cmakefiles option(SDBUSCPP_BUILD_CODEGEN "Build generator tool for C++ native bindings" OFF) option(SDBUSCPP_BUILD_EXAMPLES "Build example programs" OFF) -option(SDBUSCPP_BUILD_DOCS "Build documentation for sdbus-c++" ON) # TODO: renamed +option(SDBUSCPP_BUILD_DOCS "Build documentation for sdbus-c++" ON) if(SDBUSCPP_BUILD_DOCS) option(SDBUSCPP_BUILD_DOXYGEN_DOCS "Build doxygen documentation for sdbus-c++ API" OFF) endif() diff --git a/include/sdbus-c++/IObject.h b/include/sdbus-c++/IObject.h index b5435ec..0847dc2 100644 --- a/include/sdbus-c++/IObject.h +++ b/include/sdbus-c++/IObject.h @@ -201,6 +201,27 @@ namespace sdbus { */ virtual void emitSignal(const sdbus::Signal& message) = 0; + /*! + * @brief Emits signal on D-Bus + * + * @param[in] signalName Name of the signal + * @return A helper object for convenient emission of signals + * + * This is a high-level, convenience way of emitting D-Bus signals that abstracts + * from the D-Bus message concept. Signal arguments are automatically serialized + * in a message and D-Bus signatures automatically deduced from the provided native arguments. + * + * Example of use: + * @code + * int arg1 = ...; + * double arg2 = ...; + * object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2); + * @endcode + * + * @throws sdbus::Error in case of failure + */ + [[nodiscard]] SignalEmitter emitSignal(const std::string& signalName); + /*! * @brief Emits PropertyChanged signal for specified properties under a given interface of this object path * @@ -298,27 +319,6 @@ namespace sdbus { */ [[nodiscard]] virtual sdbus::IConnection& getConnection() const = 0; - /*! - * @brief Emits signal on D-Bus - * - * @param[in] signalName Name of the signal - * @return A helper object for convenient emission of signals - * - * This is a high-level, convenience way of emitting D-Bus signals that abstracts - * from the D-Bus message concept. Signal arguments are automatically serialized - * in a message and D-Bus signatures automatically deduced from the provided native arguments. - * - * Example of use: - * @code - * int arg1 = ...; - * double arg2 = ...; - * object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2); - * @endcode - * - * @throws sdbus::Error in case of failure - */ - [[nodiscard]] SignalEmitter emitSignal(const std::string& signalName); - /*! * @brief Returns object path of the underlying DBus object */ diff --git a/include/sdbus-c++/IProxy.h b/include/sdbus-c++/IProxy.h index 8f263f4..6c81d1b 100644 --- a/include/sdbus-c++/IProxy.h +++ b/include/sdbus-c++/IProxy.h @@ -197,53 +197,6 @@ namespace sdbus { , const std::chrono::duration<_Rep, _Period>& timeout , with_future_t ); - /*! - * @brief Registers a handler for the desired signal emitted by the D-Bus object - * - * @param[in] interfaceName Name of an interface that the signal belongs to - * @param[in] signalName Name of the signal - * @param[in] signalHandler Callback that implements the body of the signal handler - * - * A signal can be subscribed to and unsubscribed from at any time during proxy - * lifetime. The subscription is active immediately after the call. - * - * @throws sdbus::Error in case of failure - */ - virtual void registerSignalHandler( const std::string& interfaceName - , const std::string& signalName - , signal_handler signalHandler ) = 0; - - /*! - * @brief Registers a handler for the desired signal emitted by the D-Bus object - * - * @param[in] interfaceName Name of an interface that the signal belongs to - * @param[in] signalName Name of the signal - * @param[in] signalHandler Callback that implements the body of the signal handler - * - * @return RAII-style slot handle representing the ownership of the subscription - * - * A signal can be subscribed to and unsubscribed from at any time during proxy - * lifetime. The subscription is active immediately after the call. The subscription - * is unregistered when the client destroys the returned slot object. - * - * @throws sdbus::Error in case of failure - */ - [[nodiscard]] virtual Slot registerSignalHandler( const std::string& interfaceName - , const std::string& signalName - , signal_handler signalHandler - , return_slot_t ) = 0; - - /*! - * @brief Unregisters proxy's signal handlers and stops receiving replies to pending async calls - * - * Unregistration is done automatically also in proxy's destructor. This method makes - * sense if, in the process of proxy removal, we need to make sure that callbacks - * are unregistered explicitly before the final destruction of the proxy instance. - * - * @throws sdbus::Error in case of failure - */ - virtual void unregister() = 0; - /*! * @brief Calls method on the D-Bus object * @@ -289,6 +242,42 @@ namespace sdbus { */ [[nodiscard]] AsyncMethodInvoker callMethodAsync(const std::string& methodName); + /*! + * @brief Registers a handler for the desired signal emitted by the D-Bus object + * + * @param[in] interfaceName Name of an interface that the signal belongs to + * @param[in] signalName Name of the signal + * @param[in] signalHandler Callback that implements the body of the signal handler + * + * A signal can be subscribed to and unsubscribed from at any time during proxy + * lifetime. The subscription is active immediately after the call. + * + * @throws sdbus::Error in case of failure + */ + virtual void registerSignalHandler( const std::string& interfaceName + , const std::string& signalName + , signal_handler signalHandler ) = 0; + + /*! + * @brief Registers a handler for the desired signal emitted by the D-Bus object + * + * @param[in] interfaceName Name of an interface that the signal belongs to + * @param[in] signalName Name of the signal + * @param[in] signalHandler Callback that implements the body of the signal handler + * + * @return RAII-style slot handle representing the ownership of the subscription + * + * A signal can be subscribed to and unsubscribed from at any time during proxy + * lifetime. The subscription is active immediately after the call. The subscription + * is unregistered when the client destroys the returned slot object. + * + * @throws sdbus::Error in case of failure + */ + [[nodiscard]] virtual Slot registerSignalHandler( const std::string& interfaceName + , const std::string& signalName + , signal_handler signalHandler + , return_slot_t ) = 0; + /*! * @brief Registers signal handler for a given signal of the D-Bus object * @@ -312,6 +301,17 @@ namespace sdbus { */ [[nodiscard]] SignalSubscriber uponSignal(const std::string& signalName); + /*! + * @brief Unregisters proxy's signal handlers and stops receiving replies to pending async calls + * + * Unregistration is done automatically also in proxy's destructor. This method makes + * sense if, in the process of proxy removal, we need to make sure that callbacks + * are unregistered explicitly before the final destruction of the proxy instance. + * + * @throws sdbus::Error in case of failure + */ + virtual void unregister() = 0; + /*! * @brief Gets value of a property of the D-Bus object *