summaryrefslogtreecommitdiffstats
path: root/dbus/dbus-object-tree.c
diff options
context:
space:
mode:
Diffstat (limited to 'dbus/dbus-object-tree.c')
-rw-r--r--dbus/dbus-object-tree.c60
1 files changed, 45 insertions, 15 deletions
diff --git a/dbus/dbus-object-tree.c b/dbus/dbus-object-tree.c
index 8430b323..9922dec4 100644
--- a/dbus/dbus-object-tree.c
+++ b/dbus/dbus-object-tree.c
@@ -45,6 +45,7 @@
* @{
*/
+/** Subnode of the object hierarchy */
typedef struct DBusObjectSubtree DBusObjectSubtree;
static DBusObjectSubtree* _dbus_object_subtree_new (const char *name,
@@ -53,28 +54,43 @@ static DBusObjectSubtree* _dbus_object_subtree_new (const char
static void _dbus_object_subtree_ref (DBusObjectSubtree *subtree);
static void _dbus_object_subtree_unref (DBusObjectSubtree *subtree);
+/**
+ * Internals of DBusObjectTree
+ */
struct DBusObjectTree
{
- int refcount;
- DBusConnection *connection;
+ int refcount; /**< Reference count */
+ DBusConnection *connection; /**< Connection this tree belongs to */
- DBusObjectSubtree *root;
+ DBusObjectSubtree *root; /**< Root of the tree ("/" node) */
};
+/**
+ * Struct representing a single registered subtree handler, or node
+ * that's a parent of a registered subtree handler. If
+ * message_function != NULL there's actually a handler at this node.
+ */
struct DBusObjectSubtree
{
- DBusAtomic refcount;
- DBusObjectSubtree *parent;
- DBusObjectPathUnregisterFunction unregister_function;
- DBusObjectPathMessageFunction message_function;
- void *user_data;
- DBusObjectSubtree **subtrees;
- int n_subtrees;
- unsigned int subtrees_sorted : 1;
- unsigned int invoke_as_fallback : 1;
+ DBusAtomic refcount; /**< Reference count */
+ DBusObjectSubtree *parent; /**< Parent node */
+ DBusObjectPathUnregisterFunction unregister_function; /**< Function to call on unregister */
+ DBusObjectPathMessageFunction message_function; /**< Function to handle messages */
+ void *user_data; /**< Data for functions */
+ DBusObjectSubtree **subtrees; /**< Child nodes */
+ int n_subtrees; /**< Number of child nodes */
+ unsigned int subtrees_sorted : 1; /**< Whether children are sorted */
+ unsigned int invoke_as_fallback : 1; /**< Whether to invoke message_function when child nodes don't handle the message */
char name[1]; /**< Allocated as large as necessary */
};
+/**
+ * Creates a new object tree, representing a mapping from paths
+ * to handler vtables.
+ *
+ * @param connection the connection this tree belongs to
+ * @returns the new tree or #NULL if no memory
+ */
DBusObjectTree*
_dbus_object_tree_new (DBusConnection *connection)
{
@@ -107,6 +123,10 @@ _dbus_object_tree_new (DBusConnection *connection)
return NULL;
}
+/**
+ * Increment the reference count
+ * @param tree the object tree
+ */
void
_dbus_object_tree_ref (DBusObjectTree *tree)
{
@@ -115,6 +135,10 @@ _dbus_object_tree_ref (DBusObjectTree *tree)
tree->refcount += 1;
}
+/**
+ * Decrement the reference count
+ * @param tree the object tree
+ */
void
_dbus_object_tree_unref (DBusObjectTree *tree)
{
@@ -160,6 +184,9 @@ ensure_sorted (DBusObjectSubtree *subtree)
}
}
+/** Set to 1 to get a bunch of debug spew about finding the
+ * subtree nodes
+ */
#define VERBOSE_FIND 0
static DBusObjectSubtree*
@@ -855,11 +882,14 @@ spew_tree (DBusObjectTree *tree)
spew_subtree_recurse (tree->root, 0);
}
+/**
+ * Callback data used in tests
+ */
typedef struct
{
- const char **path;
- dbus_bool_t message_handled;
- dbus_bool_t handler_unregistered;
+ const char **path; /**< Path */
+ dbus_bool_t message_handled; /**< Gets set to true if message handler called */
+ dbus_bool_t handler_unregistered; /**< gets set to true if handler is unregistered */
} TreeTestData;