Method

GioDBusConnectionregister_subtree

since: 2.26

Declaration [src] 

guint
g_dbus_connection_register_subtree (
  GDBusConnection* connection,
  const gchar* object_path,
  const GDBusSubtreeVTable* vtable,
  GDBusSubtreeFlags flags,
  gpointer user_data,
  GDestroyNotify user_data_free_func,
  GError** error
)

Description [src]

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.

Available since: 2.26

Parameters

object_path

Type: const gchar*

The object path to register the subtree at.

The data is owned by the caller of the method.
The value is a NUL terminated UTF-8 string.
vtable

Type: GDBusSubtreeVTable

A GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.

The data is owned by the caller of the method.
flags

Type: GDBusSubtreeFlags

Flags used to fine tune the behavior of the subtree.

user_data

Type: gpointer

Data to pass to functions in vtable.

The argument can be NULL.
The data is owned by the caller of the method.
user_data_free_func

Type: GDestroyNotify

Function to call when the subtree is unregistered.

error

Type: GError **

The return location for a recoverable error.

The argument can be NULL.
If the return location is not NULL, then you must initialize it to a NULL GError*.
The argument will be left initialized to NULL by the method if there are no errors.
In case of error, the argument will be set to a newly allocated GError; the caller will take ownership of the data, and be responsible for freeing it.

Return value

Type: guint

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