sdbus-c++ 2.0.0
High-level C++ D-Bus library based on systemd D-Bus implementation
Loading...
Searching...
No Matches
sdbus::IObject Class Referenceabstract

#include <IObject.h>

Public Member Functions

VTableAdder addVTable (std::vector< VTableItem > vtable)
 Adds a declaration of methods, properties and signals of the object at a given interface.
 
template<typename... VTableItems, typename = std::enable_if_t<(is_one_of_variants_types<VTableItem, std::decay_t<VTableItems>> && ...)>>
VTableAdder addVTable (VTableItems &&... items)
 Adds a declaration of methods, properties and signals of the object at a given interface.
 
SignalEmitter emitSignal (const SignalName &signalName)
 Emits signal on D-Bus.
 
SignalEmitter emitSignal (const std::string &signalName)
 Emits signal on D-Bus.
 
SignalEmitter emitSignal (const char *signalName)
 Emits signal on D-Bus.
 
virtual void emitPropertiesChangedSignal (const InterfaceName &interfaceName, const std::vector< PropertyName > &propNames)=0
 Emits PropertyChanged signal for specified properties under a given interface of this object path.
 
virtual void emitPropertiesChangedSignal (const char *interfaceName, const std::vector< PropertyName > &propNames)=0
 Emits PropertyChanged signal for specified properties under a given interface of this object path.
 
virtual void emitPropertiesChangedSignal (const InterfaceName &interfaceName)=0
 Emits PropertyChanged signal for all properties on a given interface of this object path.
 
virtual void emitPropertiesChangedSignal (const char *interfaceName)=0
 Emits PropertyChanged signal for all properties on a given interface of this object path.
 
virtual void emitInterfacesAddedSignal ()=0
 Emits InterfacesAdded signal on this object path.
 
virtual void emitInterfacesAddedSignal (const std::vector< InterfaceName > &interfaces)=0
 Emits InterfacesAdded signal on this object path.
 
virtual void emitInterfacesRemovedSignal ()=0
 Emits InterfacesRemoved signal on this object path.
 
virtual void emitInterfacesRemovedSignal (const std::vector< InterfaceName > &interfaces)=0
 Emits InterfacesRemoved signal on this object path.
 
virtual void addObjectManager ()=0
 Adds an ObjectManager interface at the path of this D-Bus object.
 
virtual Slot addObjectManager (return_slot_t)=0
 Adds an ObjectManager interface at the path of this D-Bus object.
 
virtual sdbus::IConnectiongetConnection () const =0
 Provides D-Bus connection used by the object.
 
virtual const ObjectPathgetObjectPath () const =0
 Returns object path of the underlying DBus object.
 
virtual Message getCurrentlyProcessedMessage () const =0
 Provides access to the currently processed D-Bus message.
 
virtual void unregister ()=0
 Unregisters object's API and removes object from the bus.
 
template<typename... VTableItems, typename = std::enable_if_t<(is_one_of_variants_types<VTableItem, std::decay_t<VTableItems>> && ...)>>
void addVTable (InterfaceName interfaceName, VTableItems &&... items)
 Adds a declaration of methods, properties and signals of the object at a given interface.
 
virtual void addVTable (InterfaceName interfaceName, std::vector< VTableItem > vtable)=0
 Adds a declaration of methods, properties and signals of the object at a given interface.
 
virtual Slot addVTable (InterfaceName interfaceName, std::vector< VTableItem > vtable, return_slot_t)=0
 Adds a declaration of methods, properties and signals of the object at a given interface.
 
virtual Signal createSignal (const InterfaceName &interfaceName, const SignalName &signalName)=0
 Creates a signal message.
 
virtual void emitSignal (const sdbus::Signal &message)=0
 Emits signal for this object path.
 

Protected Member Functions

virtual Signal createSignal (const char *interfaceName, const char *signalName)=0
 

Protected Attributes

friend SignalEmitter
 

Detailed Description

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 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.

Member Function Documentation

◆ addObjectManager() [1/2]

virtual void sdbus::IObject::addObjectManager ( )
pure virtual

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.

Exceptions
sdbus::Errorin case of failure

◆ addObjectManager() [2/2]

virtual Slot sdbus::IObject::addObjectManager ( return_slot_t )
nodiscardpure virtual

Adds an ObjectManager interface at the path of this D-Bus object.

Returns
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.

Exceptions
sdbus::Errorin case of failure

◆ addVTable() [1/5]

virtual void sdbus::IObject::addVTable ( InterfaceName interfaceName,
std::vector< VTableItem > vtable )
pure virtual

Adds a declaration of methods, properties and signals of the object at a given interface.

Parameters
[in]interfaceNameName of an interface the the vtable is registered for
[in]vtableA 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.

Exceptions
sdbus::Errorin case of failure

◆ addVTable() [2/5]

virtual Slot sdbus::IObject::addVTable ( InterfaceName interfaceName,
std::vector< VTableItem > vtable,
return_slot_t  )
nodiscardpure virtual

Adds a declaration of methods, properties and signals of the object at a given interface.

Parameters
[in]interfaceNameName of an interface the the vtable is registered for
[in]vtableA 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.

Exceptions
sdbus::Errorin case of failure

◆ addVTable() [3/5]

template<typename... VTableItems, typename >
void sdbus::IObject::addVTable ( InterfaceName interfaceName,
VTableItems &&... items )

Adds a declaration of methods, properties and signals of the object at a given interface.

Parameters
[in]interfaceNameName of an interface the the vtable is registered for
[in]itemsIndividual 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.

Exceptions
sdbus::Errorin case of failure

◆ addVTable() [4/5]

VTableAdder sdbus::IObject::addVTable ( std::vector< VTableItem > vtable)
inlinenodiscard

Adds a declaration of methods, properties and signals of the object at a given interface.

Parameters
[in]vtableIndividual instances of VTable item structures stored in a vector
Returns
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.

Exceptions
sdbus::Errorin case of failure

◆ addVTable() [5/5]

template<typename... VTableItems, typename >
VTableAdder sdbus::IObject::addVTable ( VTableItems &&... items)
nodiscard

Adds a declaration of methods, properties and signals of the object at a given interface.

Parameters
[in]itemsIndividual instances of VTable item structures
Returns
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.

Exceptions
sdbus::Errorin case of failure

◆ createSignal()

virtual Signal sdbus::IObject::createSignal ( const InterfaceName & interfaceName,
const SignalName & signalName )
nodiscardpure virtual

Creates a signal message.

Parameters
[in]interfaceNameName of an interface that the signal belongs under
[in]signalNameName of the signal
Returns
A signal message

Serialize signal arguments into the returned message and emit the signal by passing the message with serialized arguments to the emitSignal function. Alternatively, use higher-level API emitSignal(const std::string& signalName) defined below.

Exceptions
sdbus::Errorin case of failure

◆ emitInterfacesAddedSignal() [1/2]

virtual void sdbus::IObject::emitInterfacesAddedSignal ( )
pure virtual

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.

Exceptions
sdbus::Errorin case of failure

◆ emitInterfacesAddedSignal() [2/2]

virtual void sdbus::IObject::emitInterfacesAddedSignal ( const std::vector< InterfaceName > & interfaces)
pure virtual

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.

Exceptions
sdbus::Errorin case of failure

◆ emitInterfacesRemovedSignal() [1/2]

virtual void sdbus::IObject::emitInterfacesRemovedSignal ( )
pure virtual

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.

Exceptions
sdbus::Errorin case of failure

◆ emitInterfacesRemovedSignal() [2/2]

virtual void sdbus::IObject::emitInterfacesRemovedSignal ( const std::vector< InterfaceName > & interfaces)
pure virtual

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.

Exceptions
sdbus::Errorin case of failure

◆ emitPropertiesChangedSignal() [1/4]

virtual void sdbus::IObject::emitPropertiesChangedSignal ( const char * interfaceName)
pure virtual

Emits PropertyChanged signal for all properties on a given interface of this object path.

Parameters
[in]interfaceNameName of an interface
Exceptions
sdbus::Errorin case of failure

◆ emitPropertiesChangedSignal() [2/4]

virtual void sdbus::IObject::emitPropertiesChangedSignal ( const char * interfaceName,
const std::vector< PropertyName > & propNames )
pure virtual

Emits PropertyChanged signal for specified properties under a given interface of this object path.

Parameters
[in]interfaceNameName of an interface that properties belong to
[in]propNamesNames of properties that will be included in the PropertiesChanged signal
Exceptions
sdbus::Errorin case of failure

◆ emitPropertiesChangedSignal() [3/4]

virtual void sdbus::IObject::emitPropertiesChangedSignal ( const InterfaceName & interfaceName)
pure virtual

Emits PropertyChanged signal for all properties on a given interface of this object path.

Parameters
[in]interfaceNameName of an interface
Exceptions
sdbus::Errorin case of failure

◆ emitPropertiesChangedSignal() [4/4]

virtual void sdbus::IObject::emitPropertiesChangedSignal ( const InterfaceName & interfaceName,
const std::vector< PropertyName > & propNames )
pure virtual

Emits PropertyChanged signal for specified properties under a given interface of this object path.

Parameters
[in]interfaceNameName of an interface that properties belong to
[in]propNamesNames of properties that will be included in the PropertiesChanged signal
Exceptions
sdbus::Errorin case of failure

◆ emitSignal() [1/4]

SignalEmitter sdbus::IObject::emitSignal ( const char * signalName)
inlinenodiscard

Emits signal on D-Bus.

Parameters
[in]signalNameName of the signal
Returns
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:

int arg1 = ...;
double arg2 = ...;
SignalName fooSignal{"fooSignal"};
object_.emitSignal(fooSignal).onInterface("com.kistler.foo").withArguments(arg1, arg2);
Definition Types.h:240
Exceptions
sdbus::Errorin case of failure

◆ emitSignal() [2/4]

virtual void sdbus::IObject::emitSignal ( const sdbus::Signal & message)
pure virtual

Emits signal for this object path.

Parameters
[in]messageSignal message to be sent out

Note: To avoid messing with messages, use higher-level API defined below.

Exceptions
sdbus::Errorin case of failure

◆ emitSignal() [3/4]

SignalEmitter sdbus::IObject::emitSignal ( const SignalName & signalName)
inlinenodiscard

Emits signal on D-Bus.

Parameters
[in]signalNameName of the signal
Returns
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:

int arg1 = ...;
double arg2 = ...;
SignalName fooSignal{"fooSignal"};
object_.emitSignal(fooSignal).onInterface("com.kistler.foo").withArguments(arg1, arg2);
Exceptions
sdbus::Errorin case of failure

◆ emitSignal() [4/4]

SignalEmitter sdbus::IObject::emitSignal ( const std::string & signalName)
inlinenodiscard

Emits signal on D-Bus.

Parameters
[in]signalNameName of the signal
Returns
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:

int arg1 = ...;
double arg2 = ...;
SignalName fooSignal{"fooSignal"};
object_.emitSignal(fooSignal).onInterface("com.kistler.foo").withArguments(arg1, arg2);
Exceptions
sdbus::Errorin case of failure

◆ getConnection()

virtual sdbus::IConnection & sdbus::IObject::getConnection ( ) const
nodiscardpure virtual

Provides D-Bus connection used by the object.

Returns
Reference to the D-Bus connection

◆ getCurrentlyProcessedMessage()

virtual Message sdbus::IObject::getCurrentlyProcessedMessage ( ) const
nodiscardpure virtual

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.

Returns
Currently processed D-Bus message

◆ unregister()

virtual void sdbus::IObject::unregister ( )
pure virtual

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.

Exceptions
sdbus::Errorin case of failure

The documentation for this class was generated from the following file: