sd_bus_add_object - Man Page

#include <systemd/sd-bus-vtable​.h>

typedef int (*sd_bus_message_handler_t)(sd_bus_message *m, void *userdata, sd_bus_error *ret_error);

typedef int (*sd_bus_property_get_t)(sd_bus *bus, const char *path, const char *interface, const char *property, sd_bus_message *reply, void *userdata, sd_bus_error *ret_error);

typedef int (*sd_bus_property_set_t)(sd_bus *bus, const char *path, const char *interface, const char *property, sd_bus_message *value, void *userdata, sd_bus_error *ret_error);

typedef int (*sd_bus_object_find_t)(const char *path, const char *interface, void *userdata, void **ret_found, sd_bus_error *ret_error);

int sd_bus_add_object(sd_bus *bus, sd_bus_slot **slot, const char *path, sd_bus_message_handler_t callback, void *userdata);

int sd_bus_add_fallback(sd_bus *bus, sd_bus_slot **slot, const char *path, sd_bus_message_handler_t callback, void *userdata);

int sd_bus_add_object_vtable(sd_bus *bus, sd_bus_slot **slot, const char *path, const char *interface, const sd_bus_vtable *vtable, void *userdata);

int sd_bus_add_fallback_vtable(sd_bus *bus, sd_bus_slot **slot, const char *prefix, const char *interface, const sd_bus_vtable *vtable, sd_bus_object_find_t find, void *userdata);

int sd_bus_add_filter(sd_bus *bus, sd_bus_slot **slot, sd_bus_message_handler_t callback, void *userdata);

SD_BUS_VTABLE_CAPABILITY(capability)

SD_BUS_VTABLE_START(flags)

SD_BUS_VTABLE_END

SD_BUS_METHOD_WITH_ARGS_OFFSET(member, args, result, handler, offset, flags)

SD_BUS_METHOD_WITH_ARGS(member, args, result, handler, flags)

SD_BUS_METHOD_WITH_NAMES_OFFSET(member, signature, in_names, result, out_names, handler, offset, flags)

SD_BUS_METHOD_WITH_NAMES(member, signature, in_names, result, out_names, handler, flags)

SD_BUS_METHOD_WITH_OFFSET(member, signature, result, handler, offset, flags)

SD_BUS_METHOD(member, signature, result, handler, flags)

SD_BUS_SIGNAL_WITH_ARGS(member, args, flags)

SD_BUS_SIGNAL_WITH_NAMES(member, signature, names, flags)

SD_BUS_SIGNAL(member, signature, flags)

SD_BUS_WRITABLE_PROPERTY(member, signature, get, set, offset, flags)

SD_BUS_PROPERTY(member, signature, get, offset, flags)

SD_BUS_PARAM(name)

SD_BUS_ARGS(​.​.​.)

SD_BUS_RESULT(​.​.​.)

SD_BUS_NO_ARGS

SD_BUS_NO_RESULT

sd_bus_add_object_vtable() is used to declare attributes for the object path path connected to the bus connection bus under the interface interface​. The table vtable may contain property declarations using SD_BUS_PROPERTY() or SD_BUS_WRITABLE_PROPERTY(), method declarations using SD_BUS_METHOD(), SD_BUS_METHOD_WITH_NAMES(), SD_BUS_METHOD_WITH_OFFSET(), or SD_BUS_METHOD_WITH_NAMES_OFFSET(), and signal declarations using SD_BUS_SIGNAL_WITH_NAMES() or SD_BUS_SIGNAL(), see below​. The userdata parameter contains a pointer that will be passed to various callback functions​. It may be specified as NULL if no value is necessary​. An interface can have any number of vtables attached to it​.

sd_bus_add_fallback_vtable() is similar to sd_bus_add_object_vtable(), but is used to register "fallback" attributes​. When looking for an attribute declaration, bus object paths registered with sd_bus_add_object_vtable() are checked first​. If no match is found, the fallback vtables are checked for each prefix of the bus object path, i​.e​. with the last slash-separated components successively removed​. This allows the vtable to be used for an arbitrary number of dynamically created objects​.

Parameter find is a function which is used to locate the target object based on the bus object path path​. It must return 1 and set the ret_found output parameter if the object is found, return 0 if the object was not found, and return a negative errno-style error code or initialize the error structure ret_error on error​. The pointer passed in ret_found will be used as the userdata parameter for the callback functions (offset by the offset offsets as specified in the vtable entries)​.

sd_bus_add_object() attaches a callback directly to the object path path​. An object path can have any number of callbacks attached to it​. Each callback is prepended to the list of callbacks which are always called in order​. sd_bus_add_fallback() is similar to sd_bus_add_object() but applies to fallback paths instead​.

sd_bus_add_filter() installs a callback that is invoked for each incoming D-Bus message​. Filters can be used to handle logic common to all messages received by a service (e​.g​. authentication or authorization)​.

When a request is received, any associated callbacks are called sequentially until a callback returns a non-zero integer​. Return zero from a callback to give other callbacks the chance to process the request​. Callbacks are called in the following order: first, global callbacks installed with sd_bus_add_filter() are called​. Second, callbacks attached directly to the request object path are called, followed by any D-Bus method callbacks attached to the request object path, interface and member​. Finally, the property callbacks attached to the request object path, interface and member are called​. If the final callback returns zero, an error reply is sent back to the caller indicating no matching object for the request was found​.

Note that you can return a positive integer from a method callback without immediately sending a reply​. This informs sd-bus this callback will take responsibility for replying to the request without forcing the callback to produce a reply immediately​. This allows a callback to perform any number of asynchronous operations required to construct a reply​. However, if producing a reply takes too long, the method call will time out at the caller​. This is only available to methods and not properties​.

If a callback was invoked to handle a request that expects a reply and the callback returns a negative value, the value is interpreted as a negative errno-style error code and sent back to the caller as a D-Bus error as if sd_bus_reply_method_errno(3) was called​. Additionally, all callbacks take a sd_bus_error output parameter that can be used to provide more detailed error information​. If ret_error is set when the callback finishes, the corresponding D-Bus error is sent back to the caller as if sd_bus_reply_method_error(3) was called​. Any error stored in ret_error takes priority over any negative values returned by the same callback when determining which error to send back to the caller​. Use sd_bus_error_set(3) or one of its variants to set ret_error and return a negative integer from a callback with a single function call​. To send an error reply after a callback has already finished, use sd_bus_reply_method_errno(3) or one of its variants​.

For all functions, a match slot is created internally​. If the output parameter slot is NULL, a "floating" slot object is created, see sd_bus_slot_set_floating(3)​. Otherwise, a pointer to the slot object is returned​. In that case, the reference to the slot object should be dropped when the vtable is not needed anymore, see sd_bus_slot_unref(3)​.

Example ​1. ​Create a simple listener on the bus

/* SPDX-License-Identifier: MIT-0 */

#define _GNU_SOURCE 1
#include <errno​.h>
#include <stdbool​.h>
#include <stddef​.h>
#include <stdlib​.h>
#include <stdio​.h>
#include <systemd/sd-bus​.h>

#define _cleanup_(f) __attribute__((cleanup(f)))

typedef struct object {
  char *name;
  uint32_t number;
} object;

static int method(sd_bus_message *m, void *userdata, sd_bus_error *error) {
  int r;

  printf("Got called with userdata=%p\n", userdata);

  if (sd_bus_message_is_method_call(m,
                                    "org​.freedesktop​.systemd​.VtableExample",
                                    "Method4"))
    return 1;

  const char *string;
  r = sd_bus_message_read(m, "s", &string);
  if (r < 0) {
    fprintf(stderr, "sd_bus_message_read() failed: %s\n", strerror(-r));
    return 0;
  }

  r = sd_bus_reply_method_return(m, "s", string);
  if (r < 0) {
    fprintf(stderr, "sd_bus_reply_method_return() failed: %s\n", strerror(-r));
    return 0;
  }

  return 1;
}

static const sd_bus_vtable vtable[] = {
        SD_BUS_VTABLE_START(0),
        SD_BUS_METHOD(
            "Method1", "s", "s", method, 0),
        SD_BUS_METHOD_WITH_NAMES_OFFSET(
            "Method2",
            "so", SD_BUS_PARAM(string) SD_BUS_PARAM(path),
            "s", SD_BUS_PARAM(returnstring),
            method, offsetof(object, number),
            SD_BUS_VTABLE_DEPRECATED),
        SD_BUS_METHOD_WITH_ARGS_OFFSET(
            "Method3",
            SD_BUS_ARGS("s", string, "o", path),
            SD_BUS_RESULT("s", returnstring),
            method, offsetof(object, number),
            SD_BUS_VTABLE_UNPRIVILEGED),
        SD_BUS_METHOD_WITH_ARGS(
            "Method4",
            SD_BUS_NO_ARGS,
            SD_BUS_NO_RESULT,
            method,
            SD_BUS_VTABLE_UNPRIVILEGED),
        SD_BUS_SIGNAL(
            "Signal1",
            "so",
            0),
        SD_BUS_SIGNAL_WITH_NAMES(
            "Signal2",
            "so", SD_BUS_PARAM(string) SD_BUS_PARAM(path),
            0),
        SD_BUS_SIGNAL_WITH_ARGS(
            "Signal3",
            SD_BUS_ARGS("s", string, "o", path),
            0),
        SD_BUS_WRITABLE_PROPERTY(
            "AutomaticStringProperty", "s", NULL, NULL,
            offsetof(object, name),
            SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE),
        SD_BUS_WRITABLE_PROPERTY(
            "AutomaticIntegerProperty", "u", NULL, NULL,
            offsetof(object, number),
            SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION),
        SD_BUS_VTABLE_END
};

int main(int argc, char **argv) {
  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
  int r;

  sd_bus_default(&bus);

  object object = { ​.number = 666 };
  object​.name = strdup("name");
  if (!object​.name) {
    fprintf(stderr, "OOM\n");
    return EXIT_FAILURE;
  }

  r = sd_bus_add_object_vtable(bus, NULL,
                               "/org/freedesktop/systemd/VtableExample",
                               "org​.freedesktop​.systemd​.VtableExample",
                               vtable,
                               &object);
  if (r < 0) {
    fprintf(stderr, "sd_bus_add_object_vtable() failed: %s\n", strerror(-r));
    return EXIT_FAILURE;
  }

  r = sd_bus_request_name(bus,
                          "org​.freedesktop​.systemd​.VtableExample",
                          0);
  if (r < 0) {
    fprintf(stderr, "sd_bus_request_name() failed: %s\n", strerror(-r));
    return EXIT_FAILURE;
  }

  for (;;) {
    r = sd_bus_wait(bus, UINT64_MAX);
    if (r < 0) {
      fprintf(stderr, "sd_bus_wait() failed: %s\n", strerror(-r));
      return EXIT_FAILURE;
    }

    r = sd_bus_process(bus, NULL);
    if (r < 0) {
      fprintf(stderr, "sd_bus_process() failed: %s\n", strerror(-r));
      return EXIT_FAILURE;
    }
  }

  r = sd_bus_release_name(bus, "org​.freedesktop​.systemd​.VtableExample");
  if (r < 0) {
    fprintf(stderr, "sd_bus_release_name() failed: %s\n", strerror(-r));
    return EXIT_FAILURE;
  }

  free(object​.name);

  return 0;
}

This creates a simple client on the bus (the user bus, when run as normal user)​. We may use the D-Bus org​.freedesktop​.DBus​.Introspectable​.Introspect call to acquire the XML description of the interface:

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1​.0//EN"
"https://www​.freedesktop​.org/standards/dbus/1​.0/introspect​.dtd">
<!-- SPDX-License-Identifier: LGPL-2​.1-or-later -->
<node>
 <interface name="org​.freedesktop​.DBus​.Peer">
  <method name="Ping"/>
  <method name="GetMachineId">
   <arg type="s" name="machine_uuid" direction="out"/>
  </method>
 </interface>
 <interface name="org​.freedesktop​.DBus​.Introspectable">
  <method name="Introspect">
   <arg name="xml_data" type="s" direction="out"/>
  </method>
 </interface>
 <interface name="org​.freedesktop​.DBus​.Properties">
  <method name="Get">
   <arg name="interface_name" direction="in" type="s"/>
   <arg name="property_name" direction="in" type="s"/>
   <arg name="value" direction="out" type="v"/>
  </method>
  <method name="GetAll">
   <arg name="interface_name" direction="in" type="s"/>
   <arg name="props" direction="out" type="a{sv}"/>
  </method>
  <method name="Set">
   <arg name="interface_name" direction="in" type="s"/>
   <arg name="property_name" direction="in" type="s"/>
   <arg name="value" direction="in" type="v"/>
  </method>
  <signal name="PropertiesChanged">
   <arg type="s" name="interface_name"/>
   <arg type="a{sv}" name="changed_properties"/>
   <arg type="as" name="invalidated_properties"/>
  </signal>
 </interface>
 <interface name="org​.freedesktop​.systemd​.VtableExample">
  <method name="Method1">
   <arg type="s" direction="in"/>
   <arg type="s" direction="out"/>
  </method>
  <method name="Method2">
   <arg type="s" name="string" direction="in"/>
   <arg type="o" name="path" direction="in"/>
   <arg type="s" name="returnstring" direction="out"/>
   <annotation name="org​.freedesktop​.DBus​.Deprecated" value="true"/>
  </method>
  <property name="AutomaticStringProperty" type="s" access="readwrite">
  </property>
  <property name="AutomaticIntegerProperty" type="u" access="readwrite">
   <annotation name="org​.freedesktop​.DBus​.Property​.EmitsChangedSignal" value="invalidates"/>
  </property>
 </interface>
</node>

On success, sd_bus_add_object_vtable() and sd_bus_add_fallback_vtable() return a non-negative integer​. On failure, they return a negative errno-style error code​.

Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd ​pkg-config(1) file​.

All functions listed here are thread-agnostic and only a single thread may operate on a given object at any given time​. Different threads may access the same object at different times​. Multiple independent objects may be used from different threads in parallel​.

The code described here uses getenv(3), which is declared to be not multi-thread-safe​. This means that the code calling the functions described here must not call setenv(3) from a parallel thread​. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started​.

sd_bus_property_get_t(), sd_bus_property_set_t(), sd_bus_object_find_t(), sd_bus_add_object(), sd_bus_add_fallback(), sd_bus_add_object_vtable(), sd_bus_add_fallback_vtable(), and sd_bus_add_filter() were added in version 221​.

sd-bus(3), busctl(1), sd_bus_emit_properties_changed(3), sd_bus_emit_object_added(3)

1. D-Bus annotations
   https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
2. polkit
   https://www.freedesktop.org/software/polkit/docs/latest/

sd-bus(3), sd_bus_add_node_enumerator(3), sd_bus_add_object_manager(3), sd_bus_call(3), sd_bus_process(3), sd_bus_slot_set_userdata(3), systemd.directives(7), systemd.index(7).

The man pages sd_bus_add_fallback(3), sd_bus_add_fallback_vtable(3), sd_bus_add_filter(3), sd_bus_add_object_vtable(3), SD_BUS_METHOD(3), SD_BUS_METHOD_WITH_NAMES(3), SD_BUS_METHOD_WITH_NAMES_OFFSET(3), SD_BUS_METHOD_WITH_OFFSET(3), SD_BUS_PARAM(3), SD_BUS_PROPERTY(3), SD_BUS_SIGNAL(3), SD_BUS_SIGNAL_WITH_NAMES(3), SD_BUS_VTABLE_CAPABILITY(3), SD_BUS_VTABLE_END(3), SD_BUS_VTABLE_START(3) and SD_BUS_WRITABLE_PROPERTY(3) are aliases of sd_bus_add_object(3).