1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_bus_add_node_enumerator" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_bus_add_node_enumerator</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_bus_add_node_enumerator</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>sd_bus_add_node_enumerator</refname> 21 22 <refpurpose>Add a node enumerator for a D-Bus object path prefix</refpurpose> 23 </refnamediv> 24 25 <refsynopsisdiv> 26 <funcsynopsis> 27 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 28 29 <funcprototype> 30 <funcdef>typedef int (*<function>sd_bus_node_enumerator_t</function>)</funcdef> 31 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 32 <paramdef>const char *<parameter>prefix</parameter></paramdef> 33 <paramdef>void *<parameter>userdata</parameter></paramdef> 34 <paramdef>char ***<parameter>ret_nodes</parameter></paramdef> 35 <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> 36 </funcprototype> 37 38 <funcprototype> 39 <funcdef>int <function>sd_bus_add_node_enumerator</function></funcdef> 40 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 41 <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> 42 <paramdef>const char *<parameter>path</parameter></paramdef> 43 <paramdef>sd_bus_node_enumerator_t <parameter>callback</parameter></paramdef> 44 <paramdef>void *<parameter>userdata</parameter></paramdef> 45 </funcprototype> 46 </funcsynopsis> 47 </refsynopsisdiv> 48 49 <refsect1> 50 <title>Description</title> 51 52 <para><function>sd_bus_add_node_enumerator()</function> adds a D-Bus node enumerator for the 53 given path prefix. The given callback is called to enumerate all the available objects with 54 the given path prefix when required (e.g. when 55 <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> or 56 <constant>org.freedesktop.DBus.ObjectManager.GetManagedObjects</constant> are called on a 57 D-Bus service managed by sd-bus).</para> 58 59 <para><parameter>callback</parameter> is called with the path and userdata pointer registered 60 with <function>sd_bus_add_node_enumerator()</function>. When called, it should store all the 61 child object paths of the given path prefix in <parameter>ret_nodes</parameter> with a NULL 62 terminator item. The callback should return a non-negative value on success. 63 If an error occurs, it can either return a 64 negative integer, set <parameter>ret_error</parameter> to a non-empty error or do both. Any 65 errors returned by the callback are encoded as D-Bus errors and sent back to the caller. Errors 66 in <parameter>ret_error</parameter> take priority over negative return values.</para> 67 68 <para>Note that a node enumerator callback will only ever be called for a single path prefix 69 and hence, for normal operation, <parameter>prefix</parameter> can be ignored. Also, a node 70 enumerator is only used to enumerate the available child objects under a given prefix. To 71 install a handler for a set of dynamic child objects, use 72 <citerefentry><refentrytitle>sd_bus_add_fallback_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 73 </para> 74 75 <para>When <function>sd_bus_add_node_enumerator()</function> succeeds, a slot is created 76 internally. If the output parameter <replaceable>slot</replaceable> is <constant>NULL</constant>, 77 a "floating" slot object is created, see 78 <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 79 Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot 80 object should be dropped when the node enumerator is not needed anymore, see 81 <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 82 </para> 83 </refsect1> 84 85 <refsect1> 86 <title>Return Value</title> 87 88 <para>On success, <function>sd_bus_add_node_enumerator()</function> returns a non-negative 89 integer. On failure, it returns a negative errno-style error code.</para> 90 91 <refsect2> 92 <title>Errors</title> 93 94 <para>Returned errors may indicate the following problems:</para> 95 96 <variablelist> 97 <varlistentry> 98 <term><constant>-EINVAL</constant></term> 99 100 <listitem><para>One of the required parameters is <constant>NULL</constant> or 101 <parameter>path</parameter> is not a valid object path. 102 </para></listitem> 103 </varlistentry> 104 105 <varlistentry> 106 <term><constant>-ENOPKG</constant></term> 107 108 <listitem><para>The bus cannot be resolved.</para></listitem> 109 </varlistentry> 110 111 <varlistentry> 112 <term><constant>-ECHILD</constant></term> 113 114 <listitem><para>The bus was created in a different process.</para></listitem> 115 </varlistentry> 116 117 <varlistentry> 118 <term><constant>-ENOMEM</constant></term> 119 120 <listitem><para>Memory allocation failed.</para></listitem> 121 </varlistentry> 122 </variablelist> 123 </refsect2> 124 </refsect1> 125 126 <xi:include href="libsystemd-pkgconfig.xml" /> 127 128 <refsect1> 129 <title>See Also</title> 130 131 <para> 132 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 133 <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 134 <citerefentry><refentrytitle>sd_bus_add_fallback_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 135 <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> 136 </para> 137 </refsect1> 138</refentry> 139