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