From 55944e5e40b1be2afc4855d8d2baf4b73d1876b5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:49:52 +0200 Subject: Adding upstream version 255.4. Signed-off-by: Daniel Baumann --- man/sd_bus_add_node_enumerator.xml | 152 +++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 man/sd_bus_add_node_enumerator.xml (limited to 'man/sd_bus_add_node_enumerator.xml') diff --git a/man/sd_bus_add_node_enumerator.xml b/man/sd_bus_add_node_enumerator.xml new file mode 100644 index 0000000..f97746c --- /dev/null +++ b/man/sd_bus_add_node_enumerator.xml @@ -0,0 +1,152 @@ + + + + + + + + sd_bus_add_node_enumerator + systemd + + + + sd_bus_add_node_enumerator + 3 + + + + sd_bus_add_node_enumerator + + Add a node enumerator for a D-Bus object path prefix + + + + + #include <systemd/sd-bus.h> + + + typedef int (*sd_bus_node_enumerator_t) + sd_bus *bus + const char *prefix + void *userdata + char ***ret_nodes + sd_bus_error *ret_error + + + + int sd_bus_add_node_enumerator + sd_bus *bus + sd_bus_slot **slot + const char *path + sd_bus_node_enumerator_t callback + void *userdata + + + + + + Description + + sd_bus_add_node_enumerator() adds a D-Bus node enumerator for the + given path prefix. The given callback is called to enumerate all the available objects with + the given path prefix when required (e.g. when + org.freedesktop.DBus.Introspectable.Introspect or + org.freedesktop.DBus.ObjectManager.GetManagedObjects are called on a + D-Bus service managed by sd-bus). + + callback is called with the path and userdata pointer registered + with sd_bus_add_node_enumerator(). When called, it should store all the + child object paths of the given path prefix in ret_nodes with a NULL + terminator item. The callback should return a non-negative value on success. + If an error occurs, it can either return a + negative integer, set ret_error to a non-empty error or do both. Any + errors returned by the callback are encoded as D-Bus errors and sent back to the caller. Errors + in ret_error take priority over negative return values. + + Note that a node enumerator callback will only ever be called for a single path prefix + and hence, for normal operation, prefix can be ignored. Also, a node + enumerator is only used to enumerate the available child objects under a given prefix. To + install a handler for a set of dynamic child objects, use + sd_bus_add_fallback_vtable3. + + + When sd_bus_add_node_enumerator() succeeds, a slot is created + internally. If the output parameter slot is NULL, + a "floating" slot object is created, see + sd_bus_slot_set_floating3. + Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot + object should be dropped when the node enumerator is not needed anymore, see + sd_bus_slot_unref3. + + + + + Return Value + + On success, sd_bus_add_node_enumerator() returns a non-negative + integer. On failure, it returns a negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + One of the required parameters is NULL or + path is not a valid object path. + + + + + + + -ENOPKG + + The bus cannot be resolved. + + + + + + -ECHILD + + The bus was created in a different process, library or module instance. + + + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + + + History + sd_bus_node_enumerator_t() and + sd_bus_add_node_enumerator() were added in version 246. + + + + See Also + + + sd-bus3, + busctl1, + sd_bus_add_fallback_vtable3, + sd_bus_slot_unref3 + + + -- cgit v1.2.3