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

`#include <IProxy.h>`

## Public Member Functions

MethodInvoker | callMethod (const MethodName &methodName)
| Calls method on the D-Bus object.
MethodInvoker | callMethod (const std::string &methodName)
| Calls method on the D-Bus object.
MethodInvoker | callMethod (const char *methodName)
| Calls method on the D-Bus object.
AsyncMethodInvoker | callMethodAsync (const MethodName &methodName)
| Calls method on the D-Bus object asynchronously.
AsyncMethodInvoker | callMethodAsync (const std::string &methodName)
| Calls method on the D-Bus object asynchronously.
AsyncMethodInvoker | callMethodAsync (const char *methodName)
| Calls method on the D-Bus object asynchronously.
SignalSubscriber | uponSignal (const SignalName &signalName)
| Registers signal handler for a given signal of the D-Bus object.
SignalSubscriber | uponSignal (const std::string &signalName)
| Registers signal handler for a given signal of the D-Bus object.
SignalSubscriber | uponSignal (const char *signalName)
| Registers signal handler for a given signal of the D-Bus object.
PropertyGetter | getProperty (const PropertyName &propertyName)
| Gets value of a property of the D-Bus object.
PropertyGetter | getProperty (std::string_view propertyName)
| Gets value of a property of the D-Bus object.
AsyncPropertyGetter | getPropertyAsync (const PropertyName &propertyName)
| Gets value of a property of the D-Bus object asynchronously.
AsyncPropertyGetter | getPropertyAsync (std::string_view propertyName)
| Gets value of a property of the D-Bus object asynchronously.
PropertySetter | setProperty (const PropertyName &propertyName)
| Sets value of a property of the D-Bus object.
PropertySetter | setProperty (std::string_view propertyName)
| Sets value of a property of the D-Bus object.
AsyncPropertySetter | setPropertyAsync (const PropertyName &propertyName)
| Sets value of a property of the D-Bus object asynchronously.
AsyncPropertySetter | setPropertyAsync (std::string_view propertyName)
| Sets value of a property of the D-Bus object asynchronously.
AllPropertiesGetter | getAllProperties ()
| Gets values of all properties of the D-Bus object.
AsyncAllPropertiesGetter | getAllPropertiesAsync ()
| Gets values of all properties of the D-Bus object asynchronously.
virtual sdbus::IConnection & | getConnection () const =0
| Provides D-Bus connection used by the proxy.
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 proxy's signal handlers and stops receiving replies to pending async calls.
virtual MethodCall | createMethodCall (const InterfaceName &interfaceName, const MethodName &methodName) const =0
| Creates a method call message.
virtual MethodReply | callMethod (const MethodCall &message)=0
| Calls method on the remote D-Bus object.
virtual MethodReply | callMethod (const MethodCall &message, uint64_t timeout)=0
| Calls method on the remote D-Bus object.
template<typename _Rep, typename _Period>
MethodReply | callMethod (const MethodCall &message, const std::chrono::duration< _Rep, _Period > &timeout)
| Calls method on the remote D-Bus object.
virtual PendingAsyncCall | callMethodAsync (const MethodCall &message, async_reply_handler asyncReplyCallback)=0
| Calls method on the D-Bus object asynchronously.
virtual Slot | callMethodAsync (const MethodCall &message, async_reply_handler asyncReplyCallback, return_slot_t)=0
| Calls method on the D-Bus object asynchronously.
virtual PendingAsyncCall | callMethodAsync (const MethodCall &message, async_reply_handler asyncReplyCallback, uint64_t timeout)=0
| Calls method on the D-Bus object asynchronously, with custom timeout.
virtual Slot | callMethodAsync (const MethodCall &message, async_reply_handler asyncReplyCallback, uint64_t timeout, return_slot_t)=0
| Calls method on the D-Bus object asynchronously, with custom timeout.
template<typename _Rep, typename _Period>
PendingAsyncCall | callMethodAsync (const MethodCall &message, async_reply_handler asyncReplyCallback, const std::chrono::duration< _Rep, _Period > &timeout)
template<typename _Rep, typename _Period>
Slot | callMethodAsync (const MethodCall &message, async_reply_handler asyncReplyCallback, const std::chrono::duration< _Rep, _Period > &timeout, return_slot_t)
virtual std::future< MethodReply > | callMethodAsync (const MethodCall &message, with_future_t)=0
| Calls method on the D-Bus object asynchronously.
virtual std::future< MethodReply > | callMethodAsync (const MethodCall &message, uint64_t timeout, with_future_t)=0
| Calls method on the D-Bus object asynchronously, with custom timeout.
template<typename _Rep, typename _Period>
std::future< MethodReply > | callMethodAsync (const MethodCall &message, const std::chrono::duration< _Rep, _Period > &timeout, with_future_t)
virtual void | registerSignalHandler (const InterfaceName &interfaceName, const SignalName &signalName, signal_handler signalHandler)=0
| Registers a handler for the desired signal emitted by the D-Bus object.
virtual Slot | registerSignalHandler (const InterfaceName &interfaceName, const SignalName &signalName, signal_handler signalHandler, return_slot_t)=0
| Registers a handler for the desired signal emitted by the D-Bus object.

## Protected Member Functions

virtual MethodCall | createMethodCall (const char *interfaceName, const char *methodName) const =0
virtual void | registerSignalHandler (const char *interfaceName, const char *signalName, signal_handler signalHandler)=0
virtual Slot | registerSignalHandler (const char *interfaceName, const char *signalName, signal_handler signalHandler, return_slot_t)=0

## Protected Attributes

friend | MethodInvoker
friend | AsyncMethodInvoker
friend | SignalSubscriber

## 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/6]

MethodInvoker sdbus::IProxy::callMethod | ( | const char * | methodName | ) |

inline nodiscard

Calls method on the D-Bus object.

Parameters

  [in] | methodName | Name 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 = ...;
MethodName multiply{"multiply"};
object_.callMethod(multiply).onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result);

Exceptions

  sdbus::Error | in case of failure

## callMethod() [2/6]

virtual MethodReply sdbus::IProxy::callMethod | ( | const MethodCall & | message | ) |

pure virtual

Calls method on the remote D-Bus object.

Parameters

  [in] | message | Message representing a method call

Returns
  A method reply message

The call does not block if the method call has dont-expect-reply flag set. In that case, the call returns immediately and the return value is an empty, invalid method reply.

The call blocks otherwise, waiting for the remote peer to send back a reply or an error, or until the call times out.

While blocking, other concurrent operations (in other threads) on the underlying bus connection are stalled until the call returns. This is not an issue in vast majority of (simple, single-threaded) applications. In asynchronous, multi-threaded designs involving shared bus connections, this may be an issue. It is advised to instead use an asynchronous callMethod() function overload, which does not block the bus connection, or do the synchronous call from another Proxy instance created just before the call and then destroyed (which is anyway quite a typical approach in D-Bus implementations). Such proxy instance must have its own bus connection. So-called light-weight proxies (ones running without an event loop thread) tag are designed for exactly that purpose.

The default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

Note: To avoid messing with messages, use API on a higher level of abstraction defined below.

Exceptions

  sdbus::Error | in case of failure (also in case the remote function returned an error)

## callMethod() [3/6]

template<typename _Rep, typename _Period>

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

inline

Calls method on the remote D-Bus object.

Parameters

  [in] | message | Message representing a method call
  [in] | timeout | Method call timeout (in microseconds)

Returns
  A method reply message

The call does not block if the method call has dont-expect-reply flag set. In that case, the call returns immediately and the return value is an empty, invalid method reply.

The call blocks otherwise, waiting for the remote peer to send back a reply or an error, or until the call times out.

While blocking, other concurrent operations (in other threads) on the underlying bus connection are stalled until the call returns. This is not an issue in vast majority of (simple, single-threaded) applications. In asynchronous, multi-threaded designs involving shared bus connections, this may be an issue. It is advised to instead use an asynchronous callMethod() function overload, which does not block the bus connection, or do the synchronous call from another Proxy instance created just before the call and then destroyed (which is anyway quite a typical approach in D-Bus implementations). Such proxy instance must have its own bus connection. So-called light-weight proxies (ones running without an event loop thread) tag are designed for exactly that purpose.

If timeout is zero, the default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

Note: To avoid messing with messages, use API on a higher level of abstraction defined below.

Exceptions

  sdbus::Error | in case of failure (also in case the remote function returned an error)

## callMethod() [4/6]

virtual MethodReply sdbus::IProxy::callMethod | ( | const MethodCall & | message,
|  | uint64_t | timeout )

pure virtual

Calls method on the remote D-Bus object.

Parameters

  [in] | message | Message representing a method call
  [in] | timeout | Method call timeout (in microseconds)

Returns
  A method reply message

The call does not block if the method call has dont-expect-reply flag set. In that case, the call returns immediately and the return value is an empty, invalid method reply.

The call blocks otherwise, waiting for the remote peer to send back a reply or an error, or until the call times out.

While blocking, other concurrent operations (in other threads) on the underlying bus connection are stalled until the call returns. This is not an issue in vast majority of (simple, single-threaded) applications. In asynchronous, multi-threaded designs involving shared bus connections, this may be an issue. It is advised to instead use an asynchronous callMethod() function overload, which does not block the bus connection, or do the synchronous call from another Proxy instance created just before the call and then destroyed (which is anyway quite a typical approach in D-Bus implementations). Such proxy instance must have its own bus connection. So-called light-weight proxies (ones running without an event loop thread) tag are designed for exactly that purpose.

If timeout is zero, the default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

Note: To avoid messing with messages, use API on a higher level of abstraction defined below.

Exceptions

  sdbus::Error | in case of failure (also in case the remote function returned an error)

## callMethod() [5/6]

MethodInvoker sdbus::IProxy::callMethod | ( | const MethodName & | methodName | ) |

inline nodiscard

Calls method on the D-Bus object.

Parameters

  [in] | methodName | Name 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 = ...;
MethodName multiply{"multiply"};
object_.callMethod(multiply).onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result);

Exceptions

  sdbus::Error | in case of failure

## callMethod() [6/6]

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

inline nodiscard

Calls method on the D-Bus object.

Parameters

  [in] | methodName | Name 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 = ...;
MethodName multiply{"multiply"};
object_.callMethod(multiply).onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result);

Exceptions

  sdbus::Error | in case of failure

## callMethodAsync() [1/12]

AsyncMethodInvoker sdbus::IProxy::callMethodAsync | ( | const char * | methodName | ) |

inline nodiscard

Calls method on the D-Bus object asynchronously.

Parameters

  [in] | methodName | Name 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 = ...;
MethodName multiply{"multiply"};
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::Error | in case of failure

## callMethodAsync() [2/12]

virtual PendingAsyncCall sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | async_reply_handler | asyncReplyCallback )

pure virtual

Calls method on the D-Bus object asynchronously.

Parameters

  [in] | message | Message representing an async method call
  [in] | asyncReplyCallback | Handler for the async reply

Returns
  Observing handle for the the pending asynchronous call

This is a callback-based way of asynchronously calling a remote D-Bus method.

The call itself 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 bus connection I/O event loop thread.

An non-owning, observing async call handle is returned that can be used to query call status or cancel the call.

The default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

Note: To avoid messing with messages, use API on a higher level of abstraction defined below.

Exceptions

  sdbus::Error | in case of failure

## callMethodAsync() [3/12]

template<typename _Rep, typename _Period>

PendingAsyncCall sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | async_reply_handler | asyncReplyCallback,
|  | const std::chrono::duration< _Rep, _Period > & | timeout )

inline

## callMethodAsync() [4/12]

template<typename _Rep, typename _Period>

Slot sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | async_reply_handler | asyncReplyCallback,
|  | const std::chrono::duration< _Rep, _Period > & | timeout,
|  | return_slot_t | )

inline nodiscard

## callMethodAsync() [5/12]

virtual Slot sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | async_reply_handler | asyncReplyCallback,
|  | return_slot_t | )

nodiscard pure virtual

Calls method on the D-Bus object asynchronously.

Parameters

  [in] | message | Message representing an async method call
  [in] | asyncReplyCallback | Handler for the async reply

Returns
  RAII-style slot handle representing the ownership of the async call

This is a callback-based way of asynchronously calling a remote D-Bus method.

The call itself 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 bus connection I/O event loop thread.

A slot (an owning handle) is returned for the async call. Lifetime of the call is bound to the lifetime of the slot. The slot can be used to cancel the method call at a later time by simply destroying it.

The default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

Note: To avoid messing with messages, use API on a higher level of abstraction defined below.

Exceptions

  sdbus::Error | in case of failure

## callMethodAsync() [6/12]

virtual PendingAsyncCall sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | async_reply_handler | asyncReplyCallback,
|  | uint64_t | timeout )

pure virtual

Calls method on the D-Bus object asynchronously, with custom timeout.

Parameters

  [in] | message | Message representing an async method call
  [in] | asyncReplyCallback | Handler for the async reply
  [in] | timeout | Method call timeout (in microseconds)

Returns
  Observing handle for the the pending asynchronous call

This is a callback-based way of asynchronously calling a remote D-Bus method.

The call itself 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 bus connection I/O event loop thread.

An non-owning, observing async call handle is returned that can be used to query call status or cancel the call.

If timeout is zero, the default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

Note: To avoid messing with messages, use API on a higher level of abstraction defined below.

Exceptions

  sdbus::Error | in case of failure

## callMethodAsync() [7/12]

virtual Slot sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | async_reply_handler | asyncReplyCallback,
|  | uint64_t | timeout,
|  | return_slot_t | )

nodiscard pure virtual

Calls method on the D-Bus object asynchronously, with custom timeout.

Parameters

  [in] | message | Message representing an async method call
  [in] | asyncReplyCallback | Handler for the async reply
  [in] | timeout | Method call timeout (in microseconds)

Returns
  RAII-style slot handle representing the ownership of the async call

This is a callback-based way of asynchronously calling a remote D-Bus method.

The call itself 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 bus connection I/O event loop thread.

A slot (an owning handle) is returned for the async call. Lifetime of the call is bound to the lifetime of the slot. The slot can be used to cancel the method call at a later time by simply destroying it.

If timeout is zero, the default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

Note: To avoid messing with messages, use API on a higher level of abstraction defined below.

Exceptions

  sdbus::Error | in case of failure

## callMethodAsync() [8/12]

template<typename _Rep, typename _Period>

std::future< MethodReply > sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | const std::chrono::duration< _Rep, _Period > & | timeout,
|  | with_future_t | )

inline

## callMethodAsync() [9/12]

virtual std::future< MethodReply > sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | uint64_t | timeout,
|  | with_future_t | )

pure virtual

Calls method on the D-Bus object asynchronously, with custom timeout.

Parameters

  [in] | message | Message representing an async method call
  [in] | timeout | Method call timeout
  [in] | Tag | denoting a std::future-based overload

Returns
  Future object providing access to the future method reply message

This is a std::future-based way of asynchronously calling a remote D-Bus method.

The call itself is non-blocking. It doesn't wait for the reply. Once the reply arrives, the provided future object will be set to contain the reply (or sdbus::Error in case the remote method threw an exception, or the call timed out).

If timeout is zero, the default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

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

Exceptions

  sdbus::Error | in case of failure

## callMethodAsync() [10/12]

virtual std::future< MethodReply > sdbus::IProxy::callMethodAsync | ( | const MethodCall & | message,
|  | with_future_t | )

pure virtual

Calls method on the D-Bus object asynchronously.

Parameters

  [in] | message | Message representing an async method call
  [in] | Tag | denoting a std::future-based overload

Returns
  Future object providing access to the future method reply message

This is a std::future-based way of asynchronously calling a remote D-Bus method.

The call itself is non-blocking. It doesn't wait for the reply. Once the reply arrives, the provided future object will be set to contain the reply (or sdbus::Error in case the remote method threw an exception).

The default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().

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

Exceptions

  sdbus::Error | in case of failure

## callMethodAsync() [11/12]

AsyncMethodInvoker sdbus::IProxy::callMethodAsync | ( | const MethodName & | methodName | ) |

inline nodiscard

Calls method on the D-Bus object asynchronously.

Parameters

  [in] | methodName | Name 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 = ...;
MethodName multiply{"multiply"};
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::Error | in case of failure

## callMethodAsync() [12/12]

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

inline nodiscard

Calls method on the D-Bus object asynchronously.

Parameters

  [in] | methodName | Name 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 = ...;
MethodName multiply{"multiply"};
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::Error | in case of failure

## createMethodCall()

virtual MethodCall sdbus::IProxy::createMethodCall | ( | const InterfaceName & | interfaceName,
|  | const MethodName & | methodName ) const

nodiscard pure virtual

Creates a method call message.

Parameters

  [in] | interfaceName | Name of an interface that provides a given method
  [in] | methodName | Name 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::Error | in case of failure

## getAllProperties()

AllPropertiesGetter sdbus::IProxy::getAllProperties | ( |  | ) |

inline nodiscard

Gets values of all properties of the D-Bus object.

Returns
  A helper object for convenient getting of properties' values

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

Example of use:

auto props = object.getAllProperties().onInterface("com.kistler.foo");

Exceptions

  sdbus::Error | in case of failure

## getAllPropertiesAsync()

AsyncAllPropertiesGetter sdbus::IProxy::getAllPropertiesAsync | ( |  | ) |

inline nodiscard

Gets values of all properties of the D-Bus object asynchronously.

Returns
  A helper object for convenient asynchronous getting of properties' values

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

Example of use:

auto callback = [](std::optional<sdbus::Error> err, const std::map<PropertyName, Variant>>& properties){ ... };
auto props = object.getAllPropertiesAsync().onInterface("com.kistler.foo").uponReplyInvoke(std::move(callback));

Exceptions

  sdbus::Error | in case of failure

## getConnection()

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

nodiscard pure virtual

Provides D-Bus connection used by the proxy.

Returns
  Reference to the D-Bus connection

## getCurrentlyProcessedMessage()

virtual Message sdbus::IProxy::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

## getProperty() [1/2]

PropertyGetter sdbus::IProxy::getProperty | ( | const PropertyName & | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name 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");
sdbus::InterfaceName foo{"com.kistler.foo"};
sdbus::PropertyName level{"level"};
int level = object.getProperty(level).onInterface(foo);
sdbus::InterfaceName
Definition Types.h:238

Exceptions

  sdbus::Error | in case of failure

## getProperty() [2/2]

PropertyGetter sdbus::IProxy::getProperty | ( | std::string_view | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name 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");
sdbus::InterfaceName foo{"com.kistler.foo"};
sdbus::PropertyName level{"level"};
int level = object.getProperty(level).onInterface(foo);

Exceptions

  sdbus::Error | in case of failure

## getPropertyAsync() [1/2]

AsyncPropertyGetter sdbus::IProxy::getPropertyAsync | ( | const PropertyName & | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name of the property

Returns
  A helper object for convenient asynchronous 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.

Example of use:

std::future<sdbus::Variant> state = object.getPropertyAsync("state").onInterface("com.kistler.foo").getResultAsFuture();
auto callback = [](std::optional<sdbus::Error> err, const sdbus::Variant& value){ ... };
object.getPropertyAsync("state").onInterface("com.kistler.foo").uponReplyInvoke(std::move(callback));
sdbus::Variant
Definition Types.h:57

Exceptions

  sdbus::Error | in case of failure

## getPropertyAsync() [2/2]

AsyncPropertyGetter sdbus::IProxy::getPropertyAsync | ( | std::string_view | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name of the property

Returns
  A helper object for convenient asynchronous 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.

Example of use:

std::future<sdbus::Variant> state = object.getPropertyAsync("state").onInterface("com.kistler.foo").getResultAsFuture();
auto callback = [](std::optional<sdbus::Error> err, const sdbus::Variant& value){ ... };
object.getPropertyAsync("state").onInterface("com.kistler.foo").uponReplyInvoke(std::move(callback));

Exceptions

  sdbus::Error | in case of failure

## registerSignalHandler() [1/2]

virtual void sdbus::IProxy::registerSignalHandler | ( | const InterfaceName & | interfaceName,
|  | const SignalName & | signalName,
|  | signal_handler | signalHandler )

pure virtual

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

Parameters

  [in] | interfaceName | Name of an interface that the signal belongs to
  [in] | signalName | Name of the signal
  [in] | signalHandler | Callback that implements the body of the signal handler

A signal can be subscribed to at any time during proxy lifetime. The subscription is active immediately after the call, and stays active for the entire lifetime of the Proxy object.

To be able to unsubscribe from the signal at a later time, use the registerSignalHandler() overload with request_slot tag.

Exceptions

  sdbus::Error | in case of failure

## registerSignalHandler() [2/2]

virtual Slot sdbus::IProxy::registerSignalHandler | ( | const InterfaceName & | interfaceName,
|  | const SignalName & | signalName,
|  | signal_handler | signalHandler,
|  | return_slot_t | )

nodiscard pure virtual

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

Parameters

  [in] | interfaceName | Name of an interface that the signal belongs to
  [in] | signalName | Name of the signal
  [in] | signalHandler | Callback that implements the body of the signal handler

Returns
  RAII-style slot handle representing the ownership of the subscription

A signal can be subscribed to and unsubscribed from at any time during proxy lifetime. The subscription is active immediately after the call. The lifetime of the subscription is bound to the lifetime of the slot object. The subscription is unregistered by letting go of the slot object.

Exceptions

  sdbus::Error | in case of failure

## setProperty() [1/2]

PropertySetter sdbus::IProxy::setProperty | ( | const PropertyName & | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name 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. Setting property value with NoReply flag is also supported.

Example of use:

int state = ...;
object_.setProperty("state").onInterface("com.kistler.foo").toValue(state);
// Or we can just send the set message call without waiting for the reply
object_.setProperty("state").onInterface("com.kistler.foo").toValue(state, dont_expect_reply);

Exceptions

  sdbus::Error | in case of failure

## setProperty() [2/2]

PropertySetter sdbus::IProxy::setProperty | ( | std::string_view | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name 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. Setting property value with NoReply flag is also supported.

Example of use:

int state = ...;
object_.setProperty("state").onInterface("com.kistler.foo").toValue(state);
// Or we can just send the set message call without waiting for the reply
object_.setProperty("state").onInterface("com.kistler.foo").toValue(state, dont_expect_reply);

Exceptions

  sdbus::Error | in case of failure

## setPropertyAsync() [1/2]

AsyncPropertySetter sdbus::IProxy::setPropertyAsync | ( | const PropertyName & | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name of the property

Returns
  A helper object for convenient asynchronous 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 = ...;
// We can wait until the set operation finishes by waiting on the future
std::future<void> res = object_.setPropertyAsync("state").onInterface("com.kistler.foo").toValue(state).getResultAsFuture();

Exceptions

  sdbus::Error | in case of failure

## setPropertyAsync() [2/2]

AsyncPropertySetter sdbus::IProxy::setPropertyAsync | ( | std::string_view | propertyName | ) |

inline nodiscard

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

Parameters

  [in] | propertyName | Name of the property

Returns
  A helper object for convenient asynchronous 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 = ...;
// We can wait until the set operation finishes by waiting on the future
std::future<void> res = object_.setPropertyAsync("state").onInterface("com.kistler.foo").toValue(state).getResultAsFuture();

Exceptions

  sdbus::Error | in case of failure

## unregister()

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

pure virtual

Unregisters proxy's signal handlers and stops receiving 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::Error | in case of failure

## uponSignal() [1/3]

SignalSubscriber sdbus::IProxy::uponSignal | ( | const char * | signalName | ) |

inline nodiscard

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

Parameters

  [in] | signalName | Name 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.

A signal can be subscribed to and unsubscribed from at any time during proxy lifetime. The subscription is active immediately after the call.

Example of use:

object_.uponSignal("stateChanged").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onStateChanged(arg1, arg2); });
sdbus::InterfaceName foo{"com.kistler.foo"};
sdbus::SignalName levelChanged{"levelChanged"};
object_.uponSignal(levelChanged).onInterface(foo).call([this](uint16_t level){ this->onLevelChanged(level); });

Exceptions

  sdbus::Error | in case of failure

## uponSignal() [2/3]

SignalSubscriber sdbus::IProxy::uponSignal | ( | const SignalName & | signalName | ) |

inline nodiscard

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

Parameters

  [in] | signalName | Name 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.

A signal can be subscribed to and unsubscribed from at any time during proxy lifetime. The subscription is active immediately after the call.

Example of use:

object_.uponSignal("stateChanged").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onStateChanged(arg1, arg2); });
sdbus::InterfaceName foo{"com.kistler.foo"};
sdbus::SignalName levelChanged{"levelChanged"};
object_.uponSignal(levelChanged).onInterface(foo).call([this](uint16_t level){ this->onLevelChanged(level); });

Exceptions

  sdbus::Error | in case of failure

## uponSignal() [3/3]

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

inline nodiscard

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

Parameters

  [in] | signalName | Name 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.

A signal can be subscribed to and unsubscribed from at any time during proxy lifetime. The subscription is active immediately after the call.

Example of use:

object_.uponSignal("stateChanged").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onStateChanged(arg1, arg2); });
sdbus::InterfaceName foo{"com.kistler.foo"};
sdbus::SignalName levelChanged{"levelChanged"};
object_.uponSignal(levelChanged).onInterface(foo).call([this](uint16_t level){ this->onLevelChanged(level); });

Exceptions

  sdbus::Error | in case of failure

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

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