|
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.
|
|
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.
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
-
virtual Slot sdbus::IConnection::addMatch |
( |
const std::string & | match, |
|
|
message_handler | callback, |
|
|
return_slot_t | ) |
|
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
-
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] | 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
-
virtual Slot sdbus::IConnection::addMatchAsync |
( |
const std::string & | match, |
|
|
message_handler | callback, |
|
|
message_handler | installCallback, |
|
|
return_slot_t | ) |
|
pure virtual |
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
-
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
-
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
-
virtual Message sdbus::IConnection::getCurrentlyProcessedMessage |
( |
| ) |
const |
|
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
virtual PollData sdbus::IConnection::getEventLoopPollData |
( |
| ) |
const |
|
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 an sd-event event loop, use attachSdEventLoop() function.
- Exceptions
-
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
-
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
-