Loading...
Searching...
No Matches
sdbus::IObject Class Referenceabstract

`#include <IObject.h>`

## Public Member Functions

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::IConnection & | getConnection () const =0
| Provides D-Bus connection used by the object.
virtual const ObjectPath & | getObjectPath () 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.
virtual Signal | createSignal (const InterfaceName &interfaceName, const SignalName &signalName) const =0
| Adds a declaration of methods, properties and signals of the object at a given interface.
virtual void | emitSignal (const sdbus::Signal &message)=0
| Emits signal for this object path.
template<typename... VTableItems, typename>
void | addVTable (InterfaceName interfaceName, VTableItems &&... items)

## Protected Member Functions

virtual Signal | createSignal (const char *interfaceName, const char *signalName) const =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::Error | in case of failure

## addObjectManager() [2/2]

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

nodiscard pure 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::Error | in case of failure

## addVTable()

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] | vtable | Individual 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::Error | in case of failure */ [[nodiscard]] VTableAdder addVTable(std::vector<VTableItem> vtable);

/*!

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

Parameters

  [in] | items | Individual 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::Error | in case of failure

## createSignal()

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

nodiscard pure virtual

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

Parameters

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

Exceptions

  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);

/*!

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

Parameters

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

Exceptions

  sdbus::Error | in case of failure */ 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

Parameters

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

Exceptions

  sdbus::Error | in case of failure */ [[nodiscard]] virtual Slot addVTable(InterfaceName interfaceName, std::vector<VTableItem> vtable, return_slot_t) = 0;

/*!

Creates a signal message

Parameters

  [in] | interfaceName | Name of an interface that the signal belongs under
  [in] | signalName | Name 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::Error | in 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::Error | in 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::Error | in 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::Error | in 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::Error | in 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] | interfaceName | Name of an interface

Exceptions

  sdbus::Error | in 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] | interfaceName | Name of an interface that properties belong to
  [in] | propNames | Names of properties that will be included in the PropertiesChanged signal

Exceptions

  sdbus::Error | in 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] | interfaceName | Name of an interface

Exceptions

  sdbus::Error | in 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] | interfaceName | Name of an interface that properties belong to
  [in] | propNames | Names of properties that will be included in the PropertiesChanged signal

Exceptions

  sdbus::Error | in case of failure

## emitSignal() [1/4]

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

inline nodiscard

Emits signal on D-Bus.

Parameters

  [in] | signalName | Name 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::Error | in 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] | message | Signal message to be sent out

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

Exceptions

  sdbus::Error | in case of failure

## emitSignal() [3/4]

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

inline nodiscard

Emits signal on D-Bus.

Parameters

  [in] | signalName | Name 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::Error | in case of failure

## emitSignal() [4/4]

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

inline nodiscard

Emits signal on D-Bus.

Parameters

  [in] | signalName | Name 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::Error | in case of failure

## getConnection()

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

nodiscard pure virtual

Provides D-Bus connection used by the object.

Returns
  Reference to the D-Bus connection

## getCurrentlyProcessedMessage()

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

nodiscard pure 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::Error | in case of failure

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

- include/sdbus-c++/IObject.h