# DBus-C++

## Desktop Communication Bus System

libdbus-c-- Documentation 0.9.0

- Files
- Data Structures
- Globals
- Main Page

Classes | Public Types | Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
DBus::Connection Class Reference

`#include <connection.h>`

## Classes

struct | Private

## Public Types

typedef std::list< Private * > | PrivatePList

## Public Member Functions

| Connection (Private *)
| Connection (const char *address, bool priv=true)
| Connection (const Connection &c)
virtual | ~Connection ()
Dispatcher * | setup (Dispatcher *)
bool | operator== (const Connection &) const
void | add_match (const char *rule)
| Adds a match rule to match messages going through the message bus.
void | remove_match (const char *rule, bool throw_on_error)
| Removes a previously-added match rule "by value" (the most recently-added identical rule gets removed).
bool | add_filter (MessageSlot &s)
| Adds a message filter.
void | remove_filter (MessageSlot &s)
| Removes a previously-added message filter.
bool | unique_name (const char *n)
| Sets the unique name of the connection, as assigned by the message bus.
const char * | unique_name () const
| Gets the unique name of the connection as assigned by the message bus.
bool | register_bus ()
| Registers a connection with the bus.
bool | connected () const
| Gets whether the connection is currently open.
void | disconnect ()
| Closes a private connection, so no further data can be sent or received.
void | exit_on_disconnect (bool exit)
| Set whether _exit() should be called when the connection receives a disconnect signal.
void | flush ()
| Blocks until the outgoing message queue is empty.
bool | send (const Message &msg, unsigned int *serial=NULL)
| Adds a message to the outgoing message queue.
Message | send_blocking (Message &msg, int timeout=-1)
| Sends a message and blocks a certain time period while waiting for a reply.
PendingCall | send_async (Message &msg, int timeout=-1)
| Queues a message to send, as with send(), but also returns a DBusPendingCall used to receive a reply to the message.
void | request_name (const char *name, int flags=0)
unsigned long | sender_unix_uid (const char *sender)
bool | has_name (const char *name)
| Asks the bus whether a certain name has an owner.
bool | start_service (const char *name, unsigned long flags)
| Starts a service that will request ownership of the given name.
const std::vector< std::string > & | names ()
void | set_timeout (int timeout)
int | get_timeout ()

## Static Public Member Functions

static Connection | SystemBus ()
static Connection | SessionBus ()
static Connection | ActivationBus ()

## Private Member Functions

DXXAPILOCAL void | init ()

## Private Attributes

RefPtrI< Private > | _pvt
int | _timeout

## Friends

class | ObjectAdaptor

## Detailed Description

Definition at line 48 of file connection.h.

## Member Typedef Documentation

## ◆ PrivatePList

typedef std::list<Private *> DBus::Connection::PrivatePList

Definition at line 60 of file connection.h.

## Constructor & Destructor Documentation

## ◆ Connection() [1/3]

Connection::Connection | ( | Connection::Private * | p | ) |

Definition at line 222 of file connection.cpp.

References _pvt, _timeout, DBus::default_dispatcher, and setup().

Referenced by ActivationBus(), Connection(), operator==(), SessionBus(), and SystemBus().

## ◆ Connection() [2/3]

Connection::Connection | ( | const char * | address,
|  | bool | priv = true )

Definition at line 205 of file connection.cpp.

References _pvt, _timeout, DBus::debug_log, DBus::default_dispatcher, and setup().

## ◆ Connection() [3/3]

Connection::Connection | ( | const Connection & | c | ) |

Definition at line 228 of file connection.cpp.

References _pvt, _timeout, and Connection().

## ◆ ~Connection()

Connection::~Connection | ( |  | ) |

virtual

Definition at line 234 of file connection.cpp.

References _pvt.

## Member Function Documentation

## ◆ ActivationBus()

Connection Connection::ActivationBus | ( |  | ) |

static

Definition at line 200 of file connection.cpp.

References Connection().

## ◆ add_filter()

bool Connection::add_filter | ( | MessageSlot & | s | ) |

Adds a message filter.

Filters are handlers that are run on all incoming messages, prior to the objects registered with ObjectAdaptor::register_obj(). Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more than once. Filters added during a filter callback won't be run on the message being processed.

Parameters

  s | The MessageSlot to add.

Definition at line 352 of file connection.cpp.

References _pvt, DBus::debug_log, DBus::Connection::Private::message_filter_stub(), and unique_name().

Referenced by DBus::ObjectProxy::register_obj().

## ◆ add_match()

void Connection::add_match | ( | const char * | rule | ) |

Adds a match rule to match messages going through the message bus.

The "rule" argument is the string form of a match rule.

If you pass NULL for the error, this function will not block; the match thus won't be added until you flush the connection, and if there's an error adding the match (only possible error is lack of resources in the bus), you won't find out about it.

Normal API conventions would have the function return a boolean value indicating whether the error was set, but that would require blocking always to determine the return value.

The AddMatch method is fully documented in the D-Bus specification. For quick reference, the format of the match rules is discussed here, but the specification is the canonical version of this information.

Rules are specified as a string of comma separated key/value pairs. An example is "type='signal',sender='org.freedesktop.DBus', interface='org.freedesktop.DBus',member='Foo', path='/bar/foo',destination=':452345.34'"

Possible keys you can match on are type, sender, interface, member, path, destination and numbered keys to match message args (keys are 'arg0', 'arg1', etc.). Omitting a key from the rule indicates a wildcard match. For instance omitting the member from a match rule but adding a sender would let all messages from that sender through regardless of the member.

Matches are inclusive not exclusive so as long as one rule matches the message will get through. It is important to note this because every time a essage is received the application will be paged into memory to process it. This can cause performance problems such as draining batteries on embedded platforms.

If you match message args ('arg0', 'arg1', and so forth) only string arguments will match. That is, arg0='5' means match the string "5" not the integer 5.

Currently there is no way to match against non-string arguments.

Matching on interface is tricky because method call messages only optionally specify the interface. If a message omits the interface, then it will NOT match if the rule specifies an interface name. This means match rules on method calls should not usually give an interface.

However, signal messages are required to include the interface so when matching signals usually you should specify the interface in the match rule.

For security reasons, you can match arguments only up to DBUS_MAXIMUM_MATCH_RULE_ARG_NUMBER.

Match rules have a maximum length of DBUS_MAXIMUM_MATCH_RULE_LENGTH bytes.

Both of these maximums are much higher than you're likely to need, they only exist because the D-Bus bus daemon has fixed limits on all resource usage.

Parameters

  rule | Textual form of match rule.

Exceptions

  Error |

Definition at line 321 of file connection.cpp.

References _pvt, DBus::debug_log, and unique_name().

Referenced by DBus::ObjectProxy::register_obj(), and request_name().

## ◆ connected()

bool Connection::connected | ( |  | ) | const

Gets whether the connection is currently open.

A connection may become disconnected when the remote application closes its end, or exits; a connection may also be disconnected with disconnect().

There are not separate states for "closed" and "disconnected," the two terms are synonymous.

Returns
  true If the connection is still alive.

Definition at line 290 of file connection.cpp.

References _pvt.

## ◆ disconnect()

void Connection::disconnect | ( |  | ) |

Closes a private connection, so no further data can be sent or received.

This disconnects the transport (such as a socket) underlying the connection.

Attempts to send messages after closing a connection are safe, but will result in error replies generated locally in libdbus.

This function does not affect the connection's reference count. It's safe to close a connection more than once; all calls after the first do nothing. It's impossible to "reopen" a connection, a new connection must be created. This function may result in a call to the DBusDispatchStatusFunction set with Private::init(), as the disconnect message it generates needs to be dispatched.

If a connection is dropped by the remote application, it will close itself.

You must close a connection prior to releasing the last reference to the connection.

You may not close a shared connection. Connections created with dbus_connection_open() or dbus_bus_get() are shared. These connections are owned by libdbus, and applications should only unref them, never close them. Applications can know it is safe to unref these connections because libdbus will be holding a reference as long as the connection is open. Thus, either the connection is closed and it is OK to drop the last reference, or the connection is open and the app knows it does not have the last reference.

Connections created with dbus_connection_open_private() or dbus_bus_get_private() are not kept track of or referenced by libdbus. The creator of these connections is responsible for calling dbus_connection_close() prior to releasing the last reference, if the connection is not already disconnected.

Todo
  dbus_connection_disconnect() was removed in dbus 0.9x. Maybe this function should be renamed to close().

Definition at line 295 of file connection.cpp.

References _pvt.

## ◆ exit_on_disconnect()

void Connection::exit_on_disconnect | ( | bool | exit | ) |

Set whether _exit() should be called when the connection receives a disconnect signal.

The call to _exit() comes after any handlers for the disconnect signal run; handlers can cancel the exit by calling this function.

By default, exit_on_disconnect is false; but for message bus connections returned from dbus_bus_get() it will be toggled on by default.

Parameters

  exit | true If _exit() should be called after a disconnect signal.

Definition at line 301 of file connection.cpp.

References _pvt.

## ◆ flush()

void Connection::flush | ( |  | ) |

Blocks until the outgoing message queue is empty.

Definition at line 316 of file connection.cpp.

References _pvt.

## ◆ get_timeout()

int Connection::get_timeout | ( |  | ) |

Definition at line 470 of file connection.cpp.

References _timeout.

## ◆ has_name()

bool Connection::has_name | ( | const char * | name | ) |

Asks the bus whether a certain name has an owner.

Using this can easily result in a race condition, since an owner can appear or disappear after you call this.

If you want to request a name, just request it; if you want to avoid replacing a current owner, don't specify DBUS_NAME_FLAG_REPLACE_EXISTING and you will get an error if there's already an owner.

Parameters

  name | The name.

Exceptions

  Error |

Definition at line 438 of file connection.cpp.

References _pvt.

## ◆ init()

DXXAPILOCAL void DBus::Connection::init | ( |  | ) |

private

References DXXAPILOCAL.

## ◆ names()

const std::vector< std::string > & Connection::names | ( |  | ) |

Definition at line 449 of file connection.cpp.

References _pvt.

## ◆ operator==()

bool Connection::operator== | ( | const Connection & | c | ) | const

Definition at line 274 of file connection.cpp.

References _pvt, and Connection().

## ◆ register_bus()

bool Connection::register_bus | ( |  | ) |

Registers a connection with the bus.

This must be the first thing an application does when connecting to the message bus. If registration succeeds, the unique name will be set, and can be obtained using unique_name(void).

This function will block until registration is complete.

If the connection has already registered with the bus (determined by checking whether unique_name(void) returns a non-NULL value), then this function does nothing.

If you use dbus_bus_get() or dbus_bus_get_private() this function will be called for you. (Not sure if this is yet wrapped.)

Note
  Just use dbus_bus_get() or dbus_bus_get_private() instead of register_bus() and save yourself some pain. Using register_bus() manually is only useful if you have your own custom message bus not found in DBusBusType.

If you open a bus connection by the contructor of Connection() you will have to register_bus() yourself, or make the appropriate registration method calls yourself. If you send the method calls yourself, call unique_name(const char*) with the unique bus name you get from the bus.

For shared connections (created with dbus_connection_open()) in a multithreaded application, you can't really make the registration calls yourself, because you don't know whether some other thread is also registering, and the bus will kick you off if you send two registration messages. (TODO: how is this done in the wrapper?)

If you use register_bus() however, there is a lock that keeps both apps from registering at the same time.

The rule in a multithreaded app, then, is that register_bus() must be used to register, or you need to have your own locks that all threads in the app will respect.

In a single-threaded application you can register by hand instead of using register_bus(), as long as you check unique_name(void) to see if a unique name has already been stored by another thread before you send the registration messages.

Definition at line 279 of file connection.cpp.

References _pvt.

## ◆ remove_filter()

void Connection::remove_filter | ( | MessageSlot & | s | ) |

Removes a previously-added message filter.

It is a programming error to call this function for a handler that has not been added as a filter. If the given handler was added more than once, only one instance of it will be removed (the most recently-added instance).

Parameters

  s | The MessageSlot to remove.

Definition at line 358 of file connection.cpp.

References _pvt, DBus::debug_log, DBus::Connection::Private::message_filter_stub(), and unique_name().

Referenced by DBus::ObjectProxy::unregister_obj().

## ◆ remove_match()

void Connection::remove_match | ( | const char * | rule,
|  | bool | throw_on_error )

Removes a previously-added match rule "by value" (the most recently-added identical rule gets removed).

The "rule" argument is the string form of a match rule.

The bus compares match rules semantically, not textually, so whitespace and ordering don't have to be identical to the rule you passed to add_match().

Parameters

  rule | Textual form of match rule.

Exceptions

  Error |

Definition at line 332 of file connection.cpp.

References _pvt, DBus::debug_log, and unique_name().

Referenced by DBus::ObjectProxy::unregister_obj().

## ◆ request_name()

void Connection::request_name | ( | const char * | name,
|  | int | flags = 0 )

Definition at line 399 of file connection.cpp.

References _pvt, add_match(), DBus::debug_log, and unique_name().

## ◆ send()

bool Connection::send | ( | const Message & | msg,
|  | unsigned int * | serial = NULL )

Adds a message to the outgoing message queue.

Does not block to write the message to the network; that happens asynchronously. To force the message to be written, call dbus_connection_flush(). Because this only queues the message, the only reason it can fail is lack of memory. Even if the connection is disconnected, no error will be returned.

If the function fails due to lack of memory, it returns FALSE. The function will never fail for other reasons; even if the connection is disconnected, you can queue an outgoing message, though obviously it won't be sent.

The message serial is used by the remote application to send a reply; see Message::serial() or the D-Bus specification.

Parameters

  msg | The Message to write.
  serial | Return location for message serial, or NULL if you don't care.

Returns
  true On success.

Definition at line 364 of file connection.cpp.

References _pvt, and DBus::Message::_pvt.

Referenced by DBus::ObjectAdaptor::_emit_signal(), DBus::ObjectProxy::_invoke_method_noreply(), DBus::ObjectAdaptor::handle_message(), DBus::ObjectAdaptor::return_error(), and DBus::ObjectAdaptor::return_now().

## ◆ send_async()

PendingCall Connection::send_async | ( | Message & | msg,
|  | int | timeout = -1 )

Queues a message to send, as with send(), but also returns a DBusPendingCall used to receive a reply to the message.

If no reply is received in the given timeout_milliseconds, this function expires the pending reply and generates a synthetic error reply (generated in-process, not by the remote application) indicating that a timeout occurred.

A PendingCall will see a reply message before any filters or registered object path handlers. See Connection::Private::do_dispatch() in dbus documentation for details on when handlers are run. (here: Connection::Private::do_dispatch())

A PendingCall will always see exactly one reply message, unless it's cancelled with PendingCall::cancel().

If -1 is passed for the timeout, a sane default timeout is used. -1 is typically the best value for the timeout for this reason, unless you want a very short or very long timeout. There is no way to avoid a timeout entirely, other than passing INT_MAX for the timeout to mean "very long timeout." libdbus clamps an INT_MAX timeout down to a few hours timeout though.

Parameters

  msg | The Message to write.
  timeout | Timeout in milliseconds (omit for default).

Exceptions

  ErrorNoMemory |

Definition at line 388 of file connection.cpp.

References _pvt, and DBus::Message::_pvt.

## ◆ send_blocking()

Message Connection::send_blocking | ( | Message & | msg,
|  | int | timeout = -1 )

Sends a message and blocks a certain time period while waiting for a reply.

This function does not reenter the main loop, i.e. messages other than the reply are queued up but not processed. This function is used to invoke method calls on a remote object.

If a normal reply is received, it is returned, and removed from the incoming message queue. If it is not received, NULL is returned and the error is set to DBUS_ERROR_NO_REPLY. If an error reply is received, it is converted to a DBusError and returned as an error, then the reply message is deleted and NULL is returned. If something else goes wrong, result is set to whatever is appropriate, such as DBUS_ERROR_NO_MEMORY or DBUS_ERROR_DISCONNECTED.

Warning
  While this function blocks the calling thread will not be processing the incoming message queue. This means you can end up deadlocked if the application you're talking to needs you to reply to a method. To solve this, either avoid the situation, block in a separate thread from the main connection-dispatching thread, or use PendingCall to avoid blocking.

Parameters

  msg | The Message to write.
  timeout | Timeout in milliseconds (omit for default).

Exceptions

  Error |

Definition at line 369 of file connection.cpp.

References _pvt, DBus::Message::_pvt, and _timeout.

Referenced by DBus::ObjectProxy::_invoke_method().

## ◆ sender_unix_uid()

unsigned long Connection::sender_unix_uid | ( | const char * | sender | ) |

Definition at line 427 of file connection.cpp.

References _pvt.

## ◆ SessionBus()

Connection Connection::SessionBus | ( |  | ) |

static

Definition at line 195 of file connection.cpp.

References Connection().

## ◆ set_timeout()

void Connection::set_timeout | ( | int | timeout | ) |

Definition at line 465 of file connection.cpp.

References _timeout.

## ◆ setup()

Dispatcher * Connection::setup | ( | Dispatcher * | dispatcher | ) |

Definition at line 239 of file connection.cpp.

References _pvt, DBus::debug_log, DBus::default_dispatcher, DBus::Dispatcher::Private::on_add_timeout(), DBus::Dispatcher::Private::on_add_watch(), DBus::Dispatcher::Private::on_rem_timeout(), DBus::Dispatcher::Private::on_rem_watch(), DBus::Dispatcher::Private::on_toggle_timeout(), DBus::Dispatcher::Private::on_toggle_watch(), and DBus::Dispatcher::queue_connection().

Referenced by Connection(), and Connection().

## ◆ start_service()

bool Connection::start_service | ( | const char * | name,
|  | unsigned long | flags )

Starts a service that will request ownership of the given name.

The returned result will be one of be one of DBUS_START_REPLY_SUCCESS or DBUS_START_REPLY_ALREADY_RUNNING if successful. Pass NULL if you don't care about the result.

The flags parameter is for future expansion, currently you should specify 0.

It's often easier to avoid explicitly starting services, and just send a method call to the service's bus name instead. Method calls start a service to handle them by default unless you call dbus_message_set_auto_start() to disable this behavior.

Todo
  dbus_message_set_auto_start() not yet wrapped!

Definition at line 454 of file connection.cpp.

References _pvt.

## ◆ SystemBus()

Connection Connection::SystemBus | ( |  | ) |

static

Definition at line 190 of file connection.cpp.

References Connection().

## ◆ unique_name() [1/2]

const char * Connection::unique_name | ( | void |  | ) | const

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

Only possible after the connection has been registered with the message bus. All connections returned by dbus_bus_get() or dbus_bus_get_private() have been successfully registered. (Not sure if this is yet wrapped.)

The name remains valid until the connection is freed, and should not be freed by the caller.

Other than dbus_bus_get(), there are two ways to set the unique name; one is register_bus(), the other is unique_name(const char*). You are responsible for calling unique_name(const char*) if you register by hand instead of using register_bus().

Definition at line 311 of file connection.cpp.

References _pvt.

Referenced by add_filter(), add_match(), remove_filter(), remove_match(), and request_name().

## ◆ unique_name() [2/2]

bool Connection::unique_name | ( | const char * | n | ) |

Sets the unique name of the connection, as assigned by the message bus.

Can only be used if you registered with the bus manually (i.e. if you did not call register_bus()). Can only be called once per connection. After the unique name is set, you can get it with unique_name(void).

The only reason to use this function is to re-implement the equivalent of register_bus() yourself. One (probably unusual) reason to do that might be to do the bus registration call asynchronously instead of synchronously.

Note
  Just use dbus_bus_get() or dbus_bus_get_private(), or worst case register_bus(), instead of messing with this function. There's really no point creating pain for yourself by doing things manually. (Not sure if this is yet wrapped.)

It's hard to use this function safely on shared connections (created by Connection()) in a multithreaded application, because only one registration attempt can be sent to the bus. If two threads are both sending the registration message, there is no mechanism in libdbus itself to avoid sending it twice.

Thus, you need a way to coordinate which thread sends the registration attempt; which also means you know which thread will call unique_name(const char*). If you don't know about all threads in the app (for example, if some libraries you're using might start libdbus-using threads), then you need to avoid using this function on shared connections.

Parameters

  n | The unique name.

Definition at line 306 of file connection.cpp.

References _pvt.

## Friends And Related Symbol Documentation

## ◆ ObjectAdaptor

friend class ObjectAdaptor

friend

Definition at line 464 of file connection.h.

References ObjectAdaptor.

Referenced by ObjectAdaptor.

## Member Data Documentation

## ◆ _pvt

RefPtrI<Private> DBus::Connection::_pvt

private

Definition at line 461 of file connection.h.

Referenced by add_filter(), add_match(), connected(), Connection(), Connection(), Connection(), disconnect(), exit_on_disconnect(), flush(), has_name(), names(), operator==(), register_bus(), remove_filter(), remove_match(), request_name(), send(), send_async(), send_blocking(), sender_unix_uid(), setup(), start_service(), unique_name(), unique_name(), and ~Connection().

## ◆ _timeout

int DBus::Connection::_timeout

private

Definition at line 462 of file connection.h.

Referenced by Connection(), Connection(), Connection(), get_timeout(), send_blocking(), and set_timeout().

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

- connection.h
- connection.cpp