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