dbus/doc TODO,1.23,1.24 dbus-specification.sgml,1.40,1.41
Havoc Pennington
hp@pdx.freedesktop.org
Mon, 29 Sep 2003 19:33:27 -0700
- Previous message: dbus/dbus dbus-object-tree.c,1.1,1.2 dbus-object-tree.h,1.1,1.2 dbus-pending-call.c,1.1,1.2 dbus-pending-call.h,1.1,1.2 Makefile.am,1.56,1.57 dbus-address.c,1.10,1.11 dbus-auth.c,1.28,1.29 dbus-bus.c,1.24,1.25 dbus-bus.h,1.7,1.8 dbus-connection-internal.h,1.12,1.13 dbus-connection.c,1.69,1.70 dbus-connection.h,1.24,1.25 dbus-dataslot.h,1.3,1.4 dbus-errors.c,1.21,1.22 dbus-errors.h,1.19,1.20 dbus-hash.c,1.14,1.15 dbus-hash.h,1.9,1.10 dbus-internals.c,1.30,1.31 dbus-internals.h,1.36,1.37 dbus-keyring.c,1.18,1.19 dbus-mainloop.c,1.12,1.13 dbus-mainloop.h,1.3,1.4 dbus-marshal.c,1.41,1.42 dbus-marshal.h,1.17,1.18 dbus-md5.h,1.1,1.2 dbus-message-builder.c,1.18,1.19 dbus-message.c,1.103,1.104 dbus-message.h,1.42,1.43 dbus-protocol.h,1.20,1.21 dbus-server-debug-pipe.c,1.12,1.13 dbus-server-protected.h,1.10,1.11 dbus-server-unix.c,1.18,1.19 dbus-server.c,1.29,1.30 dbus-sha.h,1.1,1.2 dbus-spawn.c,1.12,1.13 dbus-string.c,1.41,1.42 dbus-string.h,1.20,1.21 dbus-sysdeps.c,1.64,1.65 dbus-sysdeps.h,1.35,1.36 dbus-test.c,1.30,1.31 dbus-test.h,1.22,1.23 dbus-threads.c,1.17,1.18 dbus-threads.h,1.3,1.4 dbus-timeout.c,1.10,1.11 dbus-transport-protected.h,1.9,1.10 dbus-transport.c,1.33,1.34 dbus-types.h,1.7,1.8 dbus-userdb.c,1.4,1.5 dbus-watch.c,1.13,1.14 dbus.h,1.15,1.16
- Next message: dbus/glib dbus-gidl.c,1.1,1.2 dbus-gidl.h,1.1,1.2 dbus-glib-tool.c,1.1,1.2 dbus-gloader-expat.c,1.1,1.2 dbus-gobject.c,1.1,1.2 dbus-gparser.c,1.1,1.2 dbus-gparser.h,1.1,1.2 dbus-gproxy.c,1.1,1.2 dbus-gtest-main.c,1.1,1.2 dbus-gtest.c,1.1,1.2 dbus-gtest.h,1.1,1.2 dbus-gtool-test.h,1.1,1.2 dbus-gutils.c,1.1,1.2 dbus-gutils.h,1.1,1.2 .cvsignore,1.4,1.5 Makefile.am,1.4,1.5 dbus-glib.h,1.9,1.10 dbus-gmain.c,1.22,1.23 dbus-gthread.c,1.5,1.6
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvs/dbus/dbus/doc
In directory pdx:/tmp/cvs-serv18265/doc
Modified Files:
TODO dbus-specification.sgml
Log Message:
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
Index: TODO
===================================================================
RCS file: /cvs/dbus/dbus/doc/TODO,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -d -r1.23 -r1.24
--- TODO 9 Aug 2003 15:09:54 -0000 1.23
+++ TODO 30 Sep 2003 02:32:55 -0000 1.24
@@ -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.
Index: dbus-specification.sgml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.sgml,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -d -r1.40 -r1.41
--- dbus-specification.sgml 9 Aug 2003 11:33:48 -0000 1.40
+++ dbus-specification.sgml 30 Sep 2003 02:32:55 -0000 1.41
@@ -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 name of the message, such as org.freedesktop.Peer.Ping</entry>
+ <entry>The object to send the message to; objects are identified by
+ a path, "/foo/bar"</entry>
</row>
<row>
- <entry>rply</entry>
+ <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 error that occurred, for errors</entry>
+ </row>
+ <row>
+ <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>
- Previous message: dbus/dbus dbus-object-tree.c,1.1,1.2 dbus-object-tree.h,1.1,1.2 dbus-pending-call.c,1.1,1.2 dbus-pending-call.h,1.1,1.2 Makefile.am,1.56,1.57 dbus-address.c,1.10,1.11 dbus-auth.c,1.28,1.29 dbus-bus.c,1.24,1.25 dbus-bus.h,1.7,1.8 dbus-connection-internal.h,1.12,1.13 dbus-connection.c,1.69,1.70 dbus-connection.h,1.24,1.25 dbus-dataslot.h,1.3,1.4 dbus-errors.c,1.21,1.22 dbus-errors.h,1.19,1.20 dbus-hash.c,1.14,1.15 dbus-hash.h,1.9,1.10 dbus-internals.c,1.30,1.31 dbus-internals.h,1.36,1.37 dbus-keyring.c,1.18,1.19 dbus-mainloop.c,1.12,1.13 dbus-mainloop.h,1.3,1.4 dbus-marshal.c,1.41,1.42 dbus-marshal.h,1.17,1.18 dbus-md5.h,1.1,1.2 dbus-message-builder.c,1.18,1.19 dbus-message.c,1.103,1.104 dbus-message.h,1.42,1.43 dbus-protocol.h,1.20,1.21 dbus-server-debug-pipe.c,1.12,1.13 dbus-server-protected.h,1.10,1.11 dbus-server-unix.c,1.18,1.19 dbus-server.c,1.29,1.30 dbus-sha.h,1.1,1.2 dbus-spawn.c,1.12,1.13 dbus-string.c,1.41,1.42 dbus-string.h,1.20,1.21 dbus-sysdeps.c,1.64,1.65 dbus-sysdeps.h,1.35,1.36 dbus-test.c,1.30,1.31 dbus-test.h,1.22,1.23 dbus-threads.c,1.17,1.18 dbus-threads.h,1.3,1.4 dbus-timeout.c,1.10,1.11 dbus-transport-protected.h,1.9,1.10 dbus-transport.c,1.33,1.34 dbus-types.h,1.7,1.8 dbus-userdb.c,1.4,1.5 dbus-watch.c,1.13,1.14 dbus.h,1.15,1.16
- Next message: dbus/glib dbus-gidl.c,1.1,1.2 dbus-gidl.h,1.1,1.2 dbus-glib-tool.c,1.1,1.2 dbus-gloader-expat.c,1.1,1.2 dbus-gobject.c,1.1,1.2 dbus-gparser.c,1.1,1.2 dbus-gparser.h,1.1,1.2 dbus-gproxy.c,1.1,1.2 dbus-gtest-main.c,1.1,1.2 dbus-gtest.c,1.1,1.2 dbus-gtest.h,1.1,1.2 dbus-gtool-test.h,1.1,1.2 dbus-gutils.c,1.1,1.2 dbus-gutils.h,1.1,1.2 .cvsignore,1.4,1.5 Makefile.am,1.4,1.5 dbus-glib.h,1.9,1.10 dbus-gmain.c,1.22,1.23 dbus-gthread.c,1.5,1.6
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]