sdbus-c++ 2.1.0
High-level C++ D-Bus library based on systemd D-Bus implementation
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 attachSdEventLoop (sd_event *event, int priority=0)=0
 Attaches the bus connection to an sd-event event loop.
 
virtual void detachSdEventLoop ()=0
 Detaches the bus connection from an 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 void addMatchAsync (const std::string &match, message_handler callback, message_handler installCallback)=0
 Asynchronously installs a floating match rule for messages received on this bus connection.
 
virtual Slot addMatchAsync (const std::string &match, message_handler callback, message_handler installCallback, return_slot_t)=0
 Asynchronously installs a match rule for messages received on this bus connection.
 
virtual BusName getUniqueName () const =0
 Retrieves the unique name of a connection. E.g. ":1.xx".
 
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]matchMatch expression to filter incoming D-Bus message
[in]callbackCallback 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::Errorin case of failure

◆ addMatch() [2/2]

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

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

Parameters
[in]matchMatch expression to filter incoming D-Bus message
[in]callbackCallback 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::Errorin case of failure

◆ addMatchAsync() [1/2]

virtual void sdbus::IConnection::addMatchAsync ( const std::string & match,
message_handler callback,
message_handler installCallback )
pure virtual

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

Parameters
[in]matchMatch expression to filter incoming D-Bus message
[in]callbackCallback handler to be called upon processing an inbound D-Bus message matching the rule
[in]installCallbackCallback 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::Errorin case of failure

◆ addMatchAsync() [2/2]

virtual Slot sdbus::IConnection::addMatchAsync ( const std::string & match,
message_handler callback,
message_handler installCallback,
return_slot_t  )
nodiscardpure virtual

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

Parameters
[in]matchMatch expression to filter incoming D-Bus message
[in]callbackCallback handler to be called upon processing an inbound D-Bus message matching the rule
[in]installCallbackCallback 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::Errorin 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]objectPathObject 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::Errorin case of failure

◆ addObjectManager() [2/2]

virtual Slot sdbus::IConnection::addObjectManager ( const ObjectPath & objectPath,
return_slot_t  )
nodiscardpure virtual

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

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

◆ attachSdEventLoop()

virtual void sdbus::IConnection::attachSdEventLoop ( sd_event * event,
int priority = 0 )
pure virtual

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

Parameters
[in]eventsd-event event loop object
[in]prioritySpecified priority
Exceptions
sdbus::Errorin case of failure

See ‘man sd_bus_attach_event’.

◆ detachSdEventLoop()

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

Detaches the bus connection from an sd-event event loop.

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.

◆ getCurrentlyProcessedMessage()

virtual Message sdbus::IConnection::getCurrentlyProcessedMessage ( ) const
nodiscardpure 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
nodiscardpure 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 an sd-event event loop, use attachSdEventLoop() function.

Exceptions
sdbus::Errorin case of failure

◆ getMethodCallTimeout()

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

Gets general method call timeout.

Returns
Timeout value in microseconds

Supported by libsystemd>=v240.

Exceptions
sdbus::Errorin 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
nodiscardpure virtual

Retrieves 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

◆ 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 an sd-event event loop through attachSdEventLoop(). It is invoked automatically when necessary.

Exceptions
sdbus::Errorin 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]nameName to release
Exceptions
sdbus::Errorin 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]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: