2003-09-29 Havoc Pennington <hp@pobox.com>

	* Merge dbus-object-names branch. To see the entire patch
	do cvs diff -r DBUS_OBJECT_NAMES_BRANCHPOINT -r dbus-object-names,
	it's huuuuge though.
	To revert, I tagged DBUS_BEFORE_OBJECT_NAMES_MERGE.

2003-09-28  Havoc Pennington  <hp@pobox.com>

	* HACKING: update to reflect new server

2003-09-26  Seth Nickell  <seth@gnome.org>

	* python/dbus.py:
	* python/examples/example-signals.py:

	Start implementing some notions of signals. The API
	is really terrible, but they sort of work (with the
	exception of being able to filter by service, and to
	transmit signals *as* a particular service). Need to
	figure out how to make messages come from the service
	we registered :-(

	* python/dbus_bindings.pyx.in:

	Removed duplicate message_handler callbacks.

2003-09-25  Havoc Pennington  <hp@redhat.com>

	* bus/session.conf.in: fix my mess

2003-09-25  Havoc Pennington  <hp@pobox.com>

	* bus/session.conf.in: fix security policy, reported by Seth Nickell

2003-09-25  Seth Nickell  <seth@gnome.org>

	* python/examples/example-service.py:

	Johan notices complete wrong code in example-service, but
	completely wrong in a way that works exactly the same (!).
	Johan is confused, how could this possibly work? Example
	code fails to serve purpose of making things clear.
	Seth fixes.

2003-09-25  Mark McLoughlin  <mark@skynet.ie>

	* doc/dbus-specification.sgml: don't require header fields
	to be 4-byte aligned and specify that fields should be
	distinguished from padding by the fact that zero is not
	a valid field name.

	* doc/TODO: remove re-alignment item and add item to doc
	the OBJECT_PATH type.

	* dbus/dbus-message.c:
	(HeaderField): rename the original member to value_offset
	and introduce a name_offset member to keep track of where
	the field actually begins.
	(adjust_field_offsets): remove.
	(append_int_field), (append_uint_field),
	(append_string_field): don't align the start of the header
	field to a 4-byte boundary.
	(get_next_field): impl finding the next marhsalled field
	after a given field.
	(re_align_field_recurse): impl re-aligning a number of
	already marshalled fields.
	(delete_field): impl deleting a field of any type and
	re-aligning any following fields.
	(delete_int_or_uint_field), (delete_string_field): remove.
	(set_int_field), (set_uint_field): no need to re-check
	that we have the correct type for the field.
	(set_string_field): ditto and impl re-aligning any
	following fields.
	(decode_header_data): update to take into account that
	the fields aren't 4-byte aligned any more and the new
	way to distinguish padding from header fields. Also,
	don't exit when there is too much header padding.
	(process_test_subdir): print the directory.
	(_dbus_message_test): add test to make sure a following
	field is re-aligned correctly after field deletion.

	* dbus/dbus-string.[ch]:
	(_dbus_string_insert_bytes): rename from insert_byte and
	allow the insert of multiple bytes.
	(_dbus_string_test): test inserting multiple bytes.

	* dbus/dbus-marshal.c: (_dbus_marshal_set_string): add
	warning note to docs about having to re-align any
	marshalled values following the string.

	* dbus/dbus-message-builder.c:
	(append_string_field), (_dbus_message_data_load):
	don't align the header field.

	* dbus/dbus-auth.c: (process_test_subdir): print the
	directory.

	* test/break-loader.c: (randomly_add_one_byte): upd. for
	insert_byte change.

	* test/data/invalid-messages/bad-header-field-alignment.message:
	new test case.

	* test/data/valid-messages/unknown-header-field.message: shove
	a dict in the unknown field.

2003-09-25  Seth Nickell  <seth@gnome.org>

	* python/dbus.py:
	* python/dbus_bindings.pyx.in:

	Handle return values.

	* python/examples/example-client.py:
	* python/examples/example-service.py:

	Pass back return values from the service to the client.

2003-09-24  Seth Nickell  <seth@gnome.org>

	* python/dbus.py:

	Connect Object methods (when you are sharing an object) up... pass
	in a list of methods to be shared. Sharing all the methods just
	worked out too weird. You can now create nice Services over the
	DBus in Python. :-)

	* python/dbus_bindings.pyx.in:

	Keep references to user_data tuples passed into C functions so
	Python doesn't garbage collect on us.

	Implement MethodReturn and Error subclasses of Message for creating
	DBusMessage's of those types.

	* python/examples/example-client.py:
	* python/examples/example-service.py:

	Simple example code showing both how create DBus services and objects,
	and how to use them.

2003-09-23  Havoc Pennington  <hp@pobox.com>

	* glib/dbus-gproxy.c (dbus_gproxy_manager_filter): implement

2003-09-23  Havoc Pennington  <hp@redhat.com>

	* glib/dbus-gproxy.c (dbus_gproxy_connect_signal): implement
	(dbus_gproxy_disconnect_signal): implement
	(dbus_gproxy_manager_remove_signal_match): implement
	(dbus_gproxy_manager_add_signal_match): implement
	(dbus_gproxy_oneway_call): implement

2003-09-23  Havoc Pennington  <hp@pobox.com>

	* glib/dbus-gproxy.c (struct DBusGProxy): convert to a GObject
	subclass. This means dropping the transparent thread safety of the
	proxy; you now need a separate proxy per-thread, or your own
	locking on the proxy. Probably right anyway.
	(dbus_gproxy_ref, dbus_gproxy_unref): nuke, just use g_object_ref

2003-09-22  Havoc Pennington  <hp@redhat.com>

	* glib/dbus-gproxy.c (dbus_gproxy_manager_get): implement

2003-09-21  Seth Nickell  <seth@gnome.org>

        First checkin of the Python bindings.

	* python/.cvsignore:
	* python/Makefile.am:
	* python/dbus_bindings.pyx.in:
	* python/dbus_h_wrapper.h:

	Pieces for Pyrex to operate on, building a dbus_bindings.so
	python module for low-level access to the DBus APIs.

	* python/dbus.py:

	High-level Python module for accessing DBus objects.

	* configure.in:
	* Makefile.am:

	Build stuff for the python bindings.

	* acinclude.m4:

	Extra macro needed for finding the Python C header files.

2003-09-21  Havoc Pennington  <hp@pobox.com>

	* glib/dbus-gproxy.c (dbus_gproxy_manager_new): start
	implementing the proxy manager, didn't get very far.

	* dbus/dbus-bus.c (dbus_bus_add_match): new
	(dbus_bus_remove_match): new

	* glib/dbus-gproxy.c (dbus_gproxy_new_for_service): add a
	path_name argument; adjust the other not-yet-implemented
	gproxy constructors to be what I think they should be.

2003-09-21  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-bus.c (dbus_bus_get): set exit_on_disconnect to TRUE
	by default for message bus connections.

	* dbus/dbus-connection.c (dbus_connection_dispatch): exit if
	exit_on_disconnect flag is set and we process the disconnected
	signal.
	(dbus_connection_set_exit_on_disconnect): new function

2003-09-21  Havoc Pennington  <hp@pobox.com>

	Get matching rules mostly working in the bus; only actually
	parsing the rule text remains. However, the client side of
	"signal connections" hasn't been started, this patch is only the
	bus side.

	* dbus/dispatch.c: fix for the matching rules changes

	* bus/driver.c (bus_driver_handle_remove_match)
	(bus_driver_handle_add_match): send an ack reply from these
	method calls

	* glib/dbus-gproxy.c (dbus_gproxy_begin_call): fix order of
	arguments, reported by Seth Nickell

	* bus/config-parser.c (append_rule_from_element): support
	eavesdrop=true|false attribute on policies so match rules
	can be prevented from snooping on the system bus.

	* bus/dbus-daemon-1.1.in: consistently use terminology "sender"
	and "destination" in attribute names; fix some docs bugs;
	add eavesdrop=true|false attribute

	* bus/driver.c (bus_driver_handle_add_match)
	(bus_driver_handle_remove_match): handle AddMatch, RemoveMatch
	messages

	* dbus/dbus-protocol.h (DBUS_SERVICE_ORG_FREEDESKTOP_BROADCAST): get
	rid of broadcast service concept, signals are just always broadcast

	* bus/signals.c, bus/dispatch.c, bus/connection.c, bus/bus.c:
	mostly implement matching rules stuff (currently only exposed as signal
	connections)

2003-09-21  Mark McLoughlin  <mark@skynet.ie>

	* doc/dbus-specification.sgml: Change the header field name
	to be an enum and update the rest of the spec to reference
	the fields using the conventinal name.

	* dbus/dbus-protocol.h: update to reflect the spec.

	* doc/TODO: add item to remove the 4 byte alignment requirement.

	* dbus/dbus-message.c: Remove the code to generalise the
	header/body length and serial number header fields as named
	header fields so we can reference field names using the
	protocol values.
	(append_int_field), (append_uint_field), (append_string_field):
	Append the field name as a byte rather than four chars.
	(delete_int_or_uint_field), (delete_string_field): reflect the
	fact that the field name and typecode now occupy 4 bytes instead
	of 8.
	(decode_string_field), (decode_header_data): update to reflect
	protocol changes and move the field specific encoding from
	decode_string_field() back into decode_header_data().

	* dbus/dbus-internals.[ch]: (_dbus_header_field_to_string):
	Add utility to aid debugging.

	* dbus/dbus-message-builder.c:
	(append_string_field), (_dbus_message_data_load): Update to
	reflect protocol changes; Change the FIELD_NAME directive
	to HEADER_FIELD and allow it to take the field's conventional
	name rather than the actual value.

	* test/data/*/*.message: Update to use HEADER_FIELD instead
	of FIELD_NAME; Always align the header on an 8 byte boundary
	*before* updating the header length.

2003-09-15  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-pending-call.c: add the get/set object data
	boilerplate as for DBusConnection, etc. Use generic object data
	for the notify callback.

	* glib/dbus-gparser.c (parse_node): parse child nodes

	* tools/dbus-viewer.c: more hacking on the dbus-viewer

	* glib/dbus-gutils.c (_dbus_gutils_split_path): add a file to
	contain functions shared between the convenience lib and the
	installed lib

	* glib/Makefile.am (libdbus_glib_1_la_LDFLAGS): add
	-export-symbols-regex to the GLib library

	* dbus/dbus-object-tree.c (_dbus_object_tree_dispatch_and_unlock):
	fix the locking in here, and add a default handler for
	Introspect() that just returns sub-nodes.

2003-09-14  Havoc Pennington  <hp@pobox.com>

	* glib/dbus-gthread.c (dbus_g_thread_init): rename to make g_foo
	rather than gfoo consistent

	* glib/dbus-gproxy.h: delete for now, move contents to
	dbus-glib.h, because the include files don't work right since we
	aren't in the dbus/ subdir.

	* glib/dbus-gproxy.c (dbus_gproxy_send): finish implementing
	(dbus_gproxy_end_call): finish
	(dbus_gproxy_begin_call): finish

	* glib/dbus-gmain.c (dbus_set_g_error): new

	* glib/dbus-gobject.c (handle_introspect): include information
	about child nodes in the introspection

	* dbus/dbus-connection.c (dbus_connection_list_registered): new
	function to help in implementation of introspection

	* dbus/dbus-object-tree.c
	(_dbus_object_tree_list_registered_and_unlock): new function

2003-09-12  Havoc Pennington  <hp@pobox.com>

	* glib/dbus-gidl.h: add common base class for all the foo_info
	types

        * tools/dbus-viewer.c: add GTK-based introspection UI thingy
	similar to kdcop

	* test/Makefile.am: try test srcdir -ef . in addition to test
	srcdir = ., one of them should work (yeah lame)

        * glib/Makefile.am: build the "idl" parser stuff as a convenience
	library

	* glib/dbus-gparser.h: make description_load routines return
	NodeInfo* not Parser*

	* Makefile.am (SUBDIRS): build test dir after all library dirs

	* configure.in: add GTK+ detection

2003-09-07  Havoc Pennington  <hp@pobox.com>

	* Make Doxygen contented.

2003-09-07  Havoc Pennington  <hp@pobox.com>

	* doc/dbus-specification.sgml: more updates

2003-09-06  Havoc Pennington  <hp@pobox.com>

	* doc/dbus-specification.sgml: partial updates

	* bus/dbus-daemon-1.1.in: fix the config file docs for the
	zillionth time; hopefully I edited the right file this time.

	* bus/config-parser.c (append_rule_from_element): support
	send_type, send_path, receive_type, receive_path

	* bus/policy.c: add message type and path to the list of things
	that can be "firewalled"

2003-09-06  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-connection.c (dbus_connection_register_fallback): add this
	(dbus_connection_register_object_path): make this not handle
	messages to paths below the given path

2003-09-03  Havoc Pennington  <hp@pobox.com>

	* test/glib/Makefile.am: add this with random glib-linked test
	programs

	* glib/Makefile.am: remove the random test programs from here,
	leave only the unit tests

	* glib/dbus-gobject.c (_dbus_gobject_test): add test for
	uscore/javacaps conversion, and fix
	(get_object_property, set_object_property): change to .NET
	convention for mapping props to methods, set_FooBar/get_FooBar,
	since one language has such a convention we may as well copy it.
	Plus real methods in either getFooBar or get_foo_bar style won't
	collide with this convention.

2003-09-01  Havoc Pennington  <hp@pobox.com>

	* glib/dbus-gparser.c: implement

	* glib/dbus-gobject.c: start implementing skeletons support

	* configure.in: when disabling checks/assert, also define
	G_DISABLE_ASSERT and G_DISABLE_CHECKS

2003-09-01  Havoc Pennington  <hp@pobox.com>

	* glib/Makefile.am: rearrange a bunch of files and get "make
	check" framework set up

2003-08-31  Havoc Pennington  <hp@pobox.com>

	* fix build with --disable-tests

2003-08-30  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-connection.c: purge DBusMessageHandler

	* dbus/dbus-message-handler.c: remove DBusMessageHandler, just
	use callbacks everywhere

2003-08-30  Havoc Pennington  <hp@pobox.com>

	* test/data/valid-config-files/system.d/test.conf: change to
	root for the user so warnings don't get printed

	* dbus/dbus-message.c: add dbus_message_get_path,
	dbus_message_set_path

	* dbus/dbus-object-tree.c (do_test_dispatch): add test of
	dispatching to a path

	* dbus/dbus-string.c (_dbus_string_validate_path): add

	* dbus/dbus-marshal.c (_dbus_demarshal_object_path): implement
	(_dbus_marshal_object_path): implement

	* dbus/dbus-protocol.h (DBUS_HEADER_FIELD_PATH): new header field
	to contain the path to the target object
	(DBUS_HEADER_FIELD_SENDER_SERVICE): rename
	DBUS_HEADER_FIELD_SENDER to explicitly say it's the sender service

2003-08-30  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object-tree.c: write tests and fix the discovered bugs

2003-08-29  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object-tree.c: modify to allow overlapping paths to be
	registered
	(struct DBusObjectSubtree): shrink this
	a lot, since we may have a lot of them
	(_dbus_object_tree_free_all_unlocked): implement
	(_dbus_object_tree_dispatch_and_unlock): implement

2003-08-29  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-internals.h: fix _DBUS_N_GLOBAL_LOCKS

2003-08-28  Havoc Pennington  <hp@pobox.com>

	purge DBusObjectID

	* dbus/dbus-connection.c: port to no ObjectID, create a
	DBusObjectTree, rename ObjectTree to ObjectPath in public API

	* dbus/dbus-connection.h (struct DBusObjectTreeVTable): delete
	everything except UnregisterFunction and MessageFunction

	* dbus/dbus-marshal.c: port away from DBusObjectID,
	add DBUS_TYPE_OBJECT_PATH

	* dbus/dbus-object-registry.[hc], dbus/dbus-object.[hc],
	dbus/dbus-objectid.[hc]: remove these, we are moving to
	path-based object IDs

2003-08-25  Havoc Pennington  <hp@pobox.com>

        Just noticed that dbus_message_test is hosed, I wonder when I
	broke that. I thought make check was passing earlier...

	* dbus/dbus-object-tree.c: add new "object tree" to match DCOP
	container tree, will replace most of dbus-object-registry

	* dbus/dbus-string.c (_dbus_string_append_printf_valist): fix C99
	screwup

2003-08-19  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-message.c (decode_string_field): support FIELD_SENDER
	(dbus_message_is_error): fix this function

	* bus/dbus-daemon-1.1: clarify logic on when <deny>/<allow> rules
	match

	* bus/policy.c (bus_client_policy_check_can_receive): fix code to
	reflect clarified man page
	(bus_client_policy_check_can_send): ditto

	* bus/session.conf.in: fixup

	* bus/system.conf.in: fixup

2003-08-18  Havoc Pennington  <hp@redhat.com>

	* dbus/dbus-hash.c (_dbus_hash_table_insert_two_strings): fix

	* dbus/dbus-message.c (_dbus_message_loader_queue_messages): fix
	dumb bug created earlier (wrong order of args to
	decode_header_data())

	* tools/dbus-send.c: port

	* tools/dbus-print-message.c (print_message): port

        * test/data/*messages: port all messages over

        * dbus/dbus-message-builder.c: support including
	message type

        * bus/driver.c: port over

	* bus/dispatch.c: port over to new stuff

	* dbus/dbus-connection.c (_dbus_connection_new_for_transport):
	rename disconnect signal to "Disconnected"

2003-08-17  Havoc Pennington  <hp@pobox.com>

	This doesn't compile yet, but syncing up so I can hack on it from
	work. What are branches for if not broken code? ;-)

	* dbus/dbus-protocol.h: remove DBUS_HEADER_FIELD_NAME, add
	DBUS_HEADER_FIELD_INTERFACE, DBUS_HEADER_FIELD_MEMBER,
	DBUS_HEADER_FIELD_ERROR_NAME

	* dbus/dbus-hash.c: Introduce DBUS_HASH_TWO_STRINGS as hack to use
	for the interface+member pairs
	(string_hash): change to use g_str_hash algorithm
	(find_direct_function, find_string_function): refactor these to
	share most code.

	* dbus/dbus-message.c: port all of this over to support
	interface/member fields instead of name field

	* dbus/dbus-object-registry.c: port over

	* dbus/dbus-string.c (_dbus_string_validate_interface): rename
	from _dbus_string_validate_name

	* bus/dbus-daemon-1.1: change file format for the
	<deny>/<allow> stuff to match new message naming scheme

	* bus/policy.c: port over

	* bus/config-parser.c: parse new format

2003-08-16  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object-registry.c (add_and_remove_objects): remove
	broken assertion

	* glib/dbus-gproxy.c: some hacking

2003-08-15  Havoc Pennington  <hp@redhat.com>

	* dbus/dbus-pending-call.c (dbus_pending_call_block): implement

	* dbus/dbus-connection.c
	(dbus_connection_send_with_reply_and_block): factor out internals;
	change to convert any error replies to DBusError instead of
	returning them as a message

2003-08-15  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-connection.c,
	dbus/dbus-pending-call.c: Finish the pending call stuff

2003-08-14  Havoc Pennington  <hp@redhat.com>

	* dbus/dbus-pending-call.c: start on new object that will replace
	DBusMessageHandler and ReplyHandlerData for tracking outstanding
	replies

	* dbus/dbus-gproxy.c: start on proxy object used to communicate
	with remote interfaces

	* dbus/dbus-gidl.c: do the boring boilerplate in here

2003-08-12  Havoc Pennington  <hp@pobox.com>

	* bus/dispatch.c (bus_dispatch): make this return proper
	DBusHandlerResult to avoid DBUS_ERROR_UNKNOWN_METHOD

	* dbus/dbus-errors.c (dbus_set_error): use
	_dbus_string_append_printf_valist

	* dbus/dbus-string.c (_dbus_string_append_printf_valist)
	(_dbus_string_append_printf): new

	* dbus/dbus-errors.h (DBUS_ERROR_UNKNOWN_MESSAGE): change to
	UNKNOWN_METHOD

	* dbus/dbus-connection.c (dbus_connection_dispatch): handle
	DBUS_HANDLER_RESULT_NEED_MEMORY; send default error reply if a
	message is unhandled.

2003-08-11  Havoc Pennington  <hp@pobox.com>

	* bus/test.c (client_disconnect_handler): change to return
	HANDLED (would have been REMOVE_MESSAGE)

	* dbus/dbus-object.h (enum DBusHandlerResult): rename to
	HANDLED/NOT_YET_HANDLED instead of
	REMOVE_MESSAGE/ALLOW_MORE_HANDLERS to make it clearer how it
	should be used.

2003-08-10  Havoc Pennington  <hp@pobox.com>

	* tools/dbus-send.c (main): add --type argument, for now
	supporting only method_call and signal types.

	* tools/dbus-print-message.c: print message type

	* dbus/dbus-connection.c (_dbus_connection_new_for_transport):
	init connection->objects

	* doc/dbus-specification.sgml: fix sgml

	* bus/*.c: port over to object-instance API changes

	* test/test-service.c: ditto

	* dbus/dbus-message.c (dbus_message_create_header): allow #NULL
	name, we will have to fix up the rest of the code to also handle
	this
	(dbus_message_new): generic message-creation call
	(set_string_field): allow appending name field

2003-08-06  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object-registry.c: implement signal connection
	and dispatch

	* dbus/dbus-connection.c (_dbus_connection_unref_unlocked): new

	* dbus/dbus-internals.c (_dbus_memdup): new function

2003-08-02  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-message.c (dbus_message_get_no_reply)
	(dbus_message_set_no_reply): add these and remove
	set_is_error/get_is_error

	* dbus/dbus-protocol.h, doc/dbus-specification.sgml:
	remove the ERROR flag, since there's now an ERROR type

2003-08-01  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object-registry.c (_dbus_object_registry_handle_and_unlock):
	implement

	* dbus/dbus-message.c (dbus_message_get_type): new function

	* doc/dbus-specification.sgml: add "type" byte to messages

2003-08-01  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-protocol.h (DBUS_MESSAGE_TYPE_*): introduce
	a message type enum to distinguish kinds of message
	(DBUS_HEADER_FLAG_NO_REPLY_EXPECTED): flag for a message
	that need not be replied to

2003-08-01  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-marshal.c: adapt to DBusObjectID changes
	(unpack_8_octets): fix no-64-bit-int bug

	* dbus/dbus-object-registry.c (validate_id): validate the
	connection ID bits, not just the instance ID.

	* dbus/dbus-connection.c (_dbus_connection_init_id): initialize
	the connection-global 33 bits of the object ID

	* dbus/dbus-object-registry.c (info_from_entry): fill in
	object ID in the new way

	* dbus/dbus-objectid.h: rather than high/low bits, specifically
	define server/client/instance bits.

2003-07-30  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-connection.c (dbus_connection_register_object): fix
	build

2003-07-13  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object.h (struct DBusObjectVTable): add padding
	fields to DBusObjectVTable and DBusObjectInfo

2003-07-12  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object-registry.c: implement unit test,
	fix bugs discovered in process

	* dbus/dbus-connection.c: remove handler_table and
	register_handler(), add DBusObjectRegistry usage

	* dbus/dbus-objectid.c (dbus_object_id_is_null)
	(dbus_object_id_set_null): new functions

2003-07-08  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object.c: implement some of this

	* dbus/dbus-object-registry.c
	(_dbus_object_registry_add_and_unlock): fill in the object_id out
	param
	(_dbus_object_registry_new): handle OOM

2003-07-08  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-object.h: sketch out an API for registering objects
	with a connection, that allows us to use as little as 24 bytes
	per object and lets application code represent an object in
	any conceivable way.

	* dbus/dbus-object-registry.c: implement the hard bits of the
	DBusConnection aspect of object API. Not yet wired up.

2003-07-06  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-marshal.c (_dbus_marshal_set_object_id): new function
	(_dbus_marshal_object_id): new
	(_dbus_demarshal_object_id): new
	(_dbus_marshal_get_arg_end_pos): support object ID type, and
	consolidate identical switch cases. Don't conditionalize handling
	of DBUS_TYPE_UINT64, need to handle the type always.
	(_dbus_marshal_validate_arg): consolidate identical cases, and
	handle DBUS_TYPE_OBJECT_ID

	* dbus/dbus-objectid.c: new file with DBusObjectID data type.

	* dbus/dbus-protocol.h: add DBUS_TYPE_OBJECT_ID

2003-09-28  Havoc Pennington  <hp@pobox.com>

	* real 0.13 release

2003-09-28  Havoc Pennington  <hp@pobox.com>

	* doc/Makefile.am (dbus-specification.html): testing a funky hack
	to work with Debian db2html

2003-09-28  Havoc Pennington  <hp@pobox.com>

	* configure.in: 0.13

	* doc/Makefile.am (dbus-test-plan.html): accept nonexistence of
	stylesheet-images for benefit of Debian

	Change back to using filesystem-linked sockets for the system
	bus, so only root can create the default system bus address.

	* bus/system.conf.in: change to use
	DBUS_SYSTEM_BUS_DEFAULT_ADDRESS

	* dbus/Makefile.am (INCLUDES): remove DBUS_SYSTEM_BUS_PATH define
	from here.

	* configure.in: define DBUS_SYSTEM_BUS_DEFAULT_ADDRESS
	here, and AC_DEFINE DBUS_SYSTEM_PATH

2003-08-09  Anders Carlsson  <andersca@codefactory.se>

	* doc/TODO:
	* doc/busconfig.dtd:
	Add busconfig DTD.

2003-08-09  Anders Carlsson  <andersca@codefactory.se>

	* doc/dbus-specification.sgml:
	Add activation reply values.

2003-08-05  Havoc Pennington  <hp@redhat.com>

	* configure.in: 0.12

2003-08-05  Anders Carlsson  <andersca@codefactory.se>

	* glib/dbus-gmain.c: (watch_fd_new), (watch_fd_ref),
	(watch_fd_unref), (dbus_gsource_check), (dbus_gsource_dispatch),
	(add_watch), (remove_watch), (create_source):
	Refcount fds, fixes some reentrancy issues.

2003-07-30  Havoc Pennington  <hp@redhat.com>

	* dbus/dbus-bus.c (init_connections_unlocked): fix default system
	bus address to be abstract if we have abstract sockets

	* NEWS: update

2003-07-28  Havoc Pennington  <hp@redhat.com>

	* bus/messagebus.in: fix to avoid processname/servicename
	confusion, from Michael Kearey
	https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=100965

2003-07-23  Havoc Pennington  <hp@pobox.com>

	* dbus/dbus-message.c (dbus_message_iter_get_named):
	fix from Andy Hanton to remove broken "+1"

2003-07-16  Havoc Pennington  <hp@pobox.com>

	* tools/dbus-launch.c (babysit): close stdout/stderr in the
	babysitter process, as suggested by Thomas Leonard, so
	an "eval `dbus-launch --exit-with-session`" will actually
	return

2003-07-16  Havoc Pennington  <hp@pobox.com>

	* configure.in: print out EXPANDED_* variables in the summary at
	the end; clean up the code that computes EXPANDED_ variables and
	get the ones using exec_prefix right. Should make things work
	when you build without --prefix

2 files changed, 427 insertions, 227 deletions

diff --git a/doc/TODO b/doc/TODO
index 0e56e1e7..120d1eba 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -23,9 +23,6 @@
    (changing get_string to have an error return, and allowing a type error 
    as a possible return)
 
- - We might consider returning a "no such operation" error in dbus-connection.c 
-   for unhandled messages.
-
  - The convenience functions in dbus-bus.h should perhaps have
    the signatures that they would have if they were autogenerated
    stubs. e.g. the acquire service function. We should also evaluate 
@@ -69,3 +66,30 @@
    files; they have to be in the toplevel file. when loading 
    a child file, we could just init its DBusLimits from the parent, 
    then after parsing copy its DBusLimits back to the parent
+
+ - when making a method call, if the call serial were globally unique,
+   we could forward the call serial along with any method calls made
+   as a result of the first method call, and allow reentrancy that was
+   strictly part of the call stack of said method call. But I don't
+   really see how to do this without making the user pass around the
+   call serial to all method calls all the time, or disallowing 
+   async calls.
+
+ - the invalid messages in the test suite are all useless because 
+   they are invalid for the wrong reasons due to protocol changes
+
+ - I don't want to introduce DBusObject, but refcounting and object
+   data could still be factored out into an internal "base class" 
+   perhaps.
+
+ - modify the auth protocol to also support other initial-handshake
+   type of information
+
+ - document the auth protocol as a set of states and transitions, and
+   then reimplement it in those terms
+
+ - dbus_gproxy or dbus_g_proxy?
+
+ - add dbus_message_has_path(), maybe has_member/interface
+
+ - The OBJECT_PATH type is not documented in the spec.
diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml
index 4ab5291a..696c3f45 100644
--- a/doc/dbus-specification.sgml
+++ b/doc/dbus-specification.sgml
@@ -3,8 +3,8 @@
 <article id="index">
   <artheader>
     <title>D-BUS Specification</title>
-    <releaseinfo>Version 0.7</releaseinfo>
-    <date>26 March 2003</date>
+    <releaseinfo>Version 0.8</releaseinfo>
+    <date>06 September 2003</date>
     <authorgroup>
       <author>
 	<firstname>Havoc</firstname>
@@ -65,10 +65,10 @@
           <para>
             D-BUS is <emphasis>easy to use</emphasis> because it works in terms
             of <firstterm>messages</firstterm> rather than byte streams, and
-            does not require users to understand any complex concepts such as a
-            new type system or elaborate APIs. Libraries implementing D-BUS 
-            may choose to abstract messages as "method calls" (see 
-            <xref linkend="message-conventions-method">).
+            automatically handles a lot of the hard IPC issues. Also, the D-BUS
+            library is designed to be wrapped in a way that lets developers use
+            their framework's existing object/type system, rather than learning
+            a new one specifically for IPC.
           </para>
         </listitem>
       </itemizedlist>
@@ -83,11 +83,10 @@
       forwards messages among them.
     </para>
     <para>
-      Things that D-BUS can be used for is for example notification of
-      system changes (notification of when a camera is plugged in to a
-      computer, or a new version of some software has been installed),
-      or desktop interoperablity, for example a file monitoring
-      service or a configuration service.
+      Uses of D-BUS include notification of system changes (notification of when
+      a camera is plugged in to a computer, or a new version of some software
+      has been installed), or desktop interoperablity, for example a file
+      monitoring service or a configuration service.
     </para>
   </sect1>
 
@@ -135,6 +134,12 @@
               </row>
               <row>
                 <entry>1 byte</entry>
+                <entry>Type of message. Unknown types MUST be ignored. 
+                  Currently-defined types are described below.
+                </entry>
+              </row>
+              <row>
+                <entry>1 byte</entry>
                 <entry>Bitwise OR of flags. Unknown flags
                   MUST be ignored. Currently-defined flags are described below.
                 </entry>
@@ -149,12 +154,6 @@
                 </entry>
               </row>
               <row>
-                <entry>1 byte</entry>
-                <entry>A nul byte, reserved for future use.
-                  Any value for this byte MUST be accepted.
-                </entry>
-              </row>
-              <row>
                 <entry>4 bytes</entry>
                 <entry>An unsigned 32-bit integer in the
                   message's byte order, indicating the total length in bytes of
@@ -172,9 +171,11 @@
               <row>
                 <entry>4 bytes</entry>
                 <entry>The message's serial number, an unsigned 32-bit integer in
-                  the message's byte order. Applications MUST NOT reuse the same
-                  serial number for different messages more often than 32-bit
-                  unsigned integer wraparound. Zero is not a valid serial number.
+                  the message's byte order. The serial number is a cookie used to 
+                  identify message replies; thus all outstanding unreplied-to messages 
+                  from the same connection MUST have a different serial number.
+                  Zero is not a valid serial number, but all other numbers are 
+                  allowed.
                 </entry>
               </row>
             </tbody>
@@ -182,19 +183,67 @@
         </informaltable>
       </para>
       <para>
-        Flags that can appear in the second byte of the header:
+        Types that can appear in the second byte of the header:
         <informaltable>
-          <tgroup cols=2>
+          <tgroup cols=3>
+            <thead>
+              <row>
+                <entry>Conventional name</entry>
+                <entry>Decimal value</entry>
+                <entry>Description</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>INVALID</entry>
+                <entry>0</entry>
+                <entry>This is an invalid type, if seen in a message 
+                  the connection should be dropped immediately.</entry>
+              </row>
+              <row>
+                <entry>METHOD_CALL</entry>
+                <entry>1</entry>
+                <entry>Method call.</entry>
+              </row>
+              <row>
+                <entry>METHOD_RETURN</entry>
+                <entry>2</entry>
+                <entry>Method reply with returned data.</entry>
+              </row>
+              <row>
+                <entry>ERROR</entry>
+                <entry>3</entry>
+                <entry>Error reply. If the first argument exists and is a
+                string, it is an error message.</entry>
+              </row>
+              <row>
+                <entry>SIGNAL</entry>
+                <entry>4</entry>
+                <entry>Signal emission.</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+      </para>
+      <para>
+        Flags that can appear in the third byte of the header:
+        <informaltable>
+          <tgroup cols=3>
             <thead>
               <row>
+                <entry>Conventional name</entry>
                 <entry>Hex value</entry>
                 <entry>Description</entry>
               </row>
             </thead>
             <tbody>
               <row>
+                <entry>NO_REPLY_EXPECTED</entry>
                 <entry>0x1</entry>
-                <entry>This message is an error reply. If the first argument exists and is a string, it is an error message.</entry>
+                <entry>This message does not expect method return replies or
+                error replies; the reply can be omitted as an
+                optimization. However, it is compliant with this specification
+                to return the reply despite this flag.</entry>
               </row>
             </tbody>
           </tgroup>
@@ -208,22 +257,21 @@
         In addition to the required header information mentioned 
         in <xref linkend="message-protocol-header-encoding">, 
           the header may contain zero or more named 
-          header fields. These fields are named to allow 
-          future versions of this protocol specification to 
-          add new fields; implementations must ignore fields 
-          they do not understand. Implementations must not 
-          invent their own header fields; only changes to 
+          header fields. Future versions of this protocol
+          specification may add new fields. Implementations must
+          ignore fields they do not understand. Implementations
+          must not invent their own header fields; only changes to 
           this specification may introduce new header fields.
       </para>
 
       <para>
-        Header field names MUST consist of 4 non-nul bytes.  The field name is
-        NOT nul terminated; it occupies exactly 4 bytes. Following the name, the
-        field MUST have a type code represented as a single unsigned byte, and
-        then a properly-aligned value of that type.  See <xref
-        linkend="message-protocol-arguments"> for a description of how each type
-        is encoded. If an implementation sees a header field name that it does
-        not understand, it MUST ignore that field.
+        Header field names MUST consist of a single byte, possible values
+        of which are defined below. Following the name, the field MUST have
+        a type code represented as a single unsigned byte, and then a
+        properly-aligned value of that type.  See <xref
+        linkend="message-protocol-arguments"> for a description of how each
+        type is encoded. If an implementation sees a header field name that
+        it does not understand, it MUST ignore that field.
       </para>
 
       <para>
@@ -232,36 +280,68 @@
           <tgroup cols=3>
             <thead>
               <row>
-                <entry>Name</entry>
+                <entry>Conventional Name</entry>
+		<entry>Decimal Value</entry>
                 <entry>Type</entry>
                 <entry>Description</entry>
               </row>
             </thead>
             <tbody>
               <row>
-                <entry>name</entry>
+                <entry>INVALID</entry>
+		<entry>0</entry>
+                <entry>INVALID</entry>
+                <entry>Not a valid field name (error if it appears in a message)</entry>
+              </row>
+              <row>
+                <entry>PATH</entry>
+		<entry>1</entry>
+                <entry>STRING</entry>
+                <entry>The object to send the message to; objects are identified by 
+                a path, "/foo/bar"</entry>
+              </row>
+              <row>
+                <entry>INTERFACE</entry>
+		<entry>2</entry>
+                <entry>STRING</entry>
+                <entry>The interface to invoke a method call on, or 
+                that a signal is emitted from. e.g. "org.freedesktop.Introspectable"</entry>
+              </row>
+              <row>
+                <entry>MEMBER</entry>
+		<entry>3</entry>
+                <entry>STRING</entry>
+                <entry>The member, either the method name or signal name. 
+                e.g. "Frobate"</entry>
+              </row>
+              <row>
+                <entry>ERROR_NAME</entry>
+		<entry>4</entry>
                 <entry>STRING</entry>
-                <entry>The name of the message, such as org.freedesktop.Peer.Ping</entry>
+                <entry>The name of the error that occurred, for errors</entry>
               </row>
               <row>
-                <entry>rply</entry>
+                <entry>REPLY_SERIAL</entry>
+		<entry>5</entry>
                 <entry>UINT32</entry>
                 <entry>The serial number of the message this message is a reply
                 to. (The serial number is one of the mandatory header fields,
                 see <xref linkend="message-protocol-header-encoding">.)</entry>
               </row>
               <row>
-                <entry>srvc</entry>
+                <entry>SERVICE</entry>
+		<entry>6</entry>
                 <entry>STRING</entry>
                 <entry>The name of the service this message should be routed to. 
                 Only used in combination with the message bus, see 
                 <xref linkend="message-bus">.</entry>
               </row>
               <row>
-                <entry>sndr</entry>
+                <entry>SENDER_SERVICE</entry>
+		<entry>7</entry>
                 <entry>STRING</entry>
-                <entry>The name of the base service that sent this message. 
-                The message bus fills in this field; the field is 
+                <entry>Sender service. The name of the base service that sent
+                this message.  The message bus fills in this field; the field is
                 only meaningful in combination with the message bus.</entry>
               </row>
             </tbody>
@@ -277,10 +357,9 @@
         buffer while keeping data types aligned, the total length of the header
         must be a multiple of 8 bytes.  To achieve this, the header MUST be padded
         with nul bytes to align its total length on an 8-byte boundary. 
-        The minimum number of padding bytes MUST be used. Because all possible 
-        named fields use at least 8 bytes, implementations can distinguish 
-        padding (which must be less than 8 bytes) from additional named fields
-        (which must be at least 8 bytes).
+        The minimum number of padding bytes MUST be used. Because zero is an
+        invalid field name, implementations can distinguish padding (which must be
+        zero initialized) from additional named fields.
       </para>
     </sect2>
 
@@ -440,19 +519,228 @@
     <sect2 id="message-protocol-names">
       <title>Valid names</title>
       <para>
-        Messages and services have names with type STRING, meaning that 
-        they must be valid UTF-8. However, there are also some 
-        additional restrictions that apply to message and service names 
-        specifically:
-        <itemizedlist>
-	  <listitem><para>They must contain at least one '.' (period) character</para></listitem>
-	  <listitem><para>They must not begin with a '.' (period) character</para></listitem>
-	  <listitem><para>They must not exceed 256 bytes in length</para></listitem>
-	  <listitem><para>They must be at least 1 byte in length</para></listitem>
-        </itemizedlist>
-        As a special exception, base service names (those beginning with a colon (':') character)
-        need not contain a period.
+        The various header fields of type STRING have some restrictions 
+        on the string's format.
+      </para>
+      <sect3 id="message-protocol-names-service">
+        <title>Service names</title>
+        <para>
+          Services have names with type STRING, meaning that 
+          they must be valid UTF-8. However, there are also some 
+          additional restrictions that apply to service names 
+          specifically:
+          <itemizedlist>
+	    <listitem><para>They must contain at least one '.' (period) character</para></listitem>
+	    <listitem><para>They must not begin with a '.' (period) character</para></listitem>
+	    <listitem><para>They must not exceed 256 bytes in length</para></listitem>
+	    <listitem><para>They must be at least 1 byte in length</para></listitem>
+          </itemizedlist>
+          
+          As a special exception, base service names (those beginning with a colon
+          (':') character) need not contain a period.
+        </para>
+        <para>
+          FIXME really, shouldn't we ban basically everything non-alphanumeric 
+          so the name will work in all programming languages?
+        </para>
+      </sect3>
+      <sect3 id="message-protocol-names-interface">
+        <title>Interface names</title>
+        <para>
+          Interface names have the same restrictions as service names, 
+          but do not have the special exception for names beginning with 
+          a colon.
+        </para>
+        <para>
+          FIXME really, shouldn't we ban basically everything non-alphanumeric 
+          so the name will work in all programming languages?
+        </para>
+      </sect3>
+      <sect3 id="message-protocol-names-method">
+        <title>Method names</title>
+        <para>
+          Method names:
+          <itemizedlist>
+	    <listitem><para>May not contain the '.' (period) character</para></listitem>
+	    <listitem><para>Must not exceed 256 bytes in length</para></listitem>
+	    <listitem><para>Must be at least 1 byte in length</para></listitem>
+          </itemizedlist>
+        </para>
+        <para>
+          FIXME really, shouldn't we ban basically everything non-alphanumeric 
+          so the name will work in all programming languages?
+        </para>
+      </sect3>
+      <sect3 id="message-protocol-names-path">
+        <title>Path names</title>
+        <para>
+          A path must begin with an ASCII '/' (slash) character. Paths may not
+          end with a slash character unless the path is the one-byte string
+          "/". Two slash characters may not appear adjacent to one another (the
+          empty string is not a valid "subdirectory"). Paths may not exceed
+          256 bytes in length.
+        </para>
+      </sect3>
+      <sect3 id="message-protocol-names-error">
+        <title>Error names</title>
+        <para>
+          Error names have the same restrictions as interface names.
+        </para>
+        <para>
+          FIXME really, shouldn't we ban basically everything non-alphanumeric 
+          so the name will work in all programming languages?
+        </para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="message-protocol-types">
+      <title>Message types</title>
+      <para>
+        Each of the message types (METHOD_CALL, METHOD_RETURN, ERROR, and
+        SIGNAL) has its own expected usage conventions and header fields.
       </para>
+      <sect3 id="message-protocol-types-method">
+        <title>Method Calls, Returns, and Errors</title>
+        <para>
+          Some messages invoke an operation on a remote object.  These are
+          called method call messages and have the type tag METHOD_CALL. Such
+          messages map naturally to methods on objects in a typical program.
+        </para>
+        <para>
+          A method call message is expected to have a MEMBER header field
+          indicating the name of the method. Optionally, the message has an
+          INTERFACE field giving the interface the method is a part of. In the
+          absence of an INTERFACE field, if two interfaces on the same object have
+          a method with the same name, it is undefined which of the two methods
+          will be invoked. Implementations may also choose to return an error in
+          this ambiguous case. However, if a method name is unique
+          implementations should not require an interface field.
+        </para>
+        <para>
+          Method call messages also include a PATH field indicating the 
+          object to invoke the method on. If the call is passing through 
+          a message bus, the message will also have a SERVICE field giving 
+          the service to receive the message.
+        </para>
+        <para>
+          When an application handles a method call message, it is expected to
+          return a reply. The reply is identified by a REPLY_SERIAL header field
+          indicating the serial number of the METHOD_CALL being replied to. The
+          reply can have one of two types; either METHOD_RETURN or ERROR.
+        </para>
+        <para>
+          If the reply has type METHOD_RETURN, the arguments to the reply message 
+          are the return value(s) or "out parameters" of the method call. 
+          If the reply has type ERROR, then an "exception" has been thrown, 
+          and the call fails; no return value will be provided. It makes 
+          no sense to send multiple replies to the same method call.
+        </para>
+        <para>
+          Even if a method call has no return values, a METHOD_RETURN 
+          reply is expected, so the caller will know the method 
+          was successfully processed.
+        </para>
+        <para>
+          If a METHOD_CALL message has the flag NO_REPLY_EXPECTED, 
+          then as an optimization the application receiving the method 
+          call may choose to omit the reply message (regardless of 
+          whether the reply would have been METHOD_RETURN or ERROR). 
+          However, it is also acceptable to ignore the NO_REPLY_EXPECTED
+          flag and reply anyway.
+        </para>
+        <sect4 id="message-protocol-types-method-apis">
+          <title>Mapping method calls to native APIs</title>
+          <para>
+            APIs for D-BUS may map method calls to a method call in a specific
+            programming language, such as C++, or may map a method call written
+            in an IDL to a D-BUS message.
+          </para>
+          <para>
+            In APIs of this nature, arguments to a method are often termed "in"
+            (which implies sent in the METHOD_CALL), or "out" (which implies
+            returned in the METHOD_RETURN). Some APIs such as CORBA also have
+            "inout" arguments, which are both sent and received, i.e. the caller
+            passes in a value which is modified. Mapped to D-BUS, an "inout"
+            argument is equivalent to an "in" argument, followed by an "out"
+            argument. You can't pass things "by reference" over the wire, so
+            "inout" is purely an illusion of the in-process API.
+          </para>
+          <para>
+            Given a method with zero or one return values, followed by zero or more
+            arguments, where each argument may be "in", "out", or "inout", the
+            caller constructs a message by appending each "in" or "inout" argument,
+            in order. "out" arguments are not represented in the caller's message.
+          </para>
+          <para>
+            The recipient constructs a reply by appending first the return value 
+            if any, then each "out" or "inout" argument, in order. 
+            "in" arguments are not represented in the reply message.
+          </para>
+        </sect4>
+
+      </sect3>
+
+      <sect3 id="message-protocol-types-signal">
+        <title>Signal Emission</title>
+        <para>
+          Unlike method calls, signal emissions have no replies. 
+          A signal emission is simply a single message of type SIGNAL.
+          It must have three header fields: PATH giving the object 
+          the signal was emitted from, plus INTERFACE and MEMBER giving
+          the fully-qualified name of the signal.
+        </para>
+      </sect3>
+
+      <sect3 id="message-protocol-types-notation">
+        <title>Notation in this document</title>
+        <para>
+          This document uses a simple pseudo-IDL to describe particular method 
+          calls and signals. Here is an example of a method call:
+          <programlisting>
+            org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags,
+                                                  out UINT32 resultcode)
+          </programlisting>
+          This means INTERFACE = org.freedesktop.DBus, MEMBER = ActivateService, 
+          METHOD_CALL arguments are STRING and UINT32, METHOD_RETURN argument
+          is UINT32. Remember that the MEMBER field can't contain any '.' (period)
+          characters so it's known that the last part of the name in
+          the "IDL" is the member name.
+        </para>
+        <para>
+          In C++ that might end up looking like this:
+          <programlisting>
+            unsigned int org::freedesktop::DBus::ActivateService (const char  *service_name, 
+                                                                  unsigned int flags);
+          </programlisting>
+          or equally valid, the return value could be done as an argument:
+          <programlisting>
+            void org::freedesktop::DBus::ActivateService (const char   *service_name, 
+                                                          unsigned int  flags,
+                                                          unsigned int *resultcode);
+          </programlisting>
+          It's really up to the API designer how they want to make 
+          this look. You could design an API where the namespace wasn't used 
+          in C++, using STL or Qt, using varargs, or whatever you wanted.
+        </para>
+        <para>
+          Signals are written as follows:
+          <programlisting>
+            org.freedesktop.DBus.ServiceLost (STRING service_name)
+          </programlisting>
+          Signals don't specify "in" vs. "out" because only 
+          a single direction is possible.
+        </para>
+        <para>
+          In this ad hoc notation, the special type name ANY means any type
+          other than NIL, and the special type name ANY_OR_NIL means any valid
+          type.
+        </para>
+        <para>
+          It isn't especially encouraged to use this lame pseudo-IDL in actual
+          API implementations; you might use the native notation for the
+          language you're using, or you might use COM or CORBA IDL, for example.
+        </para>
+      </sect3>
     </sect2>
 
   </sect1>
@@ -730,6 +1018,13 @@
 	</figure>
       </para>
     </sect2>
+    <sect2 id="auth-states">
+      <title>Authentication state diagrams</title>
+      
+      <para>
+        WRITEME
+      </para>
+    </sect2>
     <sect2 id="auth-mechanisms">
       <title>Authentication mechanisms</title>
       <para>
@@ -905,161 +1200,35 @@
     </para>
   </sect1>
 
-  <sect1 id="message-conventions">
-    <title>Message Conventions</title>
-    <para>
-      This section documents conventions that are not essential to D-BUS
-      functionality, but should generally be followed in order to simplify
-      programmer's lives.
-    </para>
-    <sect2 id="message-conventions-naming">
-      <title>Message Naming</title>
-      <para>
-        Messages are normally named in the form 
-        "org.freedesktop.Peer.Ping", which has three 
-        distinct components:
-        <variablelist>
-          <varlistentry>
-            <term>Namespace e.g. <literal>org.freedesktop</literal></term>
-            <listitem>
-              <para>
-                Message names have a Java-style namespace: a reversed domain
-                name. The components of the domain are normally lowercase.
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term>Package or object e.g. <literal>Peer</literal></term>
-            <listitem>
-              <para>
-                The next part of the message name can be thought of as the name
-                of a singleton object, or as the name of a package of related
-                messages.  More than one dot-separated component might be used
-                here. (Note that D-BUS does not define any idea of object
-                instances or object references.)  The package or object name is
-                capitalized LikeThis.
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term>Method or operation e.g. <literal>Ping</literal></term>
-            <listitem>
-              <para>
-                The final part of the message name is the most specific, and
-                should be a verb indicating an operation to be performed on the
-                object.  The method or operation name is capitalized LikeThis.
-              </para>
-            </listitem>
-          </varlistentry>
-        </variablelist>
-      </para>
-      <para>
-        A reply to a message conventionally has the same name as the message
-        being replied to. When following method call conventions (see <xref
-                                                                         linkend="message-conventions-method">), this convention is mandatory, 
-          because a message with multiple possible replies can't be mapped
-          to method call semantics without special-case code.
-      </para>
-    </sect2>
-    <sect2 id="message-conventions-method">
-      <title>Method Call Mapping</title>
-      <para>
-        Some implementations of D-BUS may present an API that translates object
-        method calls into D-BUS messages. This document does not specify in
-        detail how such an API should look or work. However, it does specify how
-        message-based protocols should be designed to be friendly to such an
-        API.
-      </para>
-      <para>
-        Remember that D-BUS does not have object references or object instances.
-        So when one application sends the message
-        <literal>org.freedesktop.Peer.Ping</literal>, it sends it to another
-        application, not to any kind of sub-portion of that application.
-        However, a convenience API used within the recipient application may
-        route all messages that start with
-        <literal>org.freedesktop.Peer</literal> to a particular object instance,
-        and may invoke the <literal>Ping()</literal> method on said instance in
-        order to handle the message. This is a convenience API based on 
-        method calls.
-      </para>
-      <para>
-        A "method call" consists of a message and, optionally, a reply to that
-        message. The name of the "method" is the last component of the message,
-        for example, <literal>org.freedesktop.Peer.Ping</literal> would map to
-        the method <literal>Ping()</literal> on some object.
-      </para>
-      <para>
-        Arguments to a method may be considered "in" (processed by the
-        recipient of the message), or "out" (returned to the sender of the
-        message in the reply). "inout" arguments are both sent and received,
-        i.e. the caller passes in a value which is modified. An "inout" argument 
-        is equivalent to an "in" argument, followed by an "out" argument.
-      </para>
-      <para>
-        Given a method with zero or one return values, followed by zero or more
-        arguments, where each argument may be "in", "out", or "inout", the
-        caller constructs a message by appending each "in" or "inout" argument,
-        in order. "out" arguments are not represented in the caller's message.
-      </para>
-      <para>
-        The recipient constructs a reply by appending first the return value 
-        if any, then each "out" or "inout" argument, in order. 
-        "in" arguments are not represented in the reply message.
-      </para>
-      <para>
-        The standard reply message MUST have the same name as the message being 
-        replied to, and MUST set the "rply" header field to the serial 
-        number of the message being replied to.
-      </para>
-      <para>
-        If an error occurs, an error reply may be sent in place of the standard
-        reply. Error replies can be identified by a special header flag, see
-        <xref linkend="message-protocol-header-encoding">.  Error replies have a
-        name which reflects the type of error that occurred. Error replies would
-        generally be mapped to exceptions in a programming language.  If an
-        error reply has a first argument, and that argument has type STRING,
-        then the argument must be an error message.
-      </para>
-      <para>
-        [FIXME discuss mapping of broadcast messages + matching rules 
-        to signals and slots]
-      </para>
-    </sect2>
-  </sect1>
-
   <sect1 id="standard-messages">
     <title>Standard Peer-to-Peer Messages</title>
     <para>
-      In the following message definitions, "method call notation" is presented
-      in addition to simply listing the message names and arguments. The special
-      type name ANY means any type other than NIL, and the special type name
-      ANY_OR_NIL means any valid type.
-      [FIXME the messages here are just made up to illustrate the 
-      format for defining them]
+      See <xref linkend="message-protocol-types-notation"> for details on 
+       the notation used in this section.
     </para>
     <sect2 id="standard-messages-ping">
       <title><literal>org.freedesktop.Peer.Ping</literal></title>
       <para>        
-        As a method:
         <programlisting>
-          void Ping ()
+          org.freedesktop.Peer.Ping ()
         </programlisting>
       </para>
       <para>
-        On receipt of the message <literal>org.freedesktop.Peer.Ping</literal>,
-        an application should reply with
-        <literal>org.freedesktop.Peer.Ping</literal>. Neither the 
-        message nor its reply have any arguments.
-        [FIXME the messages here are just made up to illustrate the 
-        format for defining them]
+        On receipt of the METHOD_CALL
+        message <literal>org.freedesktop.Peer.Ping</literal>, an application
+        should do nothing other than reply with a METHOD_RETURN as usual.
       </para>
     </sect2>
+
     <sect2 id="standard-messages-get-props">
       <title><literal>org.freedesktop.Props.Get</literal></title>
       <para>
-        As a method:
+        [FIXME this is just a bogus made-up method that isn't implemented 
+        or thought through, to save an example of table formatting for the 
+        argument descriptions]
         <programlisting>
-          ANY_OR_NIL Get (in STRING property_name)
+          org.freedesktop.Props.Get (in STRING property_name,
+                                     out ANY_OR_NIL property_value)
         </programlisting>
         Message arguments:
         <informaltable>
@@ -1074,37 +1243,18 @@
             <tbody>
               <row>
                 <entry>0</entry>
-                <entry>STRING</entry>
+                <entry>in STRING</entry>
                 <entry>Name of the property to get</entry>
               </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-        Reply arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
               <row>
-                <entry>0</entry>
-                <entry>ANY_OR_NIL</entry>
+                <entry>1</entry>
+                <entry>out ANY_OR_NIL</entry>
                 <entry>The value of the property. The type depends on the property.</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
       </para>
-      <para>
-        
-        [FIXME the messages here are just made up to illustrate the 
-        format for defining them]
-      </para>
     </sect2>
   </sect1>
 
@@ -1132,18 +1282,18 @@
         the new owner of the service.
       </para>
       <para>
-        Messages may have a <literal>srvc</literal> field (see <xref
+        Messages may have a <literal>SERVICE</literal> field (see <xref
                                                                   linkend="message-protocol-header-fields">).  When the message bus
-          receives a message, if the <literal>srvc</literal> field is absent, the
+          receives a message, if the <literal>SERVICE</literal> field is absent, the
           message is taken to be a standard peer-to-peer message and interpreted
           by the message bus itself. For example, sending
           an <literal>org.freedesktop.Peer.Ping</literal> message with no 
-          <literal>srvc</literal> will cause the message bus itself to reply 
+          <literal>SERVICE</literal> will cause the message bus itself to reply 
           to the ping immediately; the message bus would never make 
           this message visible to other applications.
       </para>
       <para>
-        If the <literal>srvc</literal> field is present, then it indicates a
+        If the <literal>SERVICE</literal> field is present, then it indicates a
         request for the message bus to route the message. In the usual case,
         messages are routed to the owner of the named service.
         Messages may also be <firstterm>broadcast</firstterm>
@@ -1154,7 +1304,7 @@
       </para>
       <para>
         Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
-        the ping message were sent with a <literal>srvc</literal> name of
+        the ping message were sent with a <literal>SERVICE</literal> name of
         <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
         forwarded, and the Yoyodyne Corporation screensaver application would be
         expected to reply to the ping. If
@@ -1967,6 +2117,32 @@
         </para>
       </glossdef>
     </glossentry>
+
+    <glossentry id="term-object"><glossterm>Object</glossterm>
+      <glossdef>
+        <para>
+          Each application contains <firstterm>objects</firstterm>,
+          which have <firstterm>interfaces</firstterm> and 
+          <firstterm>methods</firstterm>. Objects are referred to 
+          by a name, called a <firstterm>path</firstterm> or 
+          <firstterm>object reference</firstterm>.
+        </para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry id="term-path"><glossterm>Path</glossterm>
+      <glossdef>
+        <para>
+          Object references (object names) in D-BUS are 
+          organized into a filesystem-style hierarchy, so 
+          each object is named by a path. As in LDAP, 
+          there's no difference between "files" and "directories";
+          a path can refer to an object, while still having 
+          child objects below it.
+        </para>
+      </glossdef>
+    </glossentry>
+
     <glossentry id="peer-to-peer"><glossterm>Peer-to-peer</glossterm>
       <glossdef>
 	<para>