Gio.DBusConnection.register_subtree

### Method

# Gio DBusConnectionregister_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 (see `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 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().