From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_bus_add_node_enumerator.xml | 138 +++++++++++++++++++++++++++++++++++++ 1 file changed, 138 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..c6beb1d --- /dev/null +++ b/man/sd_bus_add_node_enumerator.xml @@ -0,0 +1,138 @@ + + + + + + + + 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. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + See Also + + + sd-bus3, + busctl1, + sd_bus_add_fallback_vtable3, + sd_bus_slot_unref3 + + + -- cgit v1.2.3