sdbus-c++ 1.2.0
High-level C++ D-Bus library based on systemd D-Bus implementation
sdbus::IProxy Class Referenceabstract

#include <IProxy.h>

Public Member Functions

virtual MethodCall createMethodCall (const std::string &interfaceName, const std::string &methodName)=0
 Creates a method call message. More...
 
virtual MethodReply callMethod (const MethodCall &message, uint64_t timeout=0)=0
 Calls method on the proxied D-Bus object. More...
 
template<typename _Rep , typename _Period >
MethodReply callMethod (const MethodCall &message, const std::chrono::duration< _Rep, _Period > &timeout)
 Calls method on the proxied D-Bus object. More...
 
virtual PendingAsyncCall callMethod (const MethodCall &message, async_reply_handler asyncReplyCallback, uint64_t timeout=0)=0
 Calls method on the proxied D-Bus object asynchronously. More...
 
template<typename _Rep , typename _Period >
PendingAsyncCall callMethod (const MethodCall &message, async_reply_handler asyncReplyCallback, const std::chrono::duration< _Rep, _Period > &timeout)
 Calls method on the proxied D-Bus object asynchronously. More...
 
virtual void registerSignalHandler (const std::string &interfaceName, const std::string &signalName, signal_handler signalHandler)=0
 Registers a handler for the desired signal emitted by the proxied D-Bus object. More...
 
virtual void unregisterSignalHandler (const std::string &interfaceName, const std::string &signalName)=0
 Unregisters the handler of the desired signal. More...
 
virtual void finishRegistration ()=0
 Finishes the registration of signal handlers. More...
 
virtual void unregister ()=0
 Unregisters proxy's signal handlers and stops receving replies to pending async calls. More...
 
MethodInvoker callMethod (const std::string &methodName)
 Calls method on the proxied D-Bus object. More...
 
AsyncMethodInvoker callMethodAsync (const std::string &methodName)
 Calls method on the proxied D-Bus object asynchronously. More...
 
SignalSubscriber uponSignal (const std::string &signalName)
 Registers signal handler for a given signal of the proxied D-Bus object. More...
 
SignalUnsubscriber muteSignal (const std::string &signalName)
 Unregisters signal handler of a given signal of the proxied D-Bus object. More...
 
PropertyGetter getProperty (const std::string &propertyName)
 Gets value of a property of the proxied D-Bus object. More...
 
PropertySetter setProperty (const std::string &propertyName)
 Sets value of a property of the proxied D-Bus object. More...
 
virtual sdbus::IConnectiongetConnection () const =0
 Provides D-Bus connection used by the proxy. More...
 
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. More...
 

Detailed Description

IProxy class represents a proxy object, which is a convenient local object created to represent a remote D-Bus object in another process. The proxy enables calling methods on remote objects, receiving signals from remote objects, and getting/setting properties of remote objects.

All IProxy member methods throw sdbus::Error in case of D-Bus or sdbus-c++ error. The IProxy class has been designed as thread-aware. However, the operation of creating and sending method calls (both synchronously and asynchronously) is thread-safe by design.

Member Function Documentation

◆ callMethod() [1/5]

template<typename _Rep , typename _Period >
PendingAsyncCall sdbus::IProxy::callMethod ( const MethodCall message,
async_reply_handler  asyncReplyCallback,
const std::chrono::duration< _Rep, _Period > &  timeout 
)
inline

Calls method on the proxied D-Bus object asynchronously.

Parameters
[in]messageMessage representing an async method call
[in]asyncReplyCallbackHandler for the async reply
[in]timeoutTimeout for dbus call in microseconds
Returns
Cookie for the the pending asynchronous call

The call is non-blocking. It doesn't wait for the reply. Once the reply arrives, the provided async reply handler will get invoked from the context of the connection I/O event loop thread.

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

Exceptions
sdbus::Errorin case of failure

◆ callMethod() [2/5]

virtual PendingAsyncCall sdbus::IProxy::callMethod ( const MethodCall message,
async_reply_handler  asyncReplyCallback,
uint64_t  timeout = 0 
)
pure virtual

Calls method on the proxied D-Bus object asynchronously.

Parameters
[in]messageMessage representing an async method call
[in]asyncReplyCallbackHandler for the async reply
[in]timeoutTimeout for dbus call in microseconds
Returns
Cookie for the the pending asynchronous call

The call is non-blocking. It doesn't wait for the reply. Once the reply arrives, the provided async reply handler will get invoked from the context of the connection I/O event loop thread.

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

Exceptions
sdbus::Errorin case of failure

◆ callMethod() [3/5]

template<typename _Rep , typename _Period >
MethodReply sdbus::IProxy::callMethod ( const MethodCall message,
const std::chrono::duration< _Rep, _Period > &  timeout 
)
inline

Calls method on the proxied D-Bus object.

Parameters
[in]messageMessage representing a method call
[in]timeoutTimeout for dbus call in microseconds
Returns
A method reply message

Normally, the call is blocking, i.e. it waits for the remote method to finish with either a return value or an error.

If the method call argument is set to not expect reply, the call will not wait for the remote method to finish, i.e. the call will be non-blocking, and the function will return an empty, invalid MethodReply object (representing void).

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

Exceptions
sdbus::Errorin case of failure

◆ callMethod() [4/5]

virtual MethodReply sdbus::IProxy::callMethod ( const MethodCall message,
uint64_t  timeout = 0 
)
pure virtual

Calls method on the proxied D-Bus object.

Parameters
[in]messageMessage representing a method call
[in]timeoutTimeout for dbus call in microseconds
Returns
A method reply message

Normally, the call is blocking, i.e. it waits for the remote method to finish with either a return value or an error.

If the method call argument is set to not expect reply, the call will not wait for the remote method to finish, i.e. the call will be non-blocking, and the function will return an empty, invalid MethodReply object (representing void).

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

Exceptions
sdbus::Errorin case of failure

◆ callMethod() [5/5]

MethodInvoker sdbus::IProxy::callMethod ( const std::string &  methodName)
inline

Calls method on the proxied D-Bus object.

Parameters
[in]methodNameName of the method
Returns
A helper object for convenient invocation of the method

This is a high-level, convenience way of calling 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 provided native arguments and return values.

Example of use:

int result, a = ..., b = ...;
object_.callMethod("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result);
Exceptions
sdbus::Errorin case of failure

◆ callMethodAsync()

AsyncMethodInvoker sdbus::IProxy::callMethodAsync ( const std::string &  methodName)
inline

Calls method on the proxied D-Bus object asynchronously.

Parameters
[in]methodNameName of the method
Returns
A helper object for convenient asynchronous invocation of the method

This is a high-level, convenience way of calling 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 provided native arguments and return values.

Example of use:

int a = ..., b = ...;
object_.callMethodAsync("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).uponReplyInvoke([](int result)
{
std::cout << "Got result of multiplying " << a << " and " << b << ": " << result << std::endl;
});
Exceptions
sdbus::Errorin case of failure

◆ createMethodCall()

virtual MethodCall sdbus::IProxy::createMethodCall ( const std::string &  interfaceName,
const std::string &  methodName 
)
pure virtual

Creates a method call message.

Parameters
[in]interfaceNameName of an interface that provides a given method
[in]methodNameName of the method
Returns
A method call message

Serialize method arguments into the returned message and invoke the method by passing the message with serialized arguments to the callMethod function. Alternatively, use higher-level API callMethod(const std::string& methodName) defined below.

Exceptions
sdbus::Errorin case of failure

◆ finishRegistration()

virtual void sdbus::IProxy::finishRegistration ( )
pure virtual

Finishes the registration of signal handlers.

The method physically subscribes to the desired signals. Must be called only once, after all signals have been registered already.

Exceptions
sdbus::Errorin case of failure

◆ getConnection()

virtual sdbus::IConnection & sdbus::IProxy::getConnection ( ) const
pure virtual

Provides D-Bus connection used by the proxy.

Returns
Reference to the D-Bus connection

◆ getCurrentlyProcessedMessage()

virtual const Message * sdbus::IProxy::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. from a D-Bus signal handler, or async method reply handler, etc.). 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

◆ getProperty()

PropertyGetter sdbus::IProxy::getProperty ( const std::string &  propertyName)
inline

Gets value of a property of the proxied D-Bus object.

Parameters
[in]propertyNameName of the property
Returns
A helper object for convenient getting of property value

This is a high-level, convenience way of reading D-Bus property values that abstracts from the D-Bus message concept. sdbus::Variant is returned which shall then be converted to the real property type (implicit conversion is supported).

Example of use:

int state = object.getProperty("state").onInterface("com.kistler.foo");
Exceptions
sdbus::Errorin case of failure

◆ muteSignal()

SignalUnsubscriber sdbus::IProxy::muteSignal ( const std::string &  signalName)
inline

Unregisters signal handler of a given signal of the proxied D-Bus object.

Parameters
[in]signalNameName of the signal
Returns
A helper object for convenient unregistration of the signal handler

This is a high-level, convenience way of unregistering a D-Bus signal's handler.

Example of use:

object_.muteSignal("fooSignal").onInterface("com.kistler.foo");
Exceptions
sdbus::Errorin case of failure

◆ registerSignalHandler()

virtual void sdbus::IProxy::registerSignalHandler ( const std::string &  interfaceName,
const std::string &  signalName,
signal_handler  signalHandler 
)
pure virtual

Registers a handler for the desired signal emitted by the proxied D-Bus object.

Parameters
[in]interfaceNameName of an interface that the signal belongs to
[in]signalNameName of the signal
[in]signalHandlerCallback that implements the body of the signal handler
Exceptions
sdbus::Errorin case of failure

◆ setProperty()

PropertySetter sdbus::IProxy::setProperty ( const std::string &  propertyName)
inline

Sets value of a property of the proxied D-Bus object.

Parameters
[in]propertyNameName of the property
Returns
A helper object for convenient setting of property value

This is a high-level, convenience way of writing D-Bus property values that abstracts from the D-Bus message concept.

Example of use:

int state = ...;
object_.setProperty("state").onInterface("com.kistler.foo").toValue(state);
Exceptions
sdbus::Errorin case of failure

◆ unregister()

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

Unregisters proxy's signal handlers and stops receving replies to pending async calls.

Unregistration is done automatically also in proxy's destructor. This method makes sense if, in the process of proxy removal, we need to make sure that callbacks are unregistered explicitly before the final destruction of the proxy instance.

Exceptions
sdbus::Errorin case of failure

◆ unregisterSignalHandler()

virtual void sdbus::IProxy::unregisterSignalHandler ( const std::string &  interfaceName,
const std::string &  signalName 
)
pure virtual

Unregisters the handler of the desired signal.

Parameters
[in]interfaceNameName of an interface that the signal belongs to
[in]signalNameName of the signal
Exceptions
sdbus::Errorin case of failure

◆ uponSignal()

SignalSubscriber sdbus::IProxy::uponSignal ( const std::string &  signalName)
inline

Registers signal handler for a given signal of the proxied D-Bus object.

Parameters
[in]signalNameName of the signal
Returns
A helper object for convenient registration of the signal handler

This is a high-level, convenience way of registering to 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 parameters of the provided native signal callback.

Example of use:

object_.uponSignal("fooSignal").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onFooSignal(arg1, arg2); });
Exceptions
sdbus::Errorin case of failure

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