DBusConnection.registerSubtree

Registers a whole subtree of dynamic objects.

The @enumerate and @introspection functions in @vtable are used to convey, to remote callers, what nodes exist in the subtree rooted by @object_path.

When handling remote calls into any node in the subtree, first the @enumerate function is used to check if the node exists. If the node exists or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set the @introspection function is used to check if the node supports the requested method. If so, the @dispatch function is used to determine where to dispatch the call. The collected #GDBusInterfaceVTable and #gpointer will be used to call into the interface vtable for processing the request.

All calls into user-provided code will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from.

If an existing subtree is already registered at @object_path or then @error is set to #G_IO_ERROR_EXISTS.

Note that it is valid to register regular objects (using g_dbus_connection_register_object()) in a subtree registered with g_dbus_connection_register_subtree() - if so, the subtree handler is tried as the last resort. One way to think about a subtree handler is to consider it a fallback handler for object paths not registered via g_dbus_connection_register_object() or other bindings.

Note that @vtable will be copied so you cannot change it after registration.

See this server[gdbus-subtree-server] for an example of how to use this method.

Parameters

objectPath string

the object path to register the subtree at

vtable GDBusSubtreeVTable*

a #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree

flags GDBusSubtreeFlags

flags used to fine tune the behavior of the subtree

userData void*

data to pass to functions in @vtable

userDataFreeFunc GDestroyNotify

function to call when the subtree is unregistered

Return Value

Type: uint

0 if @error is set, otherwise a subtree registration ID (never 0) that can be used with g_dbus_connection_unregister_subtree()

Throws

GException on failure.

Meta

Since

2.26