sdbus-c++: sdbus::IObject Class Reference

sdbus-c++ 1.4.0 High-level C++ D-Bus library based on systemd D-Bus implementation

Loading...
Searching...
No Matches
Public Member Functions | List of all members
sdbus::IObject Class Referenceabstract

`#include <IObject.h>`

## Public Member Functions
virtual void | registerMethod (const std::string &interfaceName, std::string methodName, std::string inputSignature, std::string outputSignature, method_callback methodCallback, Flags flags={})=0
| Registers method that the object will provide on D-Bus.
virtual void | registerMethod (const std::string &interfaceName, std::string methodName, std::string inputSignature, const std::vector< std::string > &inputNames, std::string outputSignature, const std::vector< std::string > &outputNames, method_callback methodCallback, Flags flags={})=0
| Registers method that the object will provide on D-Bus.
virtual void | registerSignal (const std::string &interfaceName, std::string signalName, std::string signature, Flags flags={})=0
| Registers signal that the object will emit on D-Bus.
virtual void | registerSignal (const std::string &interfaceName, std::string signalName, std::string signature, const std::vector< std::string > &paramNames, Flags flags={})=0
| Registers signal that the object will emit on D-Bus.
virtual void | registerProperty (const std::string &interfaceName, std::string propertyName, std::string signature, property_get_callback getCallback, Flags flags={})=0
| Registers read-only property that the object will provide on D-Bus.
virtual void | registerProperty (const std::string &interfaceName, std::string propertyName, std::string signature, property_get_callback getCallback, property_set_callback setCallback, Flags flags={})=0
| Registers read/write property that the object will provide on D-Bus.
virtual void | setInterfaceFlags (const std::string &interfaceName, Flags flags)=0
| Sets flags for a given interface.
virtual void | finishRegistration ()=0
| Finishes object API registration and publishes the object on the bus.
virtual void | unregister ()=0
| Unregisters object's API and removes object from the bus.
virtual Signal | createSignal (const std::string &interfaceName, const std::string &signalName)=0
| Creates a signal message.
virtual void | emitSignal (const sdbus::Signal &message)=0
| Emits signal for this object path.
virtual void | emitPropertiesChangedSignal (const std::string &interfaceName, const std::vector< std::string > &propNames)=0
| Emits PropertyChanged signal for specified properties under a given interface of this object path.
virtual void | emitPropertiesChangedSignal (const std::string &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< std::string > &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< std::string > &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 void | removeObjectManager ()=0
| Removes an ObjectManager interface from the path of this D-Bus object.
virtual bool | hasObjectManager () const =0
| Tests whether ObjectManager interface is added at the path of this D-Bus object.
virtual sdbus::IConnection & | getConnection () const =0
| Provides D-Bus connection used by the object.
MethodRegistrator | registerMethod (const std::string &methodName)
| Registers method that the object will provide on D-Bus.
SignalRegistrator | registerSignal (const std::string &signalName)
| Registers signal that the object will provide on D-Bus.
PropertyRegistrator | registerProperty (const std::string &propertyName)
| Registers property that the object will provide on D-Bus.
InterfaceFlagsSetter | setInterfaceFlags (const std::string &interfaceName)
| Sets flags (annotations) for a given interface.
SignalEmitter | emitSignal (const std::string &signalName)
| Emits signal on D-Bus.
virtual const std::string & | getObjectPath () const =0
| Returns object path of the underlying DBus object.
virtual const Message * | getCurrentlyProcessedMessage () const =0
| Provides currently processed D-Bus message.

## 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()

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.

Exceptions

  sdbus::Error | in case of failure

## ◆ createSignal()

virtual Signal sdbus::IObject::createSignal | ( | const std::string & | interfaceName,
|  | const std::string & | signalName )
| pure virtual

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< std::string > & | 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. As sdbus-c++ does currently not supported adding/removing interfaces of an existing object at run time (an object has a fixed set of interfaces registered by the time of invoking finishRegistration()), emitInterfacesAddedSignal(void) is probably what you are looking for.

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< std::string > & | 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. As sdbus-c++ does currently not supported adding/removing interfaces of an existing object at run time (an object has a fixed set of interfaces registered by the time of invoking finishRegistration()), emitInterfacesRemovedSignal(void) is probably what you are looking for.

Exceptions

  sdbus::Error | in case of failure

## ◆ emitPropertiesChangedSignal() [1/2]

virtual void sdbus::IObject::emitPropertiesChangedSignal | ( | const std::string & | 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/2]

virtual void sdbus::IObject::emitPropertiesChangedSignal | ( | const std::string & | interfaceName,
|  | const std::vector< std::string > & | 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/2]

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() [2/2]

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

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 = ...;
object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2);

Exceptions

  sdbus::Error | in case of failure

## ◆ finishRegistration()

virtual void sdbus::IObject::finishRegistration | ( |  | ) |
| pure virtual

Finishes object API registration and publishes the object on the bus.

The method exports all up to now registered methods, signals and properties on D-Bus. Must be called after all methods, signals and properties have been registered.

Exceptions

  sdbus::Error | in case of failure

## ◆ getConnection()

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

Provides D-Bus connection used by the object.

Returns
  Reference to the D-Bus connection

## ◆ getCurrentlyProcessedMessage()

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

Provides currently processed D-Bus message.

This method provides immutable 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. D-Bus method implementation handler). In such a case it is guaranteed to return a valid pointer to the D-Bus message for which the handler is called. If called from other contexts/threads, it may return a nonzero pointer or a nullptr, depending on whether a message was processed at the time of call or not, but the value is nondereferencable, since the pointed-to message may have gone in the meantime.

Returns
  A pointer to the currently processed D-Bus message

## ◆ hasObjectManager()

virtual bool sdbus::IObject::hasObjectManager | ( |  | ) | const
| pure virtual

Tests whether ObjectManager interface is added at the path of this D-Bus object.

Returns
  True if ObjectManager interface is there, false otherwise

## ◆ registerMethod() [1/3]

virtual void sdbus::IObject::registerMethod | ( | const std::string & | interfaceName,
|  | std::string | methodName,
|  | std::string | inputSignature,
|  | const std::vector< std::string > & | inputNames,
|  | std::string | outputSignature,
|  | const std::vector< std::string > & | outputNames,
|  | method_callback | methodCallback,
|  | Flags | flags = {} )
| pure virtual

Registers method that the object will provide on D-Bus.

Parameters

  [in] | interfaceName | Name of an interface that the method will belong to
  [in] | methodName | Name of the method
  [in] | inputSignature | D-Bus signature of method input parameters
  [in] | inputNames | Names of input parameters
  [in] | outputSignature | D-Bus signature of method output parameters
  [in] | outputNames | Names of output parameters
  [in] | methodCallback | Callback that implements the body of the method
  [in] | flags | D-Bus method flags (privileged, deprecated, or no reply)

Provided names of input and output parameters will be included in the introspection description (given that at least version 242 of underlying libsystemd library is used; otherwise, names of parameters are ignored). This usually helps better describe the API to the introspector.

Exceptions

  sdbus::Error | in case of failure

## ◆ registerMethod() [2/3]

virtual void sdbus::IObject::registerMethod | ( | const std::string & | interfaceName,
|  | std::string | methodName,
|  | std::string | inputSignature,
|  | std::string | outputSignature,
|  | method_callback | methodCallback,
|  | Flags | flags = {} )
| pure virtual

Registers method that the object will provide on D-Bus.

Parameters

  [in] | interfaceName | Name of an interface that the method will belong to
  [in] | methodName | Name of the method
  [in] | inputSignature | D-Bus signature of method input parameters
  [in] | outputSignature | D-Bus signature of method output parameters
  [in] | methodCallback | Callback that implements the body of the method
  [in] | flags | D-Bus method flags (privileged, deprecated, or no reply)

Exceptions

  sdbus::Error | in case of failure

## ◆ registerMethod() [3/3]

MethodRegistrator sdbus::IObject::registerMethod | ( | const std::string & | methodName | ) |
| inline

Registers method that the object will provide on D-Bus.

Parameters

  [in] | methodName | Name of the method

Returns
  A helper object for convenient registration of the method

This is a high-level, convenience way of registering D-Bus methods that abstracts from the D-Bus message concept. Method arguments/return value are automatically (de)serialized in a message and D-Bus signatures automatically deduced from the parameters and return type of the provided native method implementation callback.

Example of use:

object.registerMethod("doFoo").onInterface("com.kistler.foo").implementedAs([this](int value){ return this->doFoo(value); });

Exceptions

  sdbus::Error | in case of failure

## ◆ registerProperty() [1/3]

virtual void sdbus::IObject::registerProperty | ( | const std::string & | interfaceName,
|  | std::string | propertyName,
|  | std::string | signature,
|  | property_get_callback | getCallback,
|  | Flags | flags = {} )
| pure virtual

Registers read-only property that the object will provide on D-Bus.

Parameters

  [in] | interfaceName | Name of an interface that the property will fall under
  [in] | propertyName | Name of the property
  [in] | signature | D-Bus signature of property parameters
  [in] | getCallback | Callback that implements the body of the property getter
  [in] | flags | D-Bus property flags (deprecated, property update behavior)

Exceptions

  sdbus::Error | in case of failure

## ◆ registerProperty() [2/3]

virtual void sdbus::IObject::registerProperty | ( | const std::string & | interfaceName,
|  | std::string | propertyName,
|  | std::string | signature,
|  | property_get_callback | getCallback,
|  | property_set_callback | setCallback,
|  | Flags | flags = {} )
| pure virtual

Registers read/write property that the object will provide on D-Bus.

Parameters

  [in] | interfaceName | Name of an interface that the property will fall under
  [in] | propertyName | Name of the property
  [in] | signature | D-Bus signature of property parameters
  [in] | getCallback | Callback that implements the body of the property getter
  [in] | setCallback | Callback that implements the body of the property setter
  [in] | flags | D-Bus property flags (deprecated, property update behavior)

Exceptions

  sdbus::Error | in case of failure

## ◆ registerProperty() [3/3]

PropertyRegistrator sdbus::IObject::registerProperty | ( | const std::string & | propertyName | ) |
| inline

Registers property that the object will provide on D-Bus.

Parameters

  [in] | propertyName | Name of the property

Returns
  A helper object for convenient registration of the property

This is a high-level, convenience way of registering D-Bus properties that abstracts from the D-Bus message concept. Property arguments are automatically (de)serialized in a message and D-Bus signatures automatically deduced from the provided native callbacks.

Example of use:

object_.registerProperty("state").onInterface("com.kistler.foo").withGetter([this](){ return this->state(); });

Exceptions

  sdbus::Error | in case of failure

## ◆ registerSignal() [1/3]

virtual void sdbus::IObject::registerSignal | ( | const std::string & | interfaceName,
|  | std::string | signalName,
|  | std::string | signature,
|  | const std::vector< std::string > & | paramNames,
|  | Flags | flags = {} )
| pure virtual

Registers signal that the object will emit on D-Bus.

Parameters

  [in] | interfaceName | Name of an interface that the signal will fall under
  [in] | signalName | Name of the signal
  [in] | signature | D-Bus signature of signal parameters
  [in] | paramNames | Names of parameters of the signal
  [in] | flags | D-Bus signal flags (deprecated)

Provided names of signal output parameters will be included in the introspection description (given that at least version 242 of underlying libsystemd library is used; otherwise, names of parameters are ignored). This usually helps better describe the API to the introspector.

Exceptions

  sdbus::Error | in case of failure

## ◆ registerSignal() [2/3]

virtual void sdbus::IObject::registerSignal | ( | const std::string & | interfaceName,
|  | std::string | signalName,
|  | std::string | signature,
|  | Flags | flags = {} )
| pure virtual

Registers signal that the object will emit on D-Bus.

Parameters

  [in] | interfaceName | Name of an interface that the signal will fall under
  [in] | signalName | Name of the signal
  [in] | signature | D-Bus signature of signal parameters
  [in] | flags | D-Bus signal flags (deprecated)

Exceptions

  sdbus::Error | in case of failure

## ◆ registerSignal() [3/3]

SignalRegistrator sdbus::IObject::registerSignal | ( | const std::string & | signalName | ) |
| inline

Registers signal that the object will provide on D-Bus.

Parameters

  [in] | signalName | Name of the signal

Returns
  A helper object for convenient registration of the signal

This is a high-level, convenience way of registering D-Bus signals that abstracts from the D-Bus message concept. Signal arguments are automatically (de)serialized in a message and D-Bus signatures automatically deduced from the provided native parameters.

Example of use:

object.registerSignal("paramChange").onInterface("com.kistler.foo").withParameters<std::map<int32_t, std::string>>();

Exceptions

  sdbus::Error | in case of failure

## ◆ removeObjectManager()

virtual void sdbus::IObject::removeObjectManager | ( |  | ) |
| pure virtual

Removes an ObjectManager interface from the path of this D-Bus object.

Exceptions

  sdbus::Error | in case of failure

## ◆ setInterfaceFlags() [1/2]

InterfaceFlagsSetter sdbus::IObject::setInterfaceFlags | ( | const std::string & | interfaceName | ) |
| inline

Sets flags (annotations) for a given interface.

Parameters

  [in] | interfaceName | Name of an interface whose flags will be set

Returns
  A helper object for convenient setting of Interface flags

This is a high-level, convenience alternative to the other setInterfaceFlags overload.

Example of use:

object_.setInterfaceFlags("com.kistler.foo").markAsDeprecated().withPropertyUpdateBehavior(sdbus::Flags::EMITS_NO_SIGNAL);

Exceptions

  sdbus::Error | in case of failure

## ◆ setInterfaceFlags() [2/2]

virtual void sdbus::IObject::setInterfaceFlags | ( | const std::string & | interfaceName,
|  | Flags | flags )
| pure virtual

Sets flags for a given interface.

Parameters

  [in] | interfaceName | Name of an interface whose flags will be set
  [in] | flags | Flags to be set

Exceptions

  sdbus::Error | in case of failure

## ◆ 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