# sd_bus_add_node_enumerator

## NAME



           sd_bus_add_node_enumerator - Add a node enumerator for a D-Bus
           object path prefix
    


## SYNOPSIS



           **#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_vtable(3).
    
           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_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 node
           enumerator is not needed anymore, see sd_bus_slot_unref(3).
    


## 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.
    


## NOTES



           Functions described here are available as a shared library, which
           can be compiled against and linked to with the
           **libsystemd pkg-config**(1) file.
    
           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.
    


* * *