mirror of
https://github.com/Kistler-Group/sdbus-cpp.git
synced 2026-01-25 15:12:20 +01:00
107c6a1a97
This reorganizes the layers of abstraction in the sense how `Message` depends on `Connection` and vice versa. Now, `Message` has a link to the `Connection`. This replaces the shortcut link to the low-level `SdBus` interface that the `Message` kept. The interactions from `Message` now go through `Connection` which forwards them to `SdBus`. `Connection` is now a sole owner of the low-level `SdBus` interface. This allows for future changes around `SdBus` (e.g. a change from virtual functions back to non-virtual functions) without affecting the rest of the library. `Proxy`s and `Object`s can now send messages directly without having to go through `Connection`. The `Connection` no more depends on `Message` business-logic methods; it serves only as a factory for messages. The flow for creating messages: `Proxy`/`Object` -> `Connection` -> `SdBus` The flow for sending messages: (`Proxy`/`Object` ->) `Message` -> `Connection` -> `SdBus` This also better reflects how dependencies are managed in the underlying sd-bus library. Additionally, `getSdBusInterface()` methods are removed which was anyway planned, and improves the design by "Tell, don't ask" principle. This refactoring is the necessary enabler for other upcoming improvements (regarding sending long messages, or creds refactoring, for example).
485 lines
22 KiB
C++
485 lines
22 KiB
C++
/**
|
|
* (C) 2016 - 2021 KISTLER INSTRUMENTE AG, Winterthur, Switzerland
|
|
* (C) 2016 - 2024 Stanislav Angelovic <stanislav.angelovic@protonmail.com>
|
|
*
|
|
* @file IObject.h
|
|
*
|
|
* Created on: Nov 8, 2016
|
|
* Project: sdbus-c++
|
|
* Description: High-level D-Bus IPC C++ library based on sd-bus
|
|
*
|
|
* This file is part of sdbus-c++.
|
|
*
|
|
* sdbus-c++ is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU Lesser General Public License as published by
|
|
* the Free Software Foundation, either version 2.1 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* sdbus-c++ is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public License
|
|
* along with sdbus-c++. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
#ifndef SDBUS_CXX_IOBJECT_H_
|
|
#define SDBUS_CXX_IOBJECT_H_
|
|
|
|
#include <sdbus-c++/ConvenienceApiClasses.h>
|
|
#include <sdbus-c++/Flags.h>
|
|
#include <sdbus-c++/TypeTraits.h>
|
|
#include <sdbus-c++/VTableItems.h>
|
|
|
|
#include <functional>
|
|
#include <memory>
|
|
#include <string>
|
|
#include <vector>
|
|
|
|
// Forward declarations
|
|
namespace sdbus {
|
|
class Signal;
|
|
class IConnection;
|
|
class ObjectPath;
|
|
}
|
|
|
|
namespace sdbus {
|
|
|
|
/********************************************//**
|
|
* @class IObject
|
|
*
|
|
* IObject class represents a D-Bus object instance identified by a specific object path.
|
|
* D-Bus object provides its interfaces, methods, signals and properties on a bus
|
|
* identified by a specific bus name.
|
|
*
|
|
* All IObject member methods throw @c sdbus::Error in case of D-Bus or sdbus-c++ error.
|
|
* The IObject class has been designed as thread-aware. However, the operation of
|
|
* creating and sending asynchronous method replies, as well as creating and emitting
|
|
* signals, is thread-safe by design.
|
|
*
|
|
***********************************************/
|
|
class IObject
|
|
{
|
|
public: // High-level, convenience API
|
|
virtual ~IObject() = default;
|
|
|
|
/*!
|
|
* @brief Adds a declaration of methods, properties and signals of the object at a given interface
|
|
*
|
|
* @param[in] vtable Individual instances of VTable item structures stored in a vector
|
|
* @return VTableAdder high-level helper class
|
|
*
|
|
* This method is used to declare attributes for the object under the given interface.
|
|
* Parameter `vtable' represents a vtable definition that may contain method declarations
|
|
* (using MethodVTableItem struct), property declarations (using PropertyVTableItem
|
|
* struct), signal declarations (using SignalVTableItem struct), or global interface
|
|
* flags (using InterfaceFlagsVTableItem struct).
|
|
*
|
|
* An interface can have any number of vtables attached to it.
|
|
*
|
|
* Consult manual pages for the underlying `sd_bus_add_object_vtable` function for more information.
|
|
*
|
|
* The method can be called at any time during object's lifetime.
|
|
*
|
|
* When called like `addVTable(vtable).forInterface(interface)`, then an internal registration
|
|
* slot is created for that vtable and its lifetime is tied to the lifetime of the Object instance.
|
|
* When called like `addVTable(items...).forInterface(interface, sdbus::return_slot)`, then an internal
|
|
* registration slot is created for the vtable and is returned to the caller. Keeping the slot means
|
|
* keep the registration "alive". Destroying the slot means that the vtable is not needed anymore,
|
|
* and the vtable gets removed from the object. This allows for "dynamic" object API where vtables
|
|
* can be added or removed by the user at runtime.
|
|
*
|
|
* The function provides strong exception guarantee. The state of the object remains
|
|
* unmodified in face of an exception.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
[[nodiscard]] VTableAdder addVTable(std::vector<VTableItem> vtable);
|
|
|
|
/*!
|
|
* @brief Adds a declaration of methods, properties and signals of the object at a given interface
|
|
*
|
|
* @param[in] items Individual instances of VTable item structures
|
|
* @return VTableAdder high-level helper class
|
|
*
|
|
* This method is used to declare attributes for the object under the given interface.
|
|
* Parameter pack contains vtable definition that may contain method declarations
|
|
* (using MethodVTableItem struct), property declarations (using PropertyVTableItem
|
|
* struct), signal declarations (using SignalVTableItem struct), or global interface
|
|
* flags (using InterfaceFlagsVTableItem struct).
|
|
*
|
|
* An interface can have any number of vtables attached to it.
|
|
*
|
|
* Consult manual pages for the underlying `sd_bus_add_object_vtable` function for more information.
|
|
*
|
|
* The method can be called at any time during object's lifetime.
|
|
*
|
|
* When called like `addVTable(items...).forInterface(interface)`, then an internal registration
|
|
* slot is created for that vtable and its lifetime is tied to the lifetime of the Object instance.
|
|
* When called like `addVTable(items...).forInterface(interface, sdbus::return_slot)`, then an internal
|
|
* registration slot is created for the vtable and is returned to the caller. Keeping the slot means
|
|
* keep the registration "alive". Destroying the slot means that the vtable is not needed anymore,
|
|
* and the vtable gets removed from the object. This allows for "dynamic" object API where vtables
|
|
* can be added or removed by the user at runtime.
|
|
*
|
|
* The function provides strong exception guarantee. The state of the object remains
|
|
* unmodified in face of an exception.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
template < typename... VTableItems
|
|
, typename = std::enable_if_t<(is_one_of_variants_types<VTableItem, std::decay_t<VTableItems>> && ...)> >
|
|
[[nodiscard]] VTableAdder addVTable(VTableItems&&... items);
|
|
|
|
/*!
|
|
* @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 = ...;
|
|
* SignalName fooSignal{"fooSignal"};
|
|
* object_.emitSignal(fooSignal).onInterface("com.kistler.foo").withArguments(arg1, arg2);
|
|
* @endcode
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
[[nodiscard]] SignalEmitter emitSignal(const SignalName& signalName);
|
|
|
|
/*!
|
|
* @copydoc IObject::emitSignal(const SignalName&)
|
|
*/
|
|
[[nodiscard]] SignalEmitter emitSignal(const std::string& signalName);
|
|
|
|
/*!
|
|
* @copydoc IObject::emitSignal(const SignalName&)
|
|
*/
|
|
[[nodiscard]] SignalEmitter emitSignal(const char* signalName);
|
|
|
|
/*!
|
|
* @brief Emits PropertyChanged signal for specified properties under a given interface of this object path
|
|
*
|
|
* @param[in] interfaceName Name of an interface that properties belong to
|
|
* @param[in] propNames Names of properties that will be included in the PropertiesChanged signal
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void emitPropertiesChangedSignal(const InterfaceName& interfaceName, const std::vector<PropertyName>& propNames) = 0;
|
|
|
|
/*!
|
|
* @copydoc IObject::emitPropertiesChangedSignal(const InterfaceName&,const std::vector<PropertyName>&)
|
|
*/
|
|
virtual void emitPropertiesChangedSignal(const char* interfaceName, const std::vector<PropertyName>& propNames) = 0;
|
|
|
|
/*!
|
|
* @brief Emits PropertyChanged signal for all properties on a given interface of this object path
|
|
*
|
|
* @param[in] interfaceName Name of an interface
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void emitPropertiesChangedSignal(const InterfaceName& interfaceName) = 0;
|
|
|
|
/*!
|
|
* @copydoc IObject::emitPropertiesChangedSignal(const InterfaceName&)
|
|
*/
|
|
virtual void emitPropertiesChangedSignal(const char* interfaceName) = 0;
|
|
|
|
/*!
|
|
* @brief Emits InterfacesAdded signal on this object path
|
|
*
|
|
* This emits an InterfacesAdded signal on this object path, by iterating all registered
|
|
* interfaces on the path. All properties are queried and included in the signal.
|
|
* This call is equivalent to emitInterfacesAddedSignal() with an explicit list of
|
|
* registered interfaces. However, unlike emitInterfacesAddedSignal(interfaces), this
|
|
* call can figure out the list of supported interfaces itself. Furthermore, it properly
|
|
* adds the builtin org.freedesktop.DBus.* interfaces.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void emitInterfacesAddedSignal() = 0;
|
|
|
|
/*!
|
|
* @brief Emits InterfacesAdded signal on this object path
|
|
*
|
|
* This emits an InterfacesAdded signal on this object path with explicitly provided list
|
|
* of registered interfaces. Since v2.0, sdbus-c++ supports dynamically addable/removable
|
|
* object interfaces and their vtables, so this method now makes more sense.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void emitInterfacesAddedSignal(const std::vector<InterfaceName>& interfaces) = 0;
|
|
|
|
/*!
|
|
* @brief Emits InterfacesRemoved signal on this object path
|
|
*
|
|
* This is like sd_bus_emit_object_added(), but emits an InterfacesRemoved signal on this
|
|
* object path. This only includes any registered interfaces but skips the properties.
|
|
* This function shall be called (just) before destroying the object.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void emitInterfacesRemovedSignal() = 0;
|
|
|
|
/*!
|
|
* @brief Emits InterfacesRemoved signal on this object path
|
|
*
|
|
* This emits an InterfacesRemoved signal on the given path with explicitly provided list
|
|
* of registered interfaces. Since v2.0, sdbus-c++ supports dynamically addable/removable
|
|
* object interfaces and their vtables, so this method now makes more sense.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void emitInterfacesRemovedSignal(const std::vector<InterfaceName>& interfaces) = 0;
|
|
|
|
/*!
|
|
* @brief Adds an ObjectManager interface at the path of this D-Bus object
|
|
*
|
|
* 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 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 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
|
|
*/
|
|
[[nodiscard]] virtual Slot addObjectManager(return_slot_t) = 0;
|
|
|
|
/*!
|
|
* @brief Provides D-Bus connection used by the object
|
|
*
|
|
* @return Reference to the D-Bus connection
|
|
*/
|
|
[[nodiscard]] virtual sdbus::IConnection& getConnection() const = 0;
|
|
|
|
/*!
|
|
* @brief Returns object path of the underlying DBus object
|
|
*/
|
|
[[nodiscard]] virtual const ObjectPath& getObjectPath() const = 0;
|
|
|
|
/*!
|
|
* @brief Provides access to the currently processed D-Bus message
|
|
*
|
|
* This method provides access to the currently processed incoming D-Bus message.
|
|
* "Currently processed" means that the registered callback handler(s) for that message
|
|
* are being invoked. This method is meant to be called from within a callback handler
|
|
* (e.g. from a D-Bus signal handler, or async method reply handler, etc.). In such a case it is
|
|
* guaranteed to return a valid D-Bus message instance for which the handler is called.
|
|
* If called from other contexts/threads, it may return a valid or invalid message, depending
|
|
* on whether a message was processed or not at the time of the call.
|
|
*
|
|
* @return Currently processed D-Bus message
|
|
*/
|
|
[[nodiscard]] virtual Message getCurrentlyProcessedMessage() const = 0;
|
|
|
|
/*!
|
|
* @brief Unregisters object's API and removes object from the bus
|
|
*
|
|
* This method unregisters the object, its interfaces, methods, signals and properties
|
|
* from the bus. Unregistration is done automatically also in object's destructor. This
|
|
* method makes sense if, in the process of object removal, we need to make sure that
|
|
* callbacks are unregistered explicitly before the final destruction of the object instance.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void unregister() = 0;
|
|
|
|
public: // Lower-level, message-based API
|
|
/*!
|
|
* @brief Adds a declaration of methods, properties and signals of the object at a given interface
|
|
*
|
|
* @param[in] interfaceName Name of an interface the the vtable is registered for
|
|
* @param[in] items Individual instances of VTable item structures
|
|
*
|
|
* This method is used to declare attributes for the object under the given interface.
|
|
* Parameter `items' represents a vtable definition that may contain method declarations
|
|
* (using MethodVTableItem struct), property declarations (using PropertyVTableItem
|
|
* struct), signal declarations (using SignalVTableItem struct), or global interface
|
|
* flags (using InterfaceFlagsVTableItem struct).
|
|
*
|
|
* An interface can have any number of vtables attached to it.
|
|
*
|
|
* Consult manual pages for the underlying `sd_bus_add_object_vtable` function for more information.
|
|
*
|
|
* The method can be called at any time during object's lifetime. For each vtable an internal
|
|
* registration slot is created and its lifetime is tied to the lifetime of the Object instance.
|
|
*
|
|
* The function provides strong exception guarantee. The state of the object remains
|
|
* unmodified in face of an exception.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
template < typename... VTableItems
|
|
, typename = std::enable_if_t<(is_one_of_variants_types<VTableItem, std::decay_t<VTableItems>> && ...)> >
|
|
void addVTable(InterfaceName interfaceName, VTableItems&&... items);
|
|
|
|
/*!
|
|
* @brief Adds a declaration of methods, properties and signals of the object at a given interface
|
|
*
|
|
* @param[in] interfaceName Name of an interface the the vtable is registered for
|
|
* @param[in] vtable A list of individual descriptions in the form of VTable item instances
|
|
*
|
|
* This method is used to declare attributes for the object under the given interface.
|
|
* The `vtable' parameter may contain method declarations (using MethodVTableItem struct),
|
|
* property declarations (using PropertyVTableItem struct), signal declarations (using
|
|
* SignalVTableItem struct), or global interface flags (using InterfaceFlagsVTableItem struct).
|
|
*
|
|
* An interface can have any number of vtables attached to it.
|
|
*
|
|
* Consult manual pages for the underlying `sd_bus_add_object_vtable` function for more information.
|
|
*
|
|
* The method can be called at any time during object's lifetime. For each vtable an internal
|
|
* registration slot is created and its lifetime is tied to the lifetime of the Object instance.
|
|
*
|
|
* The function provides strong exception guarantee. The state of the object remains
|
|
* unmodified in face of an exception.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void addVTable(InterfaceName interfaceName, std::vector<VTableItem> vtable) = 0;
|
|
|
|
/*!
|
|
* @brief Adds a declaration of methods, properties and signals of the object at a given interface
|
|
*
|
|
* @param[in] interfaceName Name of an interface the the vtable is registered for
|
|
* @param[in] vtable A list of individual descriptions in the form of VTable item instances
|
|
*
|
|
* This method is used to declare attributes for the object under the given interface.
|
|
* The `vtable' parameter may contain method declarations (using MethodVTableItem struct),
|
|
* property declarations (using PropertyVTableItem struct), signal declarations (using
|
|
* SignalVTableItem struct), or global interface flags (using InterfaceFlagsVTableItem struct).
|
|
*
|
|
* An interface can have any number of vtables attached to it.
|
|
*
|
|
* Consult manual pages for the underlying `sd_bus_add_object_vtable` function for more information.
|
|
*
|
|
* The method can be called at any time during object's lifetime. For each vtable an internal
|
|
* registration slot is created and is returned to the caller. The returned slot should be destroyed
|
|
* when the vtable is not needed anymore. This allows for "dynamic" object API where vtables
|
|
* can be added or removed by the user at runtime.
|
|
*
|
|
* The function provides strong exception guarantee. The state of the object remains
|
|
* unmodified in face of an exception.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
[[nodiscard]] virtual Slot addVTable(InterfaceName interfaceName, std::vector<VTableItem> vtable, return_slot_t) = 0;
|
|
|
|
/*!
|
|
* @brief Creates a signal message
|
|
*
|
|
* @param[in] interfaceName Name of an interface that the signal belongs under
|
|
* @param[in] signalName Name of the signal
|
|
* @return A signal message
|
|
*
|
|
* Serialize signal arguments into the returned message and emit the signal by passing
|
|
* the message with serialized arguments to the @c emitSignal function.
|
|
* Alternatively, use higher-level API @c emitSignal(const std::string& signalName) defined below.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
[[nodiscard]] virtual Signal createSignal(const InterfaceName& interfaceName, const SignalName& signalName) const = 0;
|
|
|
|
/*!
|
|
* @brief Emits signal for this object path
|
|
*
|
|
* @param[in] message Signal message to be sent out
|
|
*
|
|
* Note: To avoid messing with messages, use higher-level API defined below.
|
|
*
|
|
* @throws sdbus::Error in case of failure
|
|
*/
|
|
virtual void emitSignal(const sdbus::Signal& message) = 0;
|
|
|
|
protected: // Internal API for efficiency reasons used by high-level API helper classes
|
|
friend SignalEmitter;
|
|
|
|
[[nodiscard]] virtual Signal createSignal(const char* interfaceName, const char* signalName) const = 0;
|
|
};
|
|
|
|
// Out-of-line member definitions
|
|
|
|
inline SignalEmitter IObject::emitSignal(const SignalName& signalName)
|
|
{
|
|
return SignalEmitter(*this, signalName);
|
|
}
|
|
|
|
inline SignalEmitter IObject::emitSignal(const std::string& signalName)
|
|
{
|
|
return SignalEmitter(*this, signalName.c_str());
|
|
}
|
|
|
|
inline SignalEmitter IObject::emitSignal(const char* signalName)
|
|
{
|
|
return SignalEmitter(*this, signalName);
|
|
}
|
|
|
|
template <typename... VTableItems, typename>
|
|
void IObject::addVTable(InterfaceName interfaceName, VTableItems&&... items)
|
|
{
|
|
addVTable(std::move(interfaceName), {std::forward<VTableItems>(items)...});
|
|
}
|
|
|
|
template <typename... VTableItems, typename>
|
|
VTableAdder IObject::addVTable(VTableItems&&... items)
|
|
{
|
|
return addVTable(std::vector<VTableItem>{std::forward<VTableItems>(items)...});
|
|
}
|
|
|
|
inline VTableAdder IObject::addVTable(std::vector<VTableItem> vtable)
|
|
{
|
|
return VTableAdder(*this, std::move(vtable));
|
|
}
|
|
|
|
/*!
|
|
* @brief Creates instance representing a D-Bus object
|
|
*
|
|
* @param[in] connection D-Bus connection to be used by the object
|
|
* @param[in] objectPath Path of the D-Bus object
|
|
* @return Pointer to the object representation instance
|
|
*
|
|
* The provided connection will be used by the object to export methods,
|
|
* issue signals and provide properties.
|
|
*
|
|
* Creating a D-Bus object instance is (thread-)safe even upon the connection
|
|
* which is already running its I/O event loop.
|
|
*
|
|
* Code example:
|
|
* @code
|
|
* auto proxy = sdbus::createObject(connection, "/com/kistler/foo");
|
|
* @endcode
|
|
*/
|
|
[[nodiscard]] std::unique_ptr<sdbus::IObject> createObject(sdbus::IConnection& connection, ObjectPath objectPath);
|
|
|
|
}
|
|
|
|
#include <sdbus-c++/ConvenienceApiClasses.inl>
|
|
#include <sdbus-c++/VTableItems.inl>
|
|
|
|
#endif /* SDBUS_CXX_IOBJECT_H_ */
|