A hierarchy of objects with container-contained relationship
[D-Bus secret internal implementation details]

DBusObjectTree is used by DBusConnection to track the object tree. More...


Data Structures
struct	DBusObjectTree
	Internals of DBusObjectTree. More...
struct	DBusObjectSubtree
	Struct representing a single registered subtree handler, or node that's a parent of a registered subtree handler. More...
Defines
#define	VERBOSE_FIND 0
	Set to 1 to get a bunch of debug spew about finding the subtree nodes.
#define	VERBOSE_DECOMPOSE 0
	Set to 1 to get a bunch of spew about disassembling the path string.
Typedefs
typedef DBusObjectSubtree	DBusObjectSubtree
	Subnode of the object hierarchy.
Functions
DBusObjectTree *	_dbus_object_tree_new (DBusConnection *connection)
	Creates a new object tree, representing a mapping from paths to handler vtables.
DBusObjectTree *	_dbus_object_tree_ref (DBusObjectTree *tree)
	Increment the reference count.
void	_dbus_object_tree_unref (DBusObjectTree *tree)
	Decrement the reference count.
dbus_bool_t	_dbus_object_tree_register (DBusObjectTree tree, dbus_bool_t fallback, const char path, const DBusObjectPathVTable vtable, void *user_data)
	Registers a new subtree in the global object tree.
void	_dbus_object_tree_unregister_and_unlock (DBusObjectTree tree, const char *path)
	Unregisters an object subtree that was registered with the same path.
void	_dbus_object_tree_free_all_unlocked (DBusObjectTree *tree)
	Free all the handlers in the tree.
DBusHandlerResult	_dbus_object_tree_dispatch_and_unlock (DBusObjectTree tree, DBusMessage message)
	Tries to dispatch a message by directing it to handler for the object path listed in the message header, if any.
void *	_dbus_object_tree_get_user_data_unlocked (DBusObjectTree tree, const char *path)
	Looks up the data passed to _dbus_object_tree_register() for a handler at the given path.
dbus_bool_t	_dbus_object_tree_list_registered_and_unlock (DBusObjectTree tree, const char parent_path, char **child_entries)
	Lists the registered fallback handlers and object path handlers at the given parent_path.
dbus_bool_t	_dbus_decompose_path (const char data, int len, char *path, int path_len)
	Decompose an object path.

Detailed Description

DBusObjectTree is used by DBusConnection to track the object tree.

Types and functions related to DBusObjectTree. These are all library-internal.

Function Documentation

dbus_bool_t _dbus_decompose_path	(	const char *	data,
		int	len,
		char ***	path,
		int *	path_len
	)

Decompose an object path.

A path of just "/" is represented as an empty vector of strings. The path need not be nul terminated.

Parameters:

	data	the path data
	len	the length of the path string
	path	address to store new object path
	path_len	length of stored path

Definition at line 1058 of file dbus-object-tree.c.

References _dbus_assert, _dbus_memdup(), dbus_free_string_array(), dbus_new0, FALSE, NULL, and TRUE.

Referenced by dbus_connection_get_object_path_data(), dbus_connection_list_registered(), dbus_connection_register_fallback(), dbus_connection_register_object_path(), dbus_connection_unregister_object_path(), and dbus_message_get_path_decomposed().

DBusHandlerResult _dbus_object_tree_dispatch_and_unlock	(	DBusObjectTree *	tree,
		DBusMessage *	message
	)

Tries to dispatch a message by directing it to handler for the object path listed in the message header, if any.

Messages are dispatched first to the registered handler that matches the largest number of path elements; that is, message to /foo/bar/baz would go to the handler for /foo/bar before the one for /foo.

Todo:: thread problems

Parameters:

	tree	the global object tree
	message	the message to dispatch

Returns:: whether message was handled successfully

Definition at line 731 of file dbus-object-tree.c.

References _dbus_connection_lock(), _dbus_connection_unlock(), _dbus_list_append(), _dbus_list_get_first_link(), _dbus_list_get_length(), _dbus_list_get_next_link, _dbus_list_remove_link(), connection, DBusList::data, dbus_free_string_array(), DBUS_HANDLER_RESULT_NEED_MEMORY, DBUS_HANDLER_RESULT_NOT_YET_HANDLED, dbus_message_get_path_decomposed(), FALSE, DBusObjectSubtree::invoke_as_fallback, DBusObjectSubtree::message_function, NULL, DBusObjectSubtree::parent, and DBusObjectSubtree::user_data.

Referenced by dbus_connection_dispatch().

void _dbus_object_tree_free_all_unlocked ( DBusObjectTree * tree )

Free all the handlers in the tree.

Lock on tree's connection must not be held.

Parameters:

tree

the object tree

Definition at line 547 of file dbus-object-tree.c.

References connection, NULL, and root.

Referenced by _dbus_object_tree_unref().

void* _dbus_object_tree_get_user_data_unlocked	(	DBusObjectTree *	tree,
		const char **	path
	)

Looks up the data passed to _dbus_object_tree_register() for a handler at the given path.

Parameters:

	tree	the global object tree
	path	NULL-terminated array of path elements giving path to subtree

Returns:: the object's user_data or NULL if none found

Definition at line 899 of file dbus-object-tree.c.

References _dbus_assert, NULL, and DBusObjectSubtree::user_data.

Referenced by dbus_connection_get_object_path_data().

dbus_bool_t _dbus_object_tree_list_registered_and_unlock	(	DBusObjectTree *	tree,
		const char **	parent_path,
		char ***	child_entries
	)

Lists the registered fallback handlers and object path handlers at the given parent_path.

The returned array should be freed with dbus_free_string_array().

Parameters:

	tree	the object tree
	parent_path	the path to list the child handlers of
	child_entries	returns NULL-terminated array of children

Returns:: FALSE if no memory to allocate the child entries

Definition at line 1022 of file dbus-object-tree.c.

References _dbus_connection_unlock(), and connection.

Referenced by dbus_connection_list_registered().

DBusObjectTree* _dbus_object_tree_new ( DBusConnection * connection )

Creates a new object tree, representing a mapping from paths to handler vtables.

Parameters:

connection

the connection this tree belongs to

Returns:: the new tree or NULL if no memory

Definition at line 90 of file dbus-object-tree.c.

References connection, dbus_free(), dbus_new0, DBusObjectSubtree::invoke_as_fallback, NULL, refcount, root, and TRUE.

Referenced by _dbus_connection_new_for_transport().

DBusObjectTree* _dbus_object_tree_ref ( DBusObjectTree * tree )

Increment the reference count.

Parameters:

tree

the object tree

Returns:: the object tree

Definition at line 127 of file dbus-object-tree.c.

References _dbus_assert, and refcount.

dbus_bool_t _dbus_object_tree_register	(	DBusObjectTree *	tree,
		dbus_bool_t	fallback,
		const char **	path,
		const DBusObjectPathVTable *	vtable,
		void *	user_data
	)

Registers a new subtree in the global object tree.

Parameters:

	tree	the global object tree
	fallback	TRUE to handle messages to children of this path
	path	NULL-terminated array of path elements giving path to subtree
	vtable	the vtable used to traverse this subtree
	user_data	user data to pass to methods in the vtable