C API tutorial

[Havoc Pennington]

Hi,

On Tue, 2005-11-01 at 12:27 +0000, Matthew Johnson wrote:
> Having waded through the API docs myself I thought I ought to put my
> example code up somewhere and write a short tutorial for anyone else who
> is trying to use the C API. It's available here:
> 
> http://www.matthew.ath.cx/misc/dbus
> 

Cool! Some small suggestions,

	After you have finished with the bus you should close the 
        connection.

   	dbus_connection_close(conn);

The dbus_bus_get() bus is a shared connection within the process, so
normally you would not close this connection. You do want to unref() the
connection when you're done though.

You can also use dbus_bus_get_private() to get your very own connection
to the bus. In that case, you _do_ want to close it, since nobody else
is using it.

For interface names, the convention is foo.bar.CapitalLetters

and for signal/method names just CapitalLetters.

Half-tempted to enforce that in the code ;-)

You check for out-of-memory failure on dbus_message_new but not for some
other functions, like 
dbus_message_iter_append_basic, dbus_connection_send
in a tutorial it's probably best to always check.
yes it sucks but that's why the high-level bindings exist!

When you read the method reply parameters, you are trusting that the
other end sent the right thing; if you are trying to be secure/robust
you would need to check the parameter types and be sure there are enough
parameters.

I would consider the loop with sleep(1) in it to be moderately bad in a
real production app; dbus_connection_read_write_dispatch() would be
better. If you want to use dbus_connection_pop(), then we might need to
provide dbus_connection_read_write() I guess.

You only unref() the msg if it is the expected method call, leaking it
otherwise no?

Anyway, cool, I'm just being nitpicky since it's example code people
will be copying.

Havoc