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

`#include <IConnection.h>`

## Classes

struct | PollData

## Public Member Functions

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 | detachSdEventLoop ()=0
| Attaches the bus connection to a sd-event event loop.
virtual sd_event * | getSdEventLoop ()=0
| Gets current sd-event event loop for the bus connection.
virtual PollData | getEventLoopPollData () const =0
| Returns fd's, I/O events and timeout data to be used in an external event loop.
virtual bool | processPendingEvent ()=0
| Processes a pending event.
virtual Message | getCurrentlyProcessedMessage () const =0
| Provides access to the currently processed D-Bus message.
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 ObjectPath &objectPath)=0
| Adds an ObjectManager at the specified D-Bus object path.
virtual Slot | addObjectManager (const ObjectPath &objectPath, return_slot_t)=0
| Adds an ObjectManager at the specified D-Bus object path.
virtual void | addMatch (const std::string &match, message_handler callback)=0
| Installs a floating match rule for messages received on this bus connection.
virtual Slot | addMatch (const std::string &match, message_handler callback, return_slot_t)=0
| Installs a match rule for messages received on this bus connection.
virtual BusName | getUniqueName () const =0
| Asynchronously installs a floating match rule for messages received on this bus connection.
virtual void | requestName (const ServiceName &name)=0
| Requests a well-known D-Bus service name on a bus.
virtual void | releaseName (const ServiceName &name)=0
| Releases an acquired well-known D-Bus service name on a bus.

## 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 void sdbus::IConnection::addMatch | ( | const std::string & | match,
|  | message_handler | callback )

pure virtual

Installs a floating match rule for messages received on this bus connection.

Parameters

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

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 requesting the match to be added to the broker and waits until the broker confirms the match has been installed successfully.

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.

For more information, consult man sd_bus_add_match.

Exceptions

  sdbus::Error | in case of failure

## addMatch() [2/2]

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

nodiscard pure virtual

Installs a match rule for messages received on this bus connection.

Parameters

  [in] | match | Match expression to filter incoming D-Bus message
  [in] | callback | Callback handler to be called upon processing an inbound 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 requesting the match to be added to the broker and waits until the broker confirms the match has been installed successfully.

The lifetime of the match rule is bound to the lifetime of the returned slot instance. Destroying the slot instance implies uninstalling of the match rule from the bus connection.

For more information, consult man sd_bus_add_match.

Exceptions

  sdbus::Error | in case of failure

## addObjectManager() [1/2]

virtual void sdbus::IConnection::addObjectManager | ( | const ObjectPath & | objectPath | ) |

pure virtual

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

Parameters

  [in] | objectPath | Object path at which the ObjectManager interface shall be installed

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 Slot sdbus::IConnection::addObjectManager | ( | const ObjectPath & | objectPath,
|  | return_slot_t | )

nodiscard pure virtual

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

Parameters

  [in] | objectPath | Object path at which the ObjectManager interface shall be installed

Returns
  Slot handle owning the registration

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 returns an owning slot. The lifetime of the ObjectManager interface is bound to the lifetime of the returned slot instance.

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

Exceptions

  sdbus::Error | in case of failure

## detachSdEventLoop()

virtual void sdbus::IConnection::detachSdEventLoop | ( |  | ) |

pure virtual

Attaches the bus connection to a sd-event event loop.

Parameters

  [in] | event | sd-event event loop object
  [in] | priority | Specified priority

Exceptions

  sdbus::Error | in case of failure

See `man sd_bus_attach_event'. */ virtual void attachSdEventLoop(sd_event *event, int priority = 0) = 0;

/*!

Detaches the bus connection from a sd-event event loop

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.

## getCurrentlyProcessedMessage()

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

## getEventLoopPollData()

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

nodiscard pure virtual

Returns fd's, I/O events and timeout data to be used in an external event loop.

This function is useful to hook up a bus connection object with an external (like GMainLoop, boost::asio, etc.) or manual event loop involving poll() or a similar I/O polling call.

Before each invocation of the I/O polling call, this function should be invoked. Returned PollData::fd file descriptor should be polled for the events indicated by PollData::events, and the I/O call should block for that up to the returned PollData::timeout.

Additionally, returned PollData::eventFd should be polled for POLLIN events.

After each I/O polling call the bus connection needs to process incoming or outgoing data, by invoking processPendingEvent().

Note that the returned timeout should be considered only a maximum sleeping time. It is permissible (and even expected) that shorter timeouts are used by the calling program, in case other event sources are polled in the same event loop. Note that the returned time-value is absolute, based of CLOCK_MONOTONIC and specified in microseconds. Use PollData::getPollTimeout() to have the timeout value converted in a form that can be passed to poll(2).

The bus connection conveniently integrates sd-event event loop. To attach the bus connection to a sd-event event loop, use attachSdEventLoop() function.

Exceptions

  sdbus::Error | in case of failure

## getMethodCallTimeout()

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

nodiscard pure virtual

Gets general method call timeout.

Returns
  Timeout value in microseconds

Supported by libsystemd>=v240.

Exceptions

  sdbus::Error | in case of failure

## getSdEventLoop()

virtual sd_event * sdbus::IConnection::getSdEventLoop | ( |  | ) |

pure virtual

Gets current sd-event event loop for the bus connection.

Returns
  Pointer to event loop object if attached, nullptr otherwise

## getUniqueName()

virtual BusName sdbus::IConnection::getUniqueName | ( |  | ) | const

nodiscard pure virtual

Asynchronously installs a floating match rule for messages received on this bus connection.

Parameters

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

This method operates the same as addMatch() above, just that it installs the match rule asynchronously, in a non-blocking fashion. A request is sent to the broker, but the call does not wait for a response. The `installCallback' callable is called when the response is later received, with the response message from the broker as parameter. If it's an empty function object, a default implementation is used that terminates the bus connection should installing the match fail.

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.

For more information, consult man sd_bus_add_match_async.

Exceptions

  sdbus::Error | in case of failure */ virtual void addMatchAsync(const std::string& match, message_handler callback, message_handler installCallback) = 0;

/*!

Asynchronously installs a match rule for messages received on this bus connection

Parameters

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

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

This method operates the same as addMatch() above, just that it installs the match rule asynchronously, in a non-blocking fashion. A request is sent to the broker, but the call does not wait for a response. The `installCallback' callable is called when the response is later received, with the response message from the broker as parameter. If it's an empty function object, a default implementation is used that terminates the bus connection should installing the match fail.

The lifetime of the match rule is bound to the lifetime of the returned slot instance. Destroying the slot instance implies the uninstalling of the match rule from the bus connection.

For more information, consult man sd_bus_add_match_async.

Exceptions

  sdbus::Error | in case of failure */ [[nodiscard]] virtual Slot addMatchAsync( const std::string& match , message_handler callback , message_handler installCallback , return_slot_t ) = 0;

/*!

Retrieves 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

## processPendingEvent()

virtual bool sdbus::IConnection::processPendingEvent | ( |  | ) |

pure virtual

Processes a pending event.

Returns
  True if an event was processed, false if no operations were pending

This function drives the D-Bus connection. It processes pending I/O events. Queued outgoing messages (or parts thereof) are sent out. Queued incoming messages are dispatched to registered callbacks. Timeouts are recalculated.

It returns false when no operations were pending and true if a message was processed. When false is returned the caller should synchronously poll for I/O events before calling into processPendingEvent() again. Don't forget to call getEventLoopPollData() each time before the next poll.

You don't need to directly call this method or getEventLoopPollData() method when using convenient, internal bus connection event loops through enterEventLoop() or enterEventLoopAsync() calls, or when the bus is connected to a sd-event event loop through attachSdEventLoop(). It is invoked automatically when necessary.

Exceptions

  sdbus::Error | in case of failure

## releaseName()

virtual void sdbus::IConnection::releaseName | ( | const ServiceName & | name | ) |

pure virtual

Releases an acquired well-known D-Bus service name on a bus.

Parameters

  [in] | name | Name to release

Exceptions

  sdbus::Error | in case of failure

## requestName()

virtual void sdbus::IConnection::requestName | ( | const ServiceName & | name | ) |

pure virtual

Requests a well-known D-Bus service name on a bus.

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