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

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]matchMatch expression to filter incoming D-Bus message
[in]callbackCallback 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::Errorin 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]matchMatch expression to filter incoming D-Bus message
[in]callbackCallback handler to be called upon incoming D-Bus message matching the rule
[in]Floatingslot tag

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::Errorin 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::Errorin 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::Errorin 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::Errorin 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::Errorin case of failure
Deprecated:
This function has been replaced by enterEventLoop()

◆ enterProcessingLoopAsync()

void sdbus::IConnection::enterProcessingLoopAsync ( )
inline

Deprecated:
This function has been replaced by enterEventLoopAsync()
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::Errorin 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::Errorin case of failure

◆ getProcessLoopPollData()

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

Deprecated:
This function has been replaced by getEventLoopPollData()
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::Errorin 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::Errorin case of failure

◆ leaveProcessingLoop()

void sdbus::IConnection::leaveProcessingLoop ( )
inline

Deprecated:
This function has been replaced by leaveEventLoop()
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::Errorin case of failure

◆ releaseName()

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

Releases D-Bus name on the connection.

Parameters
[in]nameName to release
Exceptions
sdbus::Errorin case of failure

◆ requestName()

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

Requests D-Bus name on the connection.

Parameters
[in]nameName to request
Exceptions
sdbus::Errorin 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]timeoutTimeout 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::Errorin case of failure

◆ setMethodCallTimeout() [2/2]

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

Sets general method call timeout.

Parameters
[in]timeoutTimeout 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::Errorin case of failure

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