man/sd_bus_add_object.xml

   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_object"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_add_object</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_add_object</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_add_object</refname>
  21     <refname>sd_bus_add_fallback</refname>
  22     <refname>sd_bus_add_object_vtable</refname>
  23     <refname>sd_bus_add_fallback_vtable</refname>
  24     <refname>sd_bus_add_filter</refname>
  25     <refname>SD_BUS_VTABLE_START</refname>
  26     <refname>SD_BUS_VTABLE_END</refname>
  27     <refname>SD_BUS_METHOD_WITH_NAMES_OFFSET</refname>
  28     <refname>SD_BUS_METHOD_WITH_NAMES</refname>
  29     <refname>SD_BUS_METHOD_WITH_OFFSET</refname>
  30     <refname>SD_BUS_METHOD</refname>
  31     <refname>SD_BUS_SIGNAL_WITH_NAMES</refname>
  32     <refname>SD_BUS_SIGNAL</refname>
  33     <refname>SD_BUS_WRITABLE_PROPERTY</refname>
  34     <refname>SD_BUS_PROPERTY</refname>
  35     <refname>SD_BUS_PARAM</refname>
  36
  37     <refpurpose>Declare properties and methods for a D-Bus path</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-bus-vtable.h&gt;</funcsynopsisinfo>
  43
  44       <xi:include href="sd_bus_add_match.xml" xpointer="sd_bus_message_handler_t"/>
  45
  46       <funcprototype>
  47         <funcdef>typedef int (*<function>sd_bus_property_get_t</function>)</funcdef>
  48         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  49         <paramdef>const char *<parameter>path</parameter></paramdef>
  50         <paramdef>const char *<parameter>interface</parameter></paramdef>
  51         <paramdef>const char *<parameter>property</parameter></paramdef>
  52         <paramdef>sd_bus_message *<parameter>reply</parameter></paramdef>
  53         <paramdef>void *<parameter>userdata</parameter></paramdef>
  54         <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
  55       </funcprototype>
  56
  57       <funcprototype>
  58         <funcdef>typedef int (*<function>sd_bus_property_set_t</function>)</funcdef>
  59         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  60         <paramdef>const char *<parameter>path</parameter></paramdef>
  61         <paramdef>const char *<parameter>interface</parameter></paramdef>
  62         <paramdef>const char *<parameter>property</parameter></paramdef>
  63         <paramdef>sd_bus_message *<parameter>value</parameter></paramdef>
  64         <paramdef>void *<parameter>userdata</parameter></paramdef>
  65         <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>typedef int (*<function>sd_bus_object_find_t</function>)</funcdef>
  70         <paramdef>const char *<parameter>path</parameter></paramdef>
  71         <paramdef>const char *<parameter>interface</parameter></paramdef>
  72         <paramdef>void *<parameter>userdata</parameter></paramdef>
  73         <paramdef>void **<parameter>ret_found</parameter></paramdef>
  74         <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_bus_add_object</function></funcdef>
  79         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  80         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
  81         <paramdef>const char *<parameter>path</parameter></paramdef>
  82         <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
  83         <paramdef>void *<parameter>userdata</parameter></paramdef>
  84       </funcprototype>
  85
  86       <funcprototype>
  87         <funcdef>int <function>sd_bus_add_fallback</function></funcdef>
  88         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  89         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
  90         <paramdef>const char *<parameter>path</parameter></paramdef>
  91         <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
  92         <paramdef>void *<parameter>userdata</parameter></paramdef>
  93       </funcprototype>
  94
  95       <funcprototype>
  96         <funcdef>int <function>sd_bus_add_object_vtable</function></funcdef>
  97         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  98         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
  99         <paramdef>const char *<parameter>path</parameter></paramdef>
 100         <paramdef>const char *<parameter>interface</parameter></paramdef>
 101         <paramdef>const sd_bus_vtable *<parameter>vtable</parameter></paramdef>
 102         <paramdef>void *<parameter>userdata</parameter></paramdef>
 103       </funcprototype>
 104
 105       <funcprototype>
 106         <funcdef>int <function>sd_bus_add_fallback_vtable</function></funcdef>
 107         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
 108         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
 109         <paramdef>const char *<parameter>prefix</parameter></paramdef>
 110         <paramdef>const char *<parameter>interface</parameter></paramdef>
 111         <paramdef>const sd_bus_vtable *<parameter>vtable</parameter></paramdef>
 112         <paramdef>sd_bus_object_find_t <parameter>find</parameter></paramdef>
 113         <paramdef>void *<parameter>userdata</parameter></paramdef>
 114       </funcprototype>
 115
 116       <funcprototype>
 117         <funcdef>int <function>sd_bus_add_filter</function></funcdef>
 118         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
 119         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
 120         <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
 121         <paramdef>void *<parameter>userdata</parameter></paramdef>
 122       </funcprototype>
 123
 124       <para>
 125         <constant>SD_BUS_VTABLE_START(<replaceable>flags</replaceable>)</constant>
 126       </para>
 127       <para>
 128         <constant>SD_BUS_VTABLE_END</constant>
 129       </para>
 130       <para>
 131         <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET(
 132         <replaceable>member</replaceable>,
 133         <replaceable>args</replaceable>,
 134         <replaceable>result</replaceable>,
 135         <replaceable>handler</replaceable>,
 136         <replaceable>offset</replaceable>,
 137         <replaceable>flags</replaceable>)
 138         </constant>
 139       </para>
 140       <para>
 141         <constant>SD_BUS_METHOD_WITH_ARGS(
 142         <replaceable>member</replaceable>,
 143         <replaceable>args</replaceable>,
 144         <replaceable>result</replaceable>,
 145         <replaceable>handler</replaceable>,
 146         <replaceable>flags</replaceable>)
 147         </constant>
 148       </para>
 149       <para>
 150         <constant>SD_BUS_METHOD_WITH_NAMES_OFFSET(
 151         <replaceable>member</replaceable>,
 152         <replaceable>signature</replaceable>,
 153         <replaceable>in_names</replaceable>,
 154         <replaceable>result</replaceable>,
 155         <replaceable>out_names</replaceable>,
 156         <replaceable>handler</replaceable>,
 157         <replaceable>offset</replaceable>,
 158         <replaceable>flags</replaceable>)
 159         </constant>
 160       </para>
 161       <para>
 162         <constant>SD_BUS_METHOD_WITH_NAMES(
 163         <replaceable>member</replaceable>,
 164         <replaceable>signature</replaceable>,
 165         <replaceable>in_names</replaceable>,
 166         <replaceable>result</replaceable>,
 167         <replaceable>out_names</replaceable>,
 168         <replaceable>handler</replaceable>,
 169         <replaceable>flags</replaceable>)
 170         </constant>
 171       </para>
 172       <para>
 173         <constant>SD_BUS_METHOD_WITH_OFFSET(
 174         <replaceable>member</replaceable>,
 175         <replaceable>signature</replaceable>,
 176         <replaceable>result</replaceable>,
 177         <replaceable>handler</replaceable>,
 178         <replaceable>offset</replaceable>,
 179         <replaceable>flags</replaceable>)
 180         </constant>
 181       </para>
 182       <para>
 183         <constant>SD_BUS_METHOD(
 184         <replaceable>member</replaceable>,
 185         <replaceable>signature</replaceable>,
 186         <replaceable>result</replaceable>,
 187         <replaceable>handler</replaceable>,
 188         <replaceable>flags</replaceable>)
 189         </constant>
 190       </para>
 191       <para>
 192         <constant>SD_BUS_SIGNAL_WITH_ARGS(
 193         <replaceable>member</replaceable>,
 194         <replaceable>args</replaceable>,
 195         <replaceable>flags</replaceable>)
 196         </constant>
 197       </para>
 198       <para>
 199         <constant>SD_BUS_SIGNAL_WITH_NAMES(
 200         <replaceable>member</replaceable>,
 201         <replaceable>signature</replaceable>,
 202         <replaceable>names</replaceable>,
 203         <replaceable>flags</replaceable>)
 204         </constant>
 205       </para>
 206       <para>
 207         <constant>SD_BUS_SIGNAL(
 208         <replaceable>member</replaceable>,
 209         <replaceable>signature</replaceable>,
 210         <replaceable>flags</replaceable>)
 211         </constant>
 212       </para>
 213       <para>
 214         <constant>SD_BUS_WRITABLE_PROPERTY(
 215         <replaceable>member</replaceable>,
 216         <replaceable>signature</replaceable>,
 217         <replaceable>get</replaceable>,
 218         <replaceable>set</replaceable>,
 219         <replaceable>offset</replaceable>,
 220         <replaceable>flags</replaceable>)
 221         </constant>
 222       </para>
 223       <para>
 224         <constant>SD_BUS_PROPERTY(
 225         <replaceable>member</replaceable>,
 226         <replaceable>signature</replaceable>,
 227         <replaceable>get</replaceable>,
 228         <replaceable>offset</replaceable>,
 229         <replaceable>flags</replaceable>)
 230         </constant>
 231       </para>
 232       <para>
 233         <constant>SD_BUS_PARAM(<replaceable>name</replaceable>)</constant>
 234         <constant>SD_BUS_ARGS(<replaceable>...</replaceable>)</constant>
 235         <constant>SD_BUS_RESULT(<replaceable>...</replaceable>)</constant>
 236         <constant>SD_BUS_NO_ARGS</constant>
 237         <constant>SD_BUS_NO_RESULT</constant>
 238       </para>
 239     </funcsynopsis>
 240   </refsynopsisdiv>
 241
 242   <refsect1>
 243     <title>Description</title>
 244
 245     <para><function>sd_bus_add_object_vtable()</function> is used to declare attributes for the
 246     object path <parameter>path</parameter> connected to the bus connection
 247     <parameter>bus</parameter> under the interface <parameter>interface</parameter>. The table
 248     <parameter>vtable</parameter> may contain property declarations using
 249     <constant>SD_BUS_PROPERTY()</constant> or <constant>SD_BUS_WRITABLE_PROPERTY()</constant>,
 250     method declarations using <constant>SD_BUS_METHOD()</constant>,
 251     <constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
 252     <constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, or
 253     <constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant>, and signal declarations using
 254     <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> or <constant>SD_BUS_SIGNAL()</constant>, see
 255     below. The <replaceable>userdata</replaceable> parameter contains a pointer that will be passed
 256     to various callback functions. It may be specified as <constant>NULL</constant> if no value is
 257     necessary. An interface can have any number of vtables attached to it.</para>
 258
 259     <para><function>sd_bus_add_fallback_vtable()</function> is similar to
 260     <function>sd_bus_add_object_vtable()</function>, but is used to register "fallback" attributes.
 261     When looking for an attribute declaration, bus object paths registered with
 262     <function>sd_bus_add_object_vtable()</function> are checked first. If no match is found, the
 263     fallback vtables are checked for each prefix of the bus object path, i.e. with the last
 264     slash-separated components successively removed. This allows the vtable to be used for an
 265     arbitrary number of dynamically created objects.</para>
 266
 267     <para>Parameter <replaceable>find</replaceable> is a function which is used to locate the target
 268     object based on the bus object path <replaceable>path</replaceable>. It must return
 269     <constant>1</constant> and set the <parameter>ret_found</parameter> output parameter if the
 270     object is found, return <constant>0</constant> if the object was not found, and return a
 271     negative errno-style error code or initialize the error structure
 272     <replaceable>ret_error</replaceable> on error. The pointer passed in
 273     <parameter>ret_found</parameter> will be used as the <parameter>userdata</parameter> parameter
 274     for the callback functions (offset by the <parameter>offset</parameter> offsets as specified in
 275     the vtable entries).</para>
 276
 277     <para><function>sd_bus_add_object()</function> attaches a callback directly to the object path
 278     <parameter>path</parameter>. An object path can have any number of callbacks attached to it.
 279     Each callback is prepended to the list of callbacks which are always called in order.
 280     <function>sd_bus_add_fallback()</function> is similar to
 281     <function>sd_bus_add_object()</function> but applies to fallback paths instead.</para>
 282
 283     <para><function>sd_bus_add_filter()</function> installs a callback that is invoked for each
 284     incoming D-Bus message. Filters can be used to handle logic common to all messages received by
 285     a service (e.g. authentication or authorization).</para>
 286
 287     <para>When a request is received, any associated callbacks are called sequentially until a
 288     callback returns a non-zero integer. Return zero from a callback to give other callbacks the
 289     chance to process the request. Callbacks are called in the following order: first, global
 290     callbacks installed with <function>sd_bus_add_filter()</function> are called. Second, callbacks
 291     attached directly to the request object path are called, followed by any D-Bus method callbacks
 292     attached to the request object path, interface and member. Finally, the property callbacks
 293     attached to the request object path, interface and member are called. If the final callback
 294     returns zero, an error reply is sent back to the caller indicating no matching object for the
 295     request was found.</para>
 296
 297     <para>Note that you can return a positive integer from a callback without
 298     immediately sending a reply. This informs sd-bus this callback will take responsibility for
 299     replying to the request without forcing the callback to produce a reply immediately. This allows
 300     a callback to perform any number of asynchronous operations required to construct a reply.
 301     However, if producing a reply takes too long, the method call will time out at the caller.</para>
 302
 303     <para>If a callback was invoked to handle a request that expects a reply and the callback
 304     returns a negative value, the value is interpreted as a negative errno-style error code and sent
 305     back to the caller as a D-Bus error as if
 306     <citerefentry><refentrytitle>sd_bus_reply_method_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 307     was called. Additionally, all callbacks take a <structname>sd_bus_error</structname> output
 308     parameter that can be used to provide more detailed error information. If
 309     <parameter>ret_error</parameter> is set when the callback finishes, the corresponding D-Bus
 310     error is sent back to the caller as if
 311     <citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 312     was called. Any error stored in <parameter>ret_error</parameter> takes priority over any
 313     negative values returned by the same callback when determining which error to send back to
 314     the caller. Use
 315     <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 316     or one of its variants to set <parameter>ret_error</parameter> and return a negative integer
 317     from a callback with a single function call. To send an error reply after a callback has already
 318     finished, use
 319     <citerefentry><refentrytitle>sd_bus_reply_method_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 320     or one of its variants.</para>
 321
 322     <para>For all functions, a match slot is created internally. If the output parameter
 323     <replaceable>slot</replaceable> is <constant>NULL</constant>, a "floating" slot object is
 324     created, see
 325     <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 326     Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot
 327     object should be dropped when the vtable is not needed anymore, see
 328     <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 329     </para>
 330
 331     <refsect2>
 332       <title>The <structname>sd_bus_vtable</structname> array</title>
 333
 334       <para>The array consists of the structures of type <structname>sd_bus_vtable</structname>, but it
 335       should never be filled in manually, but through one of the following macros:</para>
 336
 337       <variablelist>
 338         <varlistentry>
 339           <term><constant>SD_BUS_VTABLE_START()</constant></term>
 340           <term><constant>SD_BUS_VTABLE_END</constant></term>
 341
 342           <listitem><para>Those must always be the first and last element.</para></listitem>
 343         </varlistentry>
 344
 345         <varlistentry>
 346           <term><constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant></term>
 347           <term><constant>SD_BUS_METHOD_WITH_ARGS()</constant></term>
 348
 349           <listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>,
 350           arguments <replaceable>args</replaceable> and result <replaceable>result</replaceable>.
 351           <replaceable>args</replaceable> expects a sequence of argument type/name pairs wrapped in the
 352           <constant>SD_BUS_ARGS()</constant> macro. The elements at even indices in this list describe the
 353           types of the method's arguments. The method's parameter signature is the concatenation of all the
 354           string literals at even indices in <replaceable>args</replaceable>. If a method has no parameters,
 355           pass <constant>SD_BUS_NO_ARGS</constant> to <replaceable>args</replaceable>. The elements at uneven
 356           indices describe the names of the method's arguments. <replaceable>result</replaceable> expects a
 357           sequence of type/name pairs wrapped in the <constant>SD_BUS_RESULT()</constant> macro in the same
 358           format as <constant>SD_BUS_ARGS()</constant>. The method's result signature is the concatenation of
 359           all the string literals at even indices in <replaceable>result</replaceable>. If a method has no
 360           result, pass <constant>SD_BUS_NO_RESULT</constant> to <replaceable>result</replaceable>. Note that
 361           argument types are expected to be quoted string literals and argument names are expected to be
 362           unquoted string literals. See below for a complete example.</para>
 363
 364           <para>The handler function <replaceable>handler</replaceable> must be of type
 365           <function>sd_bus_message_handler_t</function>. It will be called to handle the incoming messages
 366           that call this method. It receives a pointer that is the <replaceable>userdata</replaceable>
 367           parameter passed to the registration function offset by <replaceable>offset</replaceable> bytes.
 368           This may be used to pass pointers to different fields in the same data structure to different
 369           methods in the same vtable. To send a reply from <parameter>handler</parameter>, call
 370           <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 371           with the message the callback was invoked with. Parameter <replaceable>flags</replaceable> is a
 372           combination of flags, see below.</para>
 373
 374           <para><constant>SD_BUS_METHOD_WITH_ARGS()</constant> is a shorthand for calling
 375           <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant> with an offset of zero.</para>
 376           </listitem>
 377         </varlistentry>
 378
 379         <varlistentry>
 380           <term><constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant></term>
 381           <term><constant>SD_BUS_METHOD_WITH_NAMES()</constant></term>
 382           <term><constant>SD_BUS_METHOD_WITH_OFFSET()</constant></term>
 383           <term><constant>SD_BUS_METHOD()</constant></term>
 384
 385           <listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>,
 386           parameter signature <replaceable>signature</replaceable>, result signature
 387           <replaceable>result</replaceable>. Parameters <replaceable>in_names</replaceable> and
 388           <replaceable>out_names</replaceable> specify the argument names of the input and output
 389           arguments in the function signature. <replaceable>in_names</replaceable> and
 390           <replaceable>out_names</replaceable> should be created using the
 391           <constant>SD_BUS_PARAM()</constant> macro, see below. In all other regards, this macro behaves
 392           exactly the same as <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant>.</para>
 393
 394           <para><constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
 395           <constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant>
 396           are variants which specify zero offset (<replaceable>userdata</replaceable> parameter is
 397           passed with no change), leave the names unset (i.e. no parameter names), or both.</para>
 398
 399           <para>Prefer using <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant> and
 400           <constant>SD_BUS_METHOD_WITH_ARGS()</constant> over these macros as they allow specifying argument
 401           types and names next to each other which is less error-prone than first specifying all argument
 402           types followed by specifying all argument names.</para>
 403           </listitem>
 404         </varlistentry>
 405
 406         <varlistentry>
 407           <term><constant>SD_BUS_SIGNAL_WITH_ARGS()</constant></term>
 408
 409           <listitem><para>Declare a D-Bus signal with the name <replaceable>member</replaceable> and
 410           arguments <replaceable>args</replaceable>. <replaceable>args</replaceable> expects a sequence of
 411           argument type/name pairs wrapped in the <constant>SD_BUS_ARGS()</constant> macro. The elements at
 412           even indices in this list describe the types of the signal's arguments. The signal's parameter
 413           signature is the concatenation of all the string literals at even indices in
 414           <replaceable>args</replaceable>. If a signal has no parameters, pass
 415           <constant>SD_BUS_NO_ARGS</constant> to <replaceable>args</replaceable>. The elements at uneven
 416           indices describe the names of the signal's arguments. Parameter <replaceable>flags</replaceable> is
 417           a combination of flags. See below for a complete example.</para></listitem>
 418         </varlistentry>
 419
 420         <varlistentry>
 421           <term><constant>SD_BUS_SIGNAL_WITH_NAMES()</constant></term>
 422           <term><constant>SD_BUS_SIGNAL()</constant></term>
 423
 424           <listitem><para>Declare a D-Bus signal with the name <replaceable>member</replaceable>,
 425           parameter signature <replaceable>signature</replaceable>, and argument names
 426           <replaceable>names</replaceable>. <replaceable>names</replaceable> should be
 427           created using the <constant>SD_BUS_PARAM()</constant> macro, see below.
 428           Parameter <replaceable>flags</replaceable> is a combination of flags, see below.
 429           </para>
 430
 431           <para><constant>SD_BUS_SIGNAL()</constant> is equivalent to
 432           <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> with the <replaceable>names</replaceable> parameter
 433           unset (i.e. no parameter names).</para>
 434
 435           <para>Prefer using <constant>SD_BUS_SIGNAL_WITH_ARGS()</constant> over these macros as it allows
 436           specifying argument types and names next to each other which is less error-prone than first
 437           specifying all argument types followed by specifying all argument names.</para>
 438           </listitem>
 439         </varlistentry>
 440
 441         <varlistentry>
 442           <term><constant>SD_BUS_WRITABLE_PROPERTY()</constant></term>
 443           <term><constant>SD_BUS_PROPERTY()</constant></term>
 444
 445           <listitem><para>Declare a D-Bus property with the name <replaceable>member</replaceable>
 446           and value signature <replaceable>signature</replaceable>. Parameters
 447           <replaceable>get</replaceable> and <replaceable>set</replaceable> are the getter and
 448           setter methods. They are called with a pointer that is the
 449           <replaceable>userdata</replaceable> parameter passed to the registration function offset
 450           by <replaceable>offset</replaceable> bytes. This may be used pass pointers to different
 451           fields in the same data structure to different setters and getters in the same vtable.
 452           Parameter <replaceable>flags</replaceable> is a combination of flags, see below.</para>
 453
 454           <para>The setter and getter methods may be omitted (specified as
 455           <constant>NULL</constant>), if the property is one of the basic types or
 456           <literal>as</literal> in case of read-only properties. In those cases, the
 457           <replaceable>userdata</replaceable> and <replaceable>offset</replaceable> parameters must
 458           together point to a valid variable of the corresponding type. A default setter and getter
 459           will be provided, which simply copy the argument between this variable and the message.
 460           </para>
 461
 462           <para><constant>SD_BUS_PROPERTY()</constant> is used to define a read-only property.
 463           </para></listitem>
 464         </varlistentry>
 465
 466         <varlistentry>
 467           <term><constant>SD_BUS_PARAM()</constant></term>
 468           <listitem><para>Parameter names should be wrapped in this macro, see the example below.
 469           </para></listitem>
 470         </varlistentry>
 471       </variablelist>
 472     </refsect2>
 473
 474     <refsect2>
 475       <title>Flags</title>
 476
 477       <para>The <replaceable>flags</replaceable> parameter is used to specify a combination of
 478       <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus annotations</ulink>.
 479       </para>
 480
 481       <variablelist>
 482         <varlistentry>
 483           <term><constant>SD_BUS_VTABLE_DEPRECATED</constant></term>
 484
 485           <listitem><para>Mark this vtable entry as deprecated using the
 486           <constant>org.freedesktop.DBus.Deprecated</constant> annotation in introspection data. If
 487           specified for <constant>SD_BUS_VTABLE_START()</constant>, the annotation is applied to the
 488           enclosing interface.</para></listitem>
 489         </varlistentry>
 490
 491         <varlistentry>
 492           <term><constant>SD_BUS_VTABLE_HIDDEN</constant></term>
 493
 494           <listitem><para>Make this vtable entry hidden. It will not be shown in introspection data.
 495           If specified for <constant>SD_BUS_VTABLE_START()</constant>, all entries in the array are
 496           hidden.</para></listitem>
 497         </varlistentry>
 498
 499         <varlistentry>
 500           <term><constant>SD_BUS_VTABLE_UNPRIVILEGED</constant></term>
 501
 502           <listitem><para>Mark this vtable entry as unprivileged. If not specified, the
 503           <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
 504           <literal>true</literal> will be shown in introspection data.</para></listitem>
 505         </varlistentry>
 506
 507         <varlistentry>
 508           <term><constant>SD_BUS_VTABLE_METHOD_NO_REPLY</constant></term>
 509
 510           <listitem><para>Mark his vtable entry as a method that will not return a reply using the
 511           <constant>org.freedesktop.DBus.Method.NoReply</constant> annotation in introspection data.
 512           </para></listitem>
 513         </varlistentry>
 514
 515         <varlistentry>
 516           <term><constant>SD_BUS_VTABLE_PROPERTY_CONST</constant></term>
 517           <term><constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant></term>
 518           <term><constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant></term>
 519
 520           <listitem><para>Those three flags correspond to different values of the
 521           <constant>org.freedesktop.DBus.Property.EmitsChangedSignal</constant> annotation, which
 522           specifies whether the
 523           <constant>org.freedesktop.DBus.Properties.PropertiesChanged</constant> signal is emitted
 524           whenever the property changes. <constant>SD_BUS_VTABLE_PROPERTY_CONST</constant>
 525           corresponds to <constant>const</constant> and means that the property never changes during
 526           the lifetime of the object it belongs to, so no signal needs to be emitted.
 527           <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant> corresponds to
 528           <constant>true</constant> and means that the signal is emitted.
 529           <constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant> corresponds to
 530           <constant>invalidates</constant> and means that the signal is emitted, but the value is
 531           not included in the signal.</para></listitem>
 532         </varlistentry>
 533
 534         <varlistentry>
 535           <term><constant>SD_BUS_VTABLE_PROPERTY_EXPLICIT</constant></term>
 536
 537           <listitem><para>Mark this vtable property entry as requiring explicit request to for the
 538           value to be shown (generally because the value is large or slow to calculate). This entry
 539           cannot be combined with <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant>, and will
 540           not be shown in property listings by default (e.g. <command>busctl introspect</command>).
 541           This corresponds to the <constant>org.freedesktop.systemd1.Explicit</constant> annotation
 542           in introspection data.</para></listitem>
 543         </varlistentry>
 544
 545         <varlistentry>
 546           <term><constant>SD_BUS_VTABLE_SENSITIVE</constant></term>
 547
 548           <listitem><para>Mark this vtable method entry as processing sensitive data. When set,
 549           incoming method call messages and their outgoing reply messages are marked as sensitive using
 550           <citerefentry><refentrytitle>sd_bus_message_sensitive</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 551           so that they are erased from memory when freed.</para></listitem>
 552         </varlistentry>
 553
 554         <varlistentry>
 555           <term><constant>SD_BUS_VTABLE_ABSOLUTE_OFFSET</constant></term>
 556
 557           <listitem><para>Mark this vtable method or property entry so that the user data pointer passed to
 558           its associated handler functions is determined slightly differently: instead of adding the offset
 559           parameter of the entry to the user data pointer specified during vtable registration, the offset is
 560           passed directly, converted to a pointer, without taking the user data pointer specified during
 561           vtable registration into account.</para></listitem>
 562         </varlistentry>
 563       </variablelist>
 564     </refsect2>
 565   </refsect1>
 566
 567   <refsect1>
 568     <title>Examples</title>
 569
 570     <example>
 571       <title>Create a simple listener on the bus</title>
 572
 573       <programlisting><xi:include href="vtable-example.c" parse="text" /></programlisting>
 574
 575       <para>This creates a simple client on the bus (the user bus, when run as normal user). We may
 576       use the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> call to
 577       acquire the XML description of the interface:</para>
 578
 579       <programlisting><xi:include href="vtable-example.xml" parse="text" /></programlisting>
 580     </example>
 581   </refsect1>
 582
 583   <refsect1>
 584     <title>Return Value</title>
 585
 586     <para>On success, <function>sd_bus_add_object_vtable()</function> and
 587     <function>sd_bus_add_fallback_vtable()</function> return a non-negative integer. On
 588     failure, they return a negative errno-style error code.</para>
 589
 590     <refsect2>
 591       <title>Errors</title>
 592
 593       <para>Returned errors may indicate the following problems:</para>
 594
 595       <variablelist>
 596         <varlistentry>
 597           <term><constant>-EINVAL</constant></term>
 598
 599           <listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. A
 600           reserved D-Bus interface was passed as the <replaceable>interface</replaceable> parameter.
 601           </para></listitem>
 602         </varlistentry>
 603
 604         <varlistentry>
 605           <term><constant>-ENOPKG</constant></term>
 606
 607           <listitem><para>The bus cannot be resolved.</para></listitem>
 608         </varlistentry>
 609
 610         <varlistentry>
 611           <term><constant>-ECHILD</constant></term>
 612
 613           <listitem><para>The bus was created in a different process.</para></listitem>
 614         </varlistentry>
 615
 616         <varlistentry>
 617           <term><constant>-ENOMEM</constant></term>
 618
 619           <listitem><para>Memory allocation failed.</para></listitem>
 620         </varlistentry>
 621
 622         <varlistentry>
 623           <term><constant>-EPROTOTYPE</constant></term>
 624
 625           <listitem><para><function>sd_bus_add_object_vtable()</function> and
 626           <function>sd_bus_add_fallback_vtable()</function> have been both called for the same bus
 627           object path, which is not allowed.</para></listitem>
 628         </varlistentry>
 629
 630         <varlistentry>
 631           <term><constant>-EEXIST</constant></term>
 632
 633           <listitem><para>This vtable has already been registered for this
 634           <replaceable>interface</replaceable> and <replaceable>path</replaceable>.
 635           </para></listitem>
 636         </varlistentry>
 637       </variablelist>
 638     </refsect2>
 639   </refsect1>
 640
 641   <xi:include href="libsystemd-pkgconfig.xml" />
 642
 643   <refsect1>
 644     <title>See Also</title>
 645
 646     <para>
 647       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 648       <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 649       <citerefentry><refentrytitle>sd_bus_emit_properties_changed</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 650       <citerefentry><refentrytitle>sd_bus_emit_object_added</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 651     </para>
 652   </refsect1>
 653 </refentry>