PATCH: Changes to make dbus marshalling code independantly useable

[William Lachance]

Hi all,

As originally proposed in this thread:

http://lists.freedesktop.org/archives/dbus/2007-August/008321.html

I've written up a patch that adds a function to D-Bus
(dbus_message_demarshal_bytes_needed) that allows you to find out how
many bytes will be demarshalled (if any) by dbus_message_demarshal.
This, along with a few other minor modifications (described below),
allows a user of D-Bus to write their own connection and message queue
management routines, but still re-use D-Bus's rock solid message
marshalling/demarshalling code.

We have actually been using this approach for a while with WvStreams'
D-Bus library (http://code.google.com/p/wvstreams) which is used
directly by the versaplex (http://code.google.com/p/versaplex) and
pathfinder (http://code.google.com/p/pathfinder-pki) projects, so the
utility is not just hypothetical. Up to now, we've been using private
interfaces in D-Bus to do this (boo! hiss!).  Obviously it would be
better if WvStreams could be a good citizen and just consume the public
D-Bus API, so it would be great if these patches were applied.

Additional changes beyond the addition of this function:

- Lock the message (again) in dbus_message_marshal. In normal cases,
this will be handled by the D-Bus message transport, but obviously if
you're writing your own that won't work. This is absolutely required
because the header lengths are updated as part of the locking process.
- Expose the dbus_message_set_serial function as public API (again
required because we don't have a transport to set this for us).
- Add unit tests for testing the new dbus_message_marshal_bytes_needed
function.

Note there is one slight difference between the way the
dbus_message_demarshal_bytes_needed function was implemented from
Thiago's original wish: instead of returning an error if there isn't
even enough data in the buffer to parse a message header, I decided to
return 0 (meaning more data needs to be read). I find this API a bit
more usable personally (removes the requirement for some extra checks on
my end as a user of the API). Obviously this is open for
discussion/debate if there's something I haven't thought of.

I've seperated out the latter change into its own patch. I've filed a
bugzilla entry for people to follow
(http://bugs.freedesktop.org/show_bug.cgi?id=19567), but the HACKING
instructions suggested that discussing this change on the mailing list
was mandatory (since it adds new API), so that's what I'm doing here. :)

Thanks,
-- 
William Lachance <wrlach at gmail.com>