sdbus-c++ 1.5.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

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::IConnectiongetConnection () 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 MessagegetCurrentlyProcessedMessage () 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::Errorin 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]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< 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::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< 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::Errorin 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]interfaceNameName of an interface
Exceptions
sdbus::Errorin 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]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/2]

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

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

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 = ...;
object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2);
Exceptions
sdbus::Errorin 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::Errorin 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]interfaceNameName of an interface that the method will belong to
[in]methodNameName of the method
[in]inputSignatureD-Bus signature of method input parameters
[in]inputNamesNames of input parameters
[in]outputSignatureD-Bus signature of method output parameters
[in]outputNamesNames of output parameters
[in]methodCallbackCallback that implements the body of the method
[in]flagsD-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::Errorin 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]interfaceNameName of an interface that the method will belong to
[in]methodNameName of the method
[in]inputSignatureD-Bus signature of method input parameters
[in]outputSignatureD-Bus signature of method output parameters
[in]methodCallbackCallback that implements the body of the method
[in]flagsD-Bus method flags (privileged, deprecated, or no reply)
Exceptions
sdbus::Errorin 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]methodNameName 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::Errorin 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]interfaceNameName of an interface that the property will fall under
[in]propertyNameName of the property
[in]signatureD-Bus signature of property parameters
[in]getCallbackCallback that implements the body of the property getter
[in]flagsD-Bus property flags (deprecated, property update behavior)
Exceptions
sdbus::Errorin 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]interfaceNameName of an interface that the property will fall under
[in]propertyNameName of the property
[in]signatureD-Bus signature of property parameters
[in]getCallbackCallback that implements the body of the property getter
[in]setCallbackCallback that implements the body of the property setter
[in]flagsD-Bus property flags (deprecated, property update behavior)
Exceptions
sdbus::Errorin 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]propertyNameName 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::Errorin 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]interfaceNameName of an interface that the signal will fall under
[in]signalNameName of the signal
[in]signatureD-Bus signature of signal parameters
[in]paramNamesNames of parameters of the signal
[in]flagsD-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::Errorin 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]interfaceNameName of an interface that the signal will fall under
[in]signalNameName of the signal
[in]signatureD-Bus signature of signal parameters
[in]flagsD-Bus signal flags (deprecated)
Exceptions
sdbus::Errorin 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]signalNameName 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::Errorin 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::Errorin case of failure

◆ setInterfaceFlags() [1/2]

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

Sets flags (annotations) for a given interface.

Parameters
[in]interfaceNameName 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::Errorin 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]interfaceNameName of an interface whose flags will be set
[in]flagsFlags to be set
Exceptions
sdbus::Errorin 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::Errorin case of failure

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