RFC: Libdbus++ - C++ bindings for DBus

[Zilberstein, EugeneX]

Hi all-
I needed some raw DBus C++ bindings to use for a project here at Intel,
so I repackaged Paolo Durante's C++ bindings into a standalone package.
The result is a nice simple demo that doesn't pull in GLib or Qt; it can
also do some other neat tricks: 

	The demo sends and receives method and signal pings.
	Demonstrates source and destination filtering. 
	Implements an object (PendingCall) for creating asynchronous
call state machines.

Please let me know if you find this useful, have ideas, etc. 

The code is temporarily hosted at: 
http://www.twiki.org/cgi-bin/view/Main/LibDBus

Gene Zilberstein
eugenex.zilberstein at intel.com
------------------------------------------------------------------------
-----------------------------------------------

Libdbus++ package, v0.3
5/11/06
Packaged by Gene Zilberstein <eugenex.zilberstein at intel.com>
Original source: http://svn.berlios.de/viewcvs/bluetool/trunk/lib/cbus/

1) In order to compile the libdbus++ package, the following packages
are needed:

	dbus-1
	libsigc++-2.0

2) Once those packages are installed, you can configure the libraries 
and the demo with

	./bootstrap

from the root directory.

3) To compile the source, just do

	make

from the same directory.
NOTES:	- Install targets are not in the build scripts yet. 
	- The libraries are compiled and linked statically.

   When the program has built, display the program options:

	./examples/demo1/demo1 --help


4) To communicate through the session DBus:

   a) In a shell, run the following commands, which will start the
session bus
	and set a var to point to it:

	eval `dbus-launch`
	export DBUS_SESSION_BUS_ADDRESS

   b) Create 3 xterm's, which will inherit DBUS_SESSION_BUS_ADDRESS:
	xterm &
	xterm &
	xterm &

   c) In these xterms, run:
      xterm 1: 
	dbus-monitor
      xterm 2: 
 	./examples/demo1/demo1 

	The 

   d) Send our program some DBus messages. When you run the commands in
xterm 3, you should observe new debug
	output in xterms 1 + 2. 

      xterm 3:

      * Sending a method call to the local object. This should return
the string arguments in the response. 

	dbus-send --type=method_call --print-reply
--dest=dbus.examples.demo1 /com/intel/phs/Device
com.intel.phs.Device.EchoArgs string:'bauble' string:'arg2'

      * Sending out a signal. Since this is a signal, it does not wait
for a response.
	The demo trace shows that the signal was triggered.

	dbus-send --type=signal /com/intel/phs/Device
com.intel.phs.Device.TheirSignal string:'bauble' string:'arg2'

      * Calling a proxy method. This will call the DBus daemon by proxy,
massage the returned data, and return it.

	dbus-send --type=method_call --print-reply
--dest=dbus.examples.demo1 /com/intel/phs/Device
com.intel.phs.Device.ProxyCall string:'bauble' string:'arg2'


   If this all works, you should have a working session bus!


5) To communicate through the system DBus (requires root access):

   a) Add the permissions to the config directory and restart DBus: 

	cp ./examples/phs.conf /etc/dbus-1/system.d/
	/etc/init.d/dbus restart

   b) Make sure that the system dbus daemon is running: 

	localhost ~ # ps aux | grep dbus
	101      22349  0.0  0.4   2000   268 ?        Ss   00:26   0:00
/usr/bin/dbus-daemon --system

   c) Open a shell window and run the DBus monitor utility:

	dbus-monitor --system

   d) Run demo1 as root:

	./examples/demo1/demo1 --system

	Please examine the commented demo source in demo1.cpp.
	The demo's output shows the results of a ListNames method call
to the system DBus.
	The dbus-monitor shows that a DeviceAdded signal was sent to the
system DBus.

   e) Open another shell window and send our program some DBus messages:

      * Sending a method call to the local object:

	dbus-send --system --type=method_call --print-reply
--dest=dbus.examples.demo1 /com/intel/phs/Device
com.intel.phs.Device.EchoArgs string:'bauble' string:'arg2'

	(This should return the string arguments in the response. Also
observe the monitor output and the demo trace.)

      * Sending a signal:

	dbus-send --system --type=signal /com/intel/phs/Device
com.intel.phs.Device.TheirSignal string:'bauble' string:'arg2'

	(Since this is a signal, it does not wait for a response; the
demo trace shows that the signal was triggered.)

6) Use the demo's ping facilities to demonstrate signal and method
communication:

	a) Demonstrate signal sender filtering. In the 3 session-bus
Xterms, start 3 copies of the demo:

	# monitor signals coming only from moo.foo
	 ./examples/demo1/demo1 --appname boo.hoo --ssender=moo.foo
	# send a signal 
	 ./examples/demo1/demo1 --appname moo.foo --sping
	# send a signal (will not be received by boo.hoo)
	 ./examples/demo1/demo1 --appname who.what --sping

	b) Demonstrate method pings. Stop the who.what demo; start up
another like this:
	 ./examples/demo1/demo1 --appname bar.baz --mping boo.hoo

------------------------------------------------------------------------
-----------------------------------------------

Release notes:

v0.3,   5/11/06
	Corrected signal handling.
	Added signal source filtering. 
	Added signal and method ping options. 

v0.2.1, 5/5/06
	Removed dependency on boost.

v0.2,   5/4/06
	The PendingCall object is ready to use for asynchronous calls. 
	Created MyPendingCall and ProxyCallMachine demos (internal and
external async call state machines). 
	Enhanced usage model for MessageIter::append_...:
		msg.w_iter().append_string("foo")
			    .append_uint16(0x1234)
			    .append_uint32(0x12345678);
	Added command-line help and option processing. 

v0.1,   5/2/06
	Synchronous calls work. 

------------------------------------------------------------------------
-----------------------------------------------
Note from the original developers: 
THIS SOFTWARE IS STILL UNDER DEVELOPMENT, IF YOU'RE WILLING
TO INSTALL AND USE THIS SOFTWARE ON PRODUCTION SYSTEMS, PLEASE
WAIT UNTIL A STABLE VERSION IS RELEASED, 
Contact: Paolo Durante <shackan at gmail.com>