DBus::Connection Class Reference

Connection point to the DBus. More...

#include <connection.h>

Inherits std::enable_shared_from_this< Connection >.

Public Member Functions

 ~Connection ()
 
 operator bool () const
 True if this is a valid connection; false otherwise. More...
 
bool is_valid () const
 True if this is a valid connection; false otherwise. More...
 
bool is_registered () const
 True if this connection is already registered. More...
 
bool bus_register ()
 Registers this connection with the bus. More...
 
std::string unique_name () const
 Gets the unique name of the connection as assigned by the message bus. More...
 
RequestNameResponse request_name (const std::string &name, unsigned int flags=0)
 Request the given name on the bus. More...
 
ReleaseNameResponse release_name (const std::string &name)
 Release the specified name, after requesting it via request_name. More...
 
bool name_has_owner (const std::string &name) const
 Check to see if the given name currently has an owner. More...
 
StartReply start_service (const std::string &name, uint32_t flags=0) const
 start_service More...
 
bool add_match (const std::string &rule)
 
void add_match_nonblocking (const std::string &rule)
 
bool remove_match (const std::string &rule)
 
bool is_connected () const
 
bool is_authenticated () const
 
bool is_anonymous () const
 
const char * server_id () const
 
uint32_t send (const std::shared_ptr< const Message > message)
 Queues up the message to be sent on the bus. More...
 
Connectionoperator<< (std::shared_ptr< const Message > msg)
 Blindly sends the message on the connection. More...
 
std::shared_ptr< ReturnMessagesend_with_reply_blocking (std::shared_ptr< const CallMessage > msg, int timeout_milliseconds=-1)
 Send a CallMessage, and wait for the reply. More...
 
void flush ()
 Flushes all data out to the bus. More...
 
DispatchStatus dispatch_status () const
 
DispatchStatus dispatch ()
 Dispatch the connection. More...
 
int unix_fd () const
 
int socket () const
 
bool has_messages_to_send ()
 
sigc::signal< void()> & signal_needs_dispatch ()
 This signal is emitted whenever we need to be dispatched. More...
 
std::shared_ptr< Objectcreate_object (const std::string &path, ThreadForCalling calling=ThreadForCalling::DispatcherThread)
 Create and return a new object, registering the object automatically. More...
 
RegistrationStatus register_object (std::shared_ptr< Object > object, ThreadForCalling calling=ThreadForCalling::DispatcherThread)
 Register an object with this connection. More...
 
bool change_object_calling_thread (std::shared_ptr< Object > object, ThreadForCalling calling)
 Change the thread that the methods on this object will be called from. More...
 
bool change_object_proxy_calling_thread (std::shared_ptr< ObjectProxy > object, ThreadForCalling calling)
 Change the thread that the signals on this ObjectProxy will be called from. More...
 
std::shared_ptr< ObjectProxycreate_object_proxy (const std::string &path, ThreadForCalling calling=ThreadForCalling::DispatcherThread)
 
std::shared_ptr< ObjectProxycreate_object_proxy (const std::string &destination, const std::string &path, ThreadForCalling calling=ThreadForCalling::DispatcherThread)
 
bool register_object_proxy (std::shared_ptr< ObjectProxy > obj, ThreadForCalling calling=ThreadForCalling::DispatcherThread)
 Add an ObjectProxy to this Connection. More...
 
bool unregister_object (const std::string &path)
 
template<typename... T_arg>
std::shared_ptr< SignalProxy< T_arg... > > create_free_signal_proxy (const SignalMatchRule &rule, ThreadForCalling calling=ThreadForCalling::DispatcherThread)
 Create and return a signal proxy that lets you listen to signals sent on the DBus as a free proxy. More...
 
std::shared_ptr< SignalProxyBaseadd_free_signal_proxy (std::shared_ptr< SignalProxyBase > Signal, ThreadForCalling calling=ThreadForCalling::DispatcherThread)
 Adds the given signal proxy to the connection. More...
 
bool remove_free_signal_proxy (std::shared_ptr< SignalProxyBase > proxy)
 Remove a free signal proxy, so that it will not be called anymore. More...
 
const std::vector< std::shared_ptr< SignalProxyBase > > get_free_signal_proxies ()
 Gets all the free signal handlers. More...
 
std::vector< std::shared_ptr< SignalProxyBase > > get_free_signal_proxies (const std::string &interface_name)
 Gets the signal handlers for a specific interface. More...
 
std::vector< std::shared_ptr< SignalProxyBase > > get_free_signal_proxies (const std::string &interface_name, const std::string &member)
 Gets the signal handlers for a specific interface and member. More...
 
template<class T_arg >
std::shared_ptr< Signal< T_arg > > create_free_signal (const std::string &path, const std::string &interface_name, const std::string &member)
 Create a free signal, that when it is emitted will send that signal over the DBus. More...
 
std::string introspect (const std::string &destination, const std::string &path)
 
void set_dispatching_thread (std::thread::id tid)
 Set the ID of the thread that all of the dispatching hapens from. More...
 
void add_thread_dispatcher (std::weak_ptr< ThreadDispatcher > disp)
 Add a thread dispatcher that will handle messages for a given thread. More...
 

Static Public Member Functions

static std::shared_ptr< Connectioncreate (BusType type)
 Connects to a bus daemon. More...
 
static std::shared_ptr< Connectioncreate (std::string address)
 Create a new connection, connecting to the specified address. More...
 

Private Member Functions

 Connection (BusType type)
 
 Connection (std::string address)
 
void notify_dispatcher_or_dispatch ()
 Depending on what thread this is called from, will either notify the dispatcher that we need to be dispatched, or will do the dispatching needed. More...
 
uint32_t write_single_message (std::shared_ptr< const Message > msg)
 Write a single message, return the serial of this message. More...
 
void process_single_message ()
 
void remove_invalid_threaddispatchers_and_associated_objects ()
 
void send_error_on_handler_result (std::shared_ptr< const CallMessage > msg, HandlerResult result)
 Send an error back to the calling application based on HandlerResult. More...
 
void process_call_message (std::shared_ptr< const CallMessage > msg)
 
void process_signal_message (std::shared_ptr< const SignalMessage > msg)
 
std::thread::id thread_id_from_calling (ThreadForCalling calling)
 
 DBUS_CXX_PROPAGATE_CONST (std::unique_ptr< priv_data >) m_priv
 

Detailed Description

Constructor & Destructor Documentation

◆ Connection() [1/2]

◆ Connection() [2/2]

DBus::Connection::Connection ( std::string  address)
private

◆ ~Connection()

DBus::Connection::~Connection ( )

Member Function Documentation

◆ add_free_signal_proxy()

std::shared_ptr< SignalProxyBase > DBus::Connection::add_free_signal_proxy ( std::shared_ptr< SignalProxyBase Signal,
ThreadForCalling  calling = ThreadForCalling::DispatcherThread 
)

Adds the given signal proxy to the connection.

References add_match(), LOGGER_NAME, SIMPLELOGGER_DEBUG, SIMPLELOGGER_ERROR, and thread_id_from_calling().

Referenced by create_free_signal_proxy().

◆ add_match()

bool DBus::Connection::add_match ( const std::string &  rule)

◆ add_match_nonblocking()

void DBus::Connection::add_match_nonblocking ( const std::string &  rule)

◆ add_thread_dispatcher()

void DBus::Connection::add_thread_dispatcher ( std::weak_ptr< ThreadDispatcher disp)

Add a thread dispatcher that will handle messages for a given thread.

This method must be called from the thread that this ThreadDispatcher is handling messages for.

This is a weak_ptr, as the intention is to simply declare a local ThreadDispatcher object inside of the thread. When the thread exits, the ThreadDispatcher will be deconstructed. The next time a message for this thread comes in, anything that is associated with this thread will become unexported.

Parameters
dispThe thread dispatcher to associate with this connection.

◆ bus_register()

bool DBus::Connection::bus_register ( )

Registers this connection with the bus.

It is safe to call this method multiple times.

References DBus::DBusDaemonProxy::create(), and is_registered().

◆ change_object_calling_thread()

bool DBus::Connection::change_object_calling_thread ( std::shared_ptr< Object object,
ThreadForCalling  calling 
)

Change the thread that the methods on this object will be called from.

Note that this object must already be registered with register_object.

Parameters
object
calling
Returns

References DBus::DispatcherThread.

◆ change_object_proxy_calling_thread()

bool DBus::Connection::change_object_proxy_calling_thread ( std::shared_ptr< ObjectProxy object,
ThreadForCalling  calling 
)

Change the thread that the signals on this ObjectProxy will be called from.

Note that this ObjectProxy must be related to this connection

Parameters
objectThe ObjectProxy that has the signals to listen for
calling
Returns

References DBus::CurrentThread.

◆ create() [1/2]

std::shared_ptr< Connection > DBus::Connection::create ( BusType  type)
static

Connects to a bus daemon.

The returned Connection will have authenticated with the bus at this point, but it will not be registered. bus_register() must be called - the Dispatcher should do this automatically.

Parameters
is_privateif true a private connection will be created. Otherwise a shared connection is created.

References Connection(), and DBus::type().

Referenced by DBus::StandaloneDispatcher::create_connection().

◆ create() [2/2]

std::shared_ptr< Connection > DBus::Connection::create ( std::string  address)
static

Create a new connection, connecting to the specified address.

This address needs to be in the in DBus transport format (e.g. unix:path=/tmp/dbus-test). The returned connection will have authenticated with the bus at this point, but it will not be registered. bus_register() must be called - the Dispatcher should do this automatically.

Parameters
address
Returns

References Connection().

◆ create_free_signal()

template<class T_arg >
std::shared_ptr<Signal<T_arg> > DBus::Connection::create_free_signal ( const std::string &  path,
const std::string &  interface_name,
const std::string &  member 
)
inline

Create a free signal, that when it is emitted will send that signal over the DBus.

A free signal is a signal that is not associated with an Object.

◆ create_free_signal_proxy()

template<typename... T_arg>
std::shared_ptr<SignalProxy<T_arg...> > DBus::Connection::create_free_signal_proxy ( const SignalMatchRule rule,
ThreadForCalling  calling = ThreadForCalling::DispatcherThread 
)
inline

Create and return a signal proxy that lets you listen to signals sent on the DBus as a free proxy.

A free proxy is one that is not attached to an interface.

Normally, you want to add signal proxies via Interface::add_signal.

This method may be used when you need more control over the match rule for the signal that you want to listen to.

This method automatically calls add_signal_proxy.

References add_free_signal_proxy().

◆ create_object()

std::shared_ptr< Object > DBus::Connection::create_object ( const std::string &  path,
ThreadForCalling  calling = ThreadForCalling::DispatcherThread 
)

Create and return a new object, registering the object automatically.

If the registering fails, an invalid pointer will be returned.

Parameters
pathThe path of a new object, e.g. /opt/freedesktop/DBus
callingHow to call this object(what thread). Defaults to being the dispatching thread.
Returns
An invalid shared_ptr if registration was not successful, else a valid shared_ptr

References DBus::Object::create(), register_object(), and DBus::Success.

◆ create_object_proxy() [1/2]

std::shared_ptr< ObjectProxy > DBus::Connection::create_object_proxy ( const std::string &  destination,
const std::string &  path,
ThreadForCalling  calling = ThreadForCalling::DispatcherThread 
)

◆ create_object_proxy() [2/2]

std::shared_ptr< ObjectProxy > DBus::Connection::create_object_proxy ( const std::string &  path,
ThreadForCalling  calling = ThreadForCalling::DispatcherThread 
)

◆ DBUS_CXX_PROPAGATE_CONST()

DBus::Connection::DBUS_CXX_PROPAGATE_CONST ( std::unique_ptr< priv_data >  )
private

◆ dispatch()

DispatchStatus DBus::Connection::dispatch ( )

Dispatch the connection.

Dispatching involves writing messages to the bus, reading messages from the bus, and acting on those messages, if available. This method can only be called from the dispatching thread, and will throw an exception if it is called from the wrong thread.

This method, when called, will process at most one message. This is required so that responses to method calls will appear to be fully blocking.

Returns
The status of dispatching. This method should be called util the status is DispatchStatus::COMPLETE

References DBus::COMPLETE, DBus::DATA_REMAINS, flush(), is_valid(), LOGGER_NAME, process_single_message(), and SIMPLELOGGER_DEBUG.

Referenced by notify_dispatcher_or_dispatch().

◆ dispatch_status()

DispatchStatus DBus::Connection::dispatch_status ( ) const

References DBus::COMPLETE, and is_valid().

◆ flush()

void DBus::Connection::flush ( )

Flushes all data out to the bus.

This should generally be called from the dispatching thread, but it should be able to be called from any thread.

References is_valid().

Referenced by dispatch().

◆ get_free_signal_proxies() [1/3]

const std::vector< std::shared_ptr< SignalProxyBase > > DBus::Connection::get_free_signal_proxies ( )

Gets all the free signal handlers.

Referenced by get_free_signal_proxies().

◆ get_free_signal_proxies() [2/3]

std::vector< std::shared_ptr< SignalProxyBase > > DBus::Connection::get_free_signal_proxies ( const std::string &  interface_name)

Gets the signal handlers for a specific interface.

References get_free_signal_proxies().

◆ get_free_signal_proxies() [3/3]

std::vector< std::shared_ptr< SignalProxyBase > > DBus::Connection::get_free_signal_proxies ( const std::string &  interface_name,
const std::string &  member 
)

Gets the signal handlers for a specific interface and member.

References get_free_signal_proxies().

◆ has_messages_to_send()

bool DBus::Connection::has_messages_to_send ( )

References is_valid().

◆ introspect()

std::string DBus::Connection::introspect ( const std::string &  destination,
const std::string &  path 
)

◆ is_anonymous()

bool DBus::Connection::is_anonymous ( ) const

◆ is_authenticated()

bool DBus::Connection::is_authenticated ( ) const

◆ is_connected()

bool DBus::Connection::is_connected ( ) const

◆ is_registered()

bool DBus::Connection::is_registered ( ) const

True if this connection is already registered.

Referenced by bus_register().

◆ is_valid()

bool DBus::Connection::is_valid ( ) const

◆ name_has_owner()

bool DBus::Connection::name_has_owner ( const std::string &  name) const

Check to see if the given name currently has an owner.

Note that usage of this method in the form if( !connection->name_has_owner( "foo.bar" ) ){ connection->request_name( "foo.bar" ); }

may be subject to race conditions, as multiple applications may be attempting to request the bus name at the same time. Instead, you should set the flags in the request_name method to do this in a bus-atomic manner.

Parameters
name
Returns

◆ notify_dispatcher_or_dispatch()

void DBus::Connection::notify_dispatcher_or_dispatch ( )
private

Depending on what thread this is called from, will either notify the dispatcher that we need to be dispatched, or will do the dispatching needed.

References DBus::DATA_REMAINS, and dispatch().

Referenced by send(), and send_with_reply_blocking().

◆ operator bool()

DBus::Connection::operator bool ( ) const

True if this is a valid connection; false otherwise.

◆ operator<<()

Connection & DBus::Connection::operator<< ( std::shared_ptr< const Message msg)

Blindly sends the message on the connection.

Since you don't get any kind of handle back from this, you should really only use it for sending method returns and signals.

References send().

◆ process_call_message()

void DBus::Connection::process_call_message ( std::shared_ptr< const CallMessage msg)
private

◆ process_signal_message()

void DBus::Connection::process_signal_message ( std::shared_ptr< const SignalMessage msg)
private

Referenced by process_single_message().

◆ process_single_message()

void DBus::Connection::process_single_message ( )
private

◆ register_object()

RegistrationStatus DBus::Connection::register_object ( std::shared_ptr< Object object,
ThreadForCalling  calling = ThreadForCalling::DispatcherThread 
)

Register an object with this connection.

The path that this object is accessible at is part of the object. You may also select which thread the object's methods should be called on.

Parameters
objectThe object to export
callingThe thread in which this object's methods will be called in. Defaults to being the dispatching thread.
Returns
The status of registering an object to be exported.

References DBus::DispatcherThread, DBus::Failed_Invalid_Object, DBus::Failed_Path_in_Use, LOGGER_NAME, SIMPLELOGGER_DEBUG, and DBus::Success.

Referenced by create_object().

◆ register_object_proxy()

bool DBus::Connection::register_object_proxy ( std::shared_ptr< ObjectProxy obj,
ThreadForCalling  calling = ThreadForCalling::DispatcherThread 
)

Add an ObjectProxy to this Connection.

Note that calling create_object_proxy() will call this method automatically.

Parameters
objThe ObjectProxy to register with this connection
Returns

References thread_id_from_calling().

Referenced by create_object_proxy().

◆ release_name()

ReleaseNameResponse DBus::Connection::release_name ( const std::string &  name)

Release the specified name, after requesting it via request_name.

Parameters
nameThe name to release on the bus
Returns

References DBUSCXX_RELEASE_NAME_REPLY_NON_EXISTENT, DBUSCXX_RELEASE_NAME_REPLY_NOT_OWNER, DBUSCXX_RELEASE_NAME_REPLY_RELEASED, DBus::NameNonExistant, DBus::NameReleased, and DBus::NotOwner.

◆ remove_free_signal_proxy()

bool DBus::Connection::remove_free_signal_proxy ( std::shared_ptr< SignalProxyBase proxy)

Remove a free signal proxy, so that it will not be called anymore.

Parameters
proxy
Returns

References LOGGER_NAME, remove_match(), and SIMPLELOGGER_DEBUG.

◆ remove_invalid_threaddispatchers_and_associated_objects()

void DBus::Connection::remove_invalid_threaddispatchers_and_associated_objects ( )
private

Referenced by process_call_message().

◆ remove_match()

bool DBus::Connection::remove_match ( const std::string &  rule)

◆ request_name()

RequestNameResponse DBus::Connection::request_name ( const std::string &  name,
unsigned int  flags = 0 
)

Request the given name on the bus.

Parameters
nameThe name to request, e.g. "com.example.foo"
flagsAny flags with the name; see DBUSCXX_NAME_FLAG_XXX macros
Returns

References DBus::AlreadyOwner, DBUSCXX_REQUEST_NAME_REPLY_ALREADY_OWNER, DBUSCXX_REQUEST_NAME_REPLY_EXISTS, DBUSCXX_REQUEST_NAME_REPLY_IN_QUEUE, DBUSCXX_REQUEST_NAME_REPLY_PRIMARY_OWNER, is_valid(), DBus::NameExists, DBus::NameInQueue, and DBus::PrimaryOwner.

◆ send()

uint32_t DBus::Connection::send ( const std::shared_ptr< const Message message)

Queues up the message to be sent on the bus.

Parameters
messageThe message to send
Returns
The serial of the message

References is_valid(), and notify_dispatcher_or_dispatch().

Referenced by operator<<(), process_call_message(), and send_error_on_handler_result().

◆ send_error_on_handler_result()

void DBus::Connection::send_error_on_handler_result ( std::shared_ptr< const CallMessage msg,
HandlerResult  result 
)
private

Send an error back to the calling application based on HandlerResult.

No-op if the result indicates that there is no error.

References DBUSCXX_ERROR_FAILED, DBUSCXX_ERROR_UNKNOWN_INTERFACE, DBUSCXX_ERROR_UNKNOWN_METHOD, DBus::Handled, DBus::Invalid_Interface, DBus::Invalid_Method, DBus::Invalid_Path, and send().

Referenced by process_call_message().

◆ send_with_reply_blocking()

std::shared_ptr< ReturnMessage > DBus::Connection::send_with_reply_blocking ( std::shared_ptr< const CallMessage msg,
int  timeout_milliseconds = -1 
)

Send a CallMessage, and wait for the reply.

If a timeout is processed, this will throw ErrorNoReply

Parameters
msgThe message to send
timeout_millisecondsHow long to wait for. If -1, will wait the maximum time
Returns
The return message

References DBus::ERROR, is_valid(), LOGGER_NAME, notify_dispatcher_or_dispatch(), DBus::RETURN, DBus::SIGNAL, SIMPLELOGGER_DEBUG, DBus::priv::wait_for_fd_activity(), and write_single_message().

Referenced by introspect().

◆ server_id()

const char * DBus::Connection::server_id ( ) const

◆ set_dispatching_thread()

void DBus::Connection::set_dispatching_thread ( std::thread::id  tid)

Set the ID of the thread that all of the dispatching hapens from.

If a blocking call is attempted on the non-dispatching thread, that thread will block until the dispatching thread handles the data.

By default, the dispatching thread is the thread that this Connection was created in. If using the default Dispatcher, this will be set automatically.

Parameters
tid

◆ signal_needs_dispatch()

sigc::signal< void() > & DBus::Connection::signal_needs_dispatch ( )

This signal is emitted whenever we need to be dispatched.

Cannot call dispatch() in a slot connected to this signal.

Any slots that listen to this signal must be threadsafe, as this may be emitted from any thread.

◆ socket()

int DBus::Connection::socket ( ) const

References is_valid().

◆ start_service()

StartReply DBus::Connection::start_service ( const std::string &  name,
uint32_t  flags = 0 
) const

start_service

Parameters
name
flags
Returns

References DBus::ALREADY_RUNNING, DBUSCXX_START_REPLY_ALREADY_RUNNING, DBUSCXX_START_REPLY_SUCCESS, and DBus::SUCCESS.

◆ thread_id_from_calling()

std::thread::id DBus::Connection::thread_id_from_calling ( ThreadForCalling  calling)
private

◆ unique_name()

std::string DBus::Connection::unique_name ( ) const

Gets the unique name of the connection as assigned by the message bus.

References is_valid().

◆ unix_fd()

int DBus::Connection::unix_fd ( ) const

References is_valid().

◆ unregister_object()

bool DBus::Connection::unregister_object ( const std::string &  path)

◆ write_single_message()

uint32_t DBus::Connection::write_single_message ( std::shared_ptr< const Message msg)
private

Write a single message, return the serial of this message.

This should me called with a lock on m_outgoingLock

Parameters
msg
Returns

Referenced by send_with_reply_blocking().


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