Initial Concepts

Concepts #1, #2, #3 and #4: Objects (#1), methods (#2), signals (#3) and proxies (#4)

: A dbus-cxx Object is a collection of methods and signals. A method is an operation that may be invoked on a object and may or may not return a value. A signal is emitted by the object and does not have a return value.

: A dbus-cxx ObjectProxy provides an abstration of a remote Object to a client application. The ObjectProxy provides method and signal proxies that have signatures equivalent to their server-side counterparts.

: A method proxy assembles the parameters of the method call into a D-Bus message and transmits to the server. The response (if any) is returned in the form of a D-Bus message which is then unpacked and returned to the application as the return value from the proxy call.

: A signal proxy is different from a method proxy in that it watches an Object for signal events. These signal events arrive as a D-Bus signal message. When a signal event arrives the parameters are unpacked and emitted locally through the signal proxy callback.

: dbus-cxx relies heavily on sigc++'s signal and slot system for both Objects and their proxies.

: On the server side and object's methods rely upon slots to provide the underlying functionality. When an incoming method call is invoked, the parameters of the call are unpacked and passed to the slot associated with the method.

: Slots are similar to function pointers in C, but can also be a method of a specific class. The details of this are available in the sigc++ documentation and are beyond the scope of this tutorial.

: An early design decision was made to focus on the use of smart pointers as defined in the ANSI C++ committee's tr1 (Technical Report 1), which as of this writing has been accepted by the committee and recommended to ISO for incorporation as the first revision to the C++ standard. A reference implementation can be found in the boost library, the std::tr1 namespace of gcc 4.0 or greater, or the C++0x draft standard in gcc 4.3 or greater.

: Two key concepts are the pointer typedef and the create method defined in each dbus-cxx class.

: The pointer typedef is defined within each class and is typedefed to a smart pointer to that specific class. Thus, DBus::Connection::pointer is a smart pointer to a D-Bus Connection endpoint, and DBus::CallMessage::pointer is a smart pointer to a D-Bus call message.

: Each class also has static create() methods with parameters that are identical to the class' constructors. Class constructors are protected, so in general you cannot access them.

: Instead, you will need to use the class' create() method to dynamically creates an instance of the class. This method will returns a smart pointer of the appropriate type for that class similar to the way the new operator dynamically creates an object and returns a raw pointer to the newly created object.

: Since the create() method is static, you do not need an instance of the class to call it; Classname::create() is sufficient. Thus, to create a new dbus-cxx call message you would use DBus::CallMessage::create() and to create a new dbus-cxx connection you would use DBus::Connection::create().

Naturally, the smart pointer returned from create() can be assigned to the class' pointer type, which allows you to use a syntax such as:

 DBus::CallMessage::pointer my_callmessage = DBus::CallMessage::create();

Continue On: Quick start example 0: A simple server and client

Go Back: Quick Start Guide to dbus-cxx