C API tutorial

[Matthew Johnson]

On Tue, 1 Nov 2005, Havoc Pennington wrote:

> Cool! Some small suggestions,

Suggestions are good

>
> 	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.

will that close it when the ref count reaches 0? I was intending for
this whole thing to be called once within the application, so all the
setup would happen at the start, the DBusConnection reference would be
passed around during execution and connection_close() called when the
application quits.

> For interface names, the convention is foo.bar.CapitalLetters
>
> and for signal/method names just CapitalLetters.
>
> Half-tempted to enforce that in the code ;-)

Only if you DOCUMENT IT (-: This is all getting a bit Java-like. I'll
change the ones in the tutorial and my App.

> 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!

Damn I'm ignoring RVs, I shouldn't do that. See below...

>
> 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.

Yeah, the tutorial came out of me trying to work out how the C API
worked and just trying to my my App do something, I tidied it up a bit
for the tutorial, I'll go through it again soon to try and catch the
rest of this.

> 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.

The idea is it would be used in an application which is doing other
stuff which can't block and has a loop which it can asynchronously
check for messages.

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

Oops, yes, see above.

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

Yeah, fine, I'd be annoyed if I copied buggy example code!

On Tue, 1 Nov 2005, J5 wrote:

> This is all really cool though I would rather a tutorial which utilized
> filter functions and read_write_dispatch.  The nice thing about doing it
> that way is it is mostly interchangeable when using a real mainloop so
> the mainloop becomes an implementation detail in the tutorial and not a
> confusing "how should I structure my code?" detail.  We can put sidebars
> for tips on how to get messages without needing a filter function along
> with the pitfalls in doing so.

yeah, I agree it would be nice, looking over the C API it really wasn't
obvious how to use it. For a lot of small apps which only want to expose
one or two things, this is fine though. (This is the tutorial I wrote
because this is what I am doing).

Matt

-- 
Matthew Johnson
http://www.matthew.ath.cx/