sdbus-c++: sdbus::IConnection Class Reference

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

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

`#include <IConnection.h>`

## Classes
struct | PollData

## Public Member Functions
virtual void | requestName (const std::string &name)=0
| Requests D-Bus name on the connection.
virtual void | releaseName (const std::string &name)=0
| Releases D-Bus name on the connection.
virtual std::string | getUniqueName () const =0
| Retrieve the unique name of a connection. E.g. ":1.xx".
virtual void | enterEventLoop ()=0
| Enters I/O event loop on this bus connection.
virtual void | enterEventLoopAsync ()=0
| Enters I/O event loop on this bus connection in a separate thread.
virtual void | leaveEventLoop ()=0
| Leaves the I/O event loop running on this bus connection.
virtual void | addObjectManager (const std::string &objectPath)=0
| Adds an ObjectManager at the specified D-Bus object path.
virtual PollData | getEventLoopPollData () const =0
| Returns fd, I/O events and timeout data you can pass to poll.
virtual bool | processPendingRequest ()=0
| Process a pending request.
virtual void | setMethodCallTimeout (uint64_t timeout)=0
| Sets general method call timeout.
template<typename _Rep , typename _Period >
void | setMethodCallTimeout (const std::chrono::duration< _Rep, _Period > &timeout)
| Sets general method call timeout.
virtual uint64_t | getMethodCallTimeout () const =0
| Gets general method call timeout.
virtual void | addObjectManager (const std::string &objectPath, floating_slot_t)=0
| Adds an ObjectManager at the specified D-Bus object path.
virtual Slot | addMatch (const std::string &match, message_handler callback)=0
| Adds a match rule for incoming message dispatching.
virtual void | addMatch (const std::string &match, message_handler callback, floating_slot_t)=0
| Adds a floating match rule for incoming message dispatching.
void | enterProcessingLoop ()
| Enters I/O event loop on this bus connection.
void | enterProcessingLoopAsync ()
| Enters I/O event loop on this bus connection in a separate thread.
void | leaveProcessingLoop ()
| Leaves the I/O event loop running on this bus connection.
PollData | getProcessLoopPollData () const
| Returns fd, I/O events and timeout data you can pass to poll.

## Detailed Description

An interface to D-Bus bus connection. Incorporates implementation of both synchronous and asynchronous D-Bus I/O event loop.

All methods throw sdbus::Error in case of failure. All methods in this class are thread-aware, but not thread-safe.

## Member Function Documentation

## ◆ addMatch() [1/2]

virtual Slot sdbus::IConnection::addMatch | ( | const std::string & | match,
|  | message_handler | callback )
| pure virtual

Adds a match rule for incoming message dispatching.

Parameters

  [in] | match | Match expression to filter incoming D-Bus message
  [in] | callback | Callback handler to be called upon incoming D-Bus message matching the rule

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

The method installs a match rule for messages received on the specified bus connection. The syntax of the match rule expression passed in match is described in the D-Bus specification. The specified handler function callback is called for each incoming message matching the specified expression. The match is installed synchronously when connected to a bus broker, i.e. the call sends a control message requested the match to be added to the broker and waits until the broker confirms the match has been installed successfully.

Simply let go of the slot instance to uninstall the match rule from the bus connection. The slot must not outlive the connection for the slot is associated with it.

For more information, consult `man sd_bus_add_match`.

Exceptions

  sdbus::Error | in case of failure

## ◆ addMatch() [2/2]

virtual void sdbus::IConnection::addMatch | ( | const std::string & | match,
|  | message_handler | callback,
|  | floating_slot_t | )
| pure virtual

Adds a floating match rule for incoming message dispatching.

Parameters

  [in] | match | Match expression to filter incoming D-Bus message
  [in] | callback | Callback handler to be called upon incoming D-Bus message matching the rule

The method installs a floating match rule for messages received on the specified bus connection. Floating means that the bus connection object owns the match rule, i.e. lifetime of the match rule is bound to the lifetime of the bus connection.

Refer to the `addMatch(const std::string& match, message_handler callback)` documentation for more information.

Exceptions

  sdbus::Error | in case of failure

## ◆ addObjectManager() [1/2]

virtual void sdbus::IConnection::addObjectManager | ( | const std::string & | objectPath | ) |
| pure virtual

Adds an ObjectManager at the specified D-Bus object path.

Creates an ObjectManager interface at the specified object path on the connection. This is a convenient way to interrogate a connection to see what objects it has.

This call creates a floating registration. The ObjectManager will be there for the object path until the connection is destroyed.

Another, recommended way to add object managers is directly through IObject API.

Exceptions

  sdbus::Error | in case of failure

## ◆ addObjectManager() [2/2]

virtual void sdbus::IConnection::addObjectManager | ( | const std::string & | objectPath,
|  | floating_slot_t | )
| pure virtual

Adds an ObjectManager at the specified D-Bus object path.

Creates an ObjectManager interface at the specified object path on the connection. This is a convenient way to interrogate a connection to see what objects it has.

This call creates a floating registration. The ObjectManager will be there for the object path until the connection is destroyed.

Another, recommended way to add object managers is directly through IObject API.

Exceptions

  sdbus::Error | in case of failure

## ◆ enterEventLoop()

virtual void sdbus::IConnection::enterEventLoop | ( |  | ) |
| pure virtual

Enters I/O event loop on this bus connection.

The incoming D-Bus messages are processed in the loop. The method blocks indefinitely, until unblocked through leaveEventLoop().

Exceptions

  sdbus::Error | in case of failure

## ◆ enterEventLoopAsync()

virtual void sdbus::IConnection::enterEventLoopAsync | ( |  | ) |
| pure virtual

Enters I/O event loop on this bus connection in a separate thread.

The same as enterEventLoop, except that it doesn't block because it runs the loop in a separate, internally managed thread.

## ◆ enterProcessingLoop()

void sdbus::IConnection::enterProcessingLoop | ( |  | ) |
| inline

Enters I/O event loop on this bus connection.

The incoming D-Bus messages are processed in the loop. The method blocks indefinitely, until unblocked through leaveEventLoop().

Exceptions

  sdbus::Error | in case of failure

Deprecated
  This function has been replaced by enterEventLoop()

## ◆ enterProcessingLoopAsync()

void sdbus::IConnection::enterProcessingLoopAsync | ( |  | ) |
| inline

Enters I/O event loop on this bus connection in a separate thread.

The same as enterEventLoop, except that it doesn't block because it runs the loop in a separate, internally managed thread.

Deprecated
  This function has been replaced by enterEventLoopAsync()

## ◆ getEventLoopPollData()

virtual PollData sdbus::IConnection::getEventLoopPollData | ( |  | ) | const
| pure virtual

Returns fd, I/O events and timeout data you can pass to poll.

To integrate sdbus with your app's own custom event handling system (without the requirement of an extra thread), you can use this method to query which file descriptors, poll events and timeouts you should add to your app's poll call in your main event loop. If these file descriptors signal, then you should call processPendingRequest to process the event. This means that all of sdbus's callbacks will arrive on your app's main event thread (opposed to on a thread created by sdbus-c++). If you are unsure what this all means then use enterEventLoop() or enterEventLoopAsync() instead.

To integrate sdbus-c++ into a gtk app, pass the file descriptor returned by this method to g_main_context_add_poll.

Exceptions

  sdbus::Error | in case of failure

## ◆ getMethodCallTimeout()

virtual uint64_t sdbus::IConnection::getMethodCallTimeout | ( |  | ) | const
| pure virtual

Gets general method call timeout.

Returns
  Timeout value in microseconds

Supported by libsystemd>=v240.

Exceptions

  sdbus::Error | in case of failure

## ◆ getProcessLoopPollData()

IConnection::PollData sdbus::IConnection::getProcessLoopPollData | ( |  | ) | const
| inline

Returns fd, I/O events and timeout data you can pass to poll.

To integrate sdbus with your app's own custom event handling system (without the requirement of an extra thread), you can use this method to query which file descriptors, poll events and timeouts you should add to your app's poll call in your main event loop. If these file descriptors signal, then you should call processPendingRequest to process the event. This means that all of sdbus's callbacks will arrive on your app's main event thread (opposed to on a thread created by sdbus-c++). If you are unsure what this all means then use enterEventLoop() or enterEventLoopAsync() instead.

To integrate sdbus-c++ into a gtk app, pass the file descriptor returned by this method to g_main_context_add_poll.

Exceptions

  sdbus::Error | in case of failure

Deprecated
  This function has been replaced by getEventLoopPollData()

## ◆ getUniqueName()

virtual std::string sdbus::IConnection::getUniqueName | ( |  | ) | const
| pure virtual

Retrieve the unique name of a connection. E.g. ":1.xx".

Exceptions

  sdbus::Error | in case of failure

## ◆ leaveEventLoop()

virtual void sdbus::IConnection::leaveEventLoop | ( |  | ) |
| pure virtual

Leaves the I/O event loop running on this bus connection.

This causes the loop to exit and frees the thread serving the loop

Exceptions

  sdbus::Error | in case of failure

## ◆ leaveProcessingLoop()

void sdbus::IConnection::leaveProcessingLoop | ( |  | ) |
| inline

Leaves the I/O event loop running on this bus connection.

This causes the loop to exit and frees the thread serving the loop

Exceptions

  sdbus::Error | in case of failure

Deprecated
  This function has been replaced by leaveEventLoop()

## ◆ processPendingRequest()

virtual bool sdbus::IConnection::processPendingRequest | ( |  | ) |
| pure virtual

Process a pending request.

Returns
  true if an event was processed, false if poll should be called

Processes a single dbus event. All of sdbus-c++'s callbacks will be called from within this method. This method should ONLY be used in conjuction with getEventLoopPollData(). This method returns true if an I/O message was processed. This you can try to call this method again before going to poll on I/O events. The method returns false if no operations were pending, and the caller should then poll for I/O events before calling this method again. enterEventLoop() and enterEventLoopAsync() will call this method for you, so there is no need to call it when using these. If you are unsure what this all means then don't use this method.

Exceptions

  sdbus::Error | in case of failure

## ◆ releaseName()

virtual void sdbus::IConnection::releaseName | ( | const std::string & | name | ) |
| pure virtual

Releases D-Bus name on the connection.

Parameters

  [in] | name | Name to release

Exceptions

  sdbus::Error | in case of failure

## ◆ requestName()

virtual void sdbus::IConnection::requestName | ( | const std::string & | name | ) |
| pure virtual

Requests D-Bus name on the connection.

Parameters

  [in] | name | Name to request

Exceptions

  sdbus::Error | in case of failure

## ◆ setMethodCallTimeout() [1/2]

template<typename _Rep , typename _Period >

void sdbus::IConnection::setMethodCallTimeout | ( | const std::chrono::duration< _Rep, _Period > & | timeout | ) |
| inline

Sets general method call timeout.

Parameters

  [in] | timeout | Timeout value in microseconds

General method call timeout is used for all method calls upon this connection. Method call-specific timeout overrides this general setting.

Supported by libsystemd>=v240.

Exceptions

  sdbus::Error | in case of failure

## ◆ setMethodCallTimeout() [2/2]

virtual void sdbus::IConnection::setMethodCallTimeout | ( | uint64_t | timeout | ) |
| pure virtual

Sets general method call timeout.

Parameters

  [in] | timeout | Timeout value in microseconds

General method call timeout is used for all method calls upon this connection. Method call-specific timeout overrides this general setting.

Supported by libsystemd>=v240.

Exceptions

  sdbus::Error | in case of failure

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

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