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_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 <systemd/sd-bus-vtable.h></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 125 <para> 126 <constant>SD_BUS_VTABLE_CAPABILITY(<replaceable>capability</replaceable>)</constant> 127 </para> 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(<replaceable>member</replaceable>, 137 <replaceable>args</replaceable>, 138 <replaceable>result</replaceable>, 139 <replaceable>handler</replaceable>, 140 <replaceable>offset</replaceable>, 141 <replaceable>flags</replaceable>) 142 </constant> 143 </para> 144 <para> 145 <constant>SD_BUS_METHOD_WITH_ARGS(<replaceable>member</replaceable>, 146 <replaceable>args</replaceable>, 147 <replaceable>result</replaceable>, 148 <replaceable>handler</replaceable>, 149 <replaceable>flags</replaceable>) 150 </constant> 151 </para> 152 <para> 153 <constant>SD_BUS_METHOD_WITH_NAMES_OFFSET(<replaceable>member</replaceable>, 154 <replaceable>signature</replaceable>, 155 <replaceable>in_names</replaceable>, 156 <replaceable>result</replaceable>, 157 <replaceable>out_names</replaceable>, 158 <replaceable>handler</replaceable>, 159 <replaceable>offset</replaceable>, 160 <replaceable>flags</replaceable>) 161 </constant> 162 </para> 163 <para> 164 <constant>SD_BUS_METHOD_WITH_NAMES(<replaceable>member</replaceable>, 165 <replaceable>signature</replaceable>, 166 <replaceable>in_names</replaceable>, 167 <replaceable>result</replaceable>, 168 <replaceable>out_names</replaceable>, 169 <replaceable>handler</replaceable>, 170 <replaceable>flags</replaceable>) 171 </constant> 172 </para> 173 <para> 174 <constant>SD_BUS_METHOD_WITH_OFFSET(<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(<replaceable>member</replaceable>, 184 <replaceable>signature</replaceable>, 185 <replaceable>result</replaceable>, 186 <replaceable>handler</replaceable>, 187 <replaceable>flags</replaceable>) 188 </constant> 189 </para> 190 <para> 191 <constant>SD_BUS_SIGNAL_WITH_ARGS(<replaceable>member</replaceable>, 192 <replaceable>args</replaceable>, 193 <replaceable>flags</replaceable>) 194 </constant> 195 </para> 196 <para> 197 <constant>SD_BUS_SIGNAL_WITH_NAMES(<replaceable>member</replaceable>, 198 <replaceable>signature</replaceable>, 199 <replaceable>names</replaceable>, 200 <replaceable>flags</replaceable>) 201 </constant> 202 </para> 203 <para> 204 <constant>SD_BUS_SIGNAL(<replaceable>member</replaceable>, 205 <replaceable>signature</replaceable>, 206 <replaceable>flags</replaceable>) 207 </constant> 208 </para> 209 <para> 210 <constant>SD_BUS_WRITABLE_PROPERTY(<replaceable>member</replaceable>, 211 <replaceable>signature</replaceable>, 212 <replaceable>get</replaceable>, 213 <replaceable>set</replaceable>, 214 <replaceable>offset</replaceable>, 215 <replaceable>flags</replaceable>) 216 </constant> 217 </para> 218 <para> 219 <constant>SD_BUS_PROPERTY(<replaceable>member</replaceable>, 220 <replaceable>signature</replaceable>, 221 <replaceable>get</replaceable>, 222 <replaceable>offset</replaceable>, 223 <replaceable>flags</replaceable>) 224 </constant> 225 </para> 226 <para> 227 <constant>SD_BUS_PARAM(<replaceable>name</replaceable>)</constant> 228 </para> 229 <para> 230 <constant>SD_BUS_ARGS(<replaceable>...</replaceable>)</constant> 231 </para> 232 <para> 233 <constant>SD_BUS_RESULT(<replaceable>...</replaceable>)</constant> 234 </para> 235 <para> 236 <constant>SD_BUS_NO_ARGS</constant> 237 </para> 238 <para> 239 <constant>SD_BUS_NO_RESULT</constant> 240 </para> 241 </funcsynopsis> 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 </listitem> 382 </varlistentry> 383 384 <varlistentry> 385 <term><constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant></term> 386 <term><constant>SD_BUS_METHOD_WITH_NAMES()</constant></term> 387 <term><constant>SD_BUS_METHOD_WITH_OFFSET()</constant></term> 388 <term><constant>SD_BUS_METHOD()</constant></term> 389 390 <listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>, 391 parameter signature <replaceable>signature</replaceable>, result signature 392 <replaceable>result</replaceable>. Parameters <replaceable>in_names</replaceable> and 393 <replaceable>out_names</replaceable> specify the argument names of the input and output 394 arguments in the function signature. <replaceable>in_names</replaceable> and 395 <replaceable>out_names</replaceable> should be created using the 396 <constant>SD_BUS_PARAM()</constant> macro, see below. In all other regards, this macro behaves 397 exactly the same as <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant>.</para> 398 399 <para><constant>SD_BUS_METHOD_WITH_NAMES()</constant>, 400 <constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant> 401 are variants which specify zero offset (<replaceable>userdata</replaceable> parameter is 402 passed with no change), leave the names unset (i.e. no parameter names), or both.</para> 403 404 <para>Prefer using <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant> and 405 <constant>SD_BUS_METHOD_WITH_ARGS()</constant> over these macros as they allow specifying argument 406 types and names next to each other which is less error-prone than first specifying all argument 407 types followed by specifying all argument names.</para> 408 </listitem> 409 </varlistentry> 410 411 <varlistentry> 412 <term><constant>SD_BUS_SIGNAL_WITH_ARGS()</constant></term> 413 414 <listitem><para>Declare a D-Bus signal with the name <replaceable>member</replaceable> and 415 arguments <replaceable>args</replaceable>. <replaceable>args</replaceable> expects a sequence of 416 argument type/name pairs wrapped in the <constant>SD_BUS_ARGS()</constant> macro. The elements at 417 even indices in this list describe the types of the signal's arguments. The signal's parameter 418 signature is the concatenation of all the string literals at even indices in 419 <replaceable>args</replaceable>. If a signal has no parameters, pass 420 <constant>SD_BUS_NO_ARGS</constant> to <replaceable>args</replaceable>. The elements at uneven 421 indices describe the names of the signal's arguments. Parameter <replaceable>flags</replaceable> is 422 a combination of flags. See below for a complete example.</para></listitem> 423 </varlistentry> 424 425 <varlistentry> 426 <term><constant>SD_BUS_SIGNAL_WITH_NAMES()</constant></term> 427 <term><constant>SD_BUS_SIGNAL()</constant></term> 428 429 <listitem><para>Declare a D-Bus signal with the name <replaceable>member</replaceable>, 430 parameter signature <replaceable>signature</replaceable>, and argument names 431 <replaceable>names</replaceable>. <replaceable>names</replaceable> should be 432 created using the <constant>SD_BUS_PARAM()</constant> macro, see below. 433 Parameter <replaceable>flags</replaceable> is a combination of flags, see below. 434 </para> 435 436 <para><constant>SD_BUS_SIGNAL()</constant> is equivalent to 437 <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> with the <replaceable>names</replaceable> parameter 438 unset (i.e. no parameter names).</para> 439 440 <para>Prefer using <constant>SD_BUS_SIGNAL_WITH_ARGS()</constant> over these macros as it allows 441 specifying argument types and names next to each other which is less error-prone than first 442 specifying all argument types followed by specifying all argument names.</para> 443 </listitem> 444 </varlistentry> 445 446 <varlistentry> 447 <term><constant>SD_BUS_WRITABLE_PROPERTY()</constant></term> 448 <term><constant>SD_BUS_PROPERTY()</constant></term> 449 450 <listitem><para>Declare a D-Bus property with the name <replaceable>member</replaceable> 451 and value signature <replaceable>signature</replaceable>. Parameters 452 <replaceable>get</replaceable> and <replaceable>set</replaceable> are the getter and 453 setter methods. They are called with a pointer that is the 454 <replaceable>userdata</replaceable> parameter passed to the registration function offset 455 by <replaceable>offset</replaceable> bytes. This may be used pass pointers to different 456 fields in the same data structure to different setters and getters in the same vtable. 457 Parameter <replaceable>flags</replaceable> is a combination of flags, see below.</para> 458 459 <para>The setter and getter methods may be omitted (specified as 460 <constant>NULL</constant>), if the property is one of the basic types or 461 <literal>as</literal> in case of read-only properties. In those cases, the 462 <replaceable>userdata</replaceable> and <replaceable>offset</replaceable> parameters must 463 together point to a valid variable of the corresponding type. A default setter and getter 464 will be provided, which simply copy the argument between this variable and the message. 465 </para> 466 467 <para><constant>SD_BUS_PROPERTY()</constant> is used to define a read-only property. 468 </para></listitem> 469 </varlistentry> 470 471 <varlistentry> 472 <term><constant>SD_BUS_PARAM()</constant></term> 473 <listitem><para>Parameter names should be wrapped in this macro, see the example below. 474 </para></listitem> 475 </varlistentry> 476 </variablelist> 477 </refsect2> 478 479 <refsect2> 480 <title>Flags</title> 481 482 <para>The <replaceable>flags</replaceable> parameter is used to specify a combination of 483 <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus annotations</ulink>. 484 </para> 485 486 <variablelist> 487 <varlistentry> 488 <term><constant>SD_BUS_VTABLE_DEPRECATED</constant></term> 489 490 <listitem><para>Mark this vtable entry as deprecated using the 491 <constant>org.freedesktop.DBus.Deprecated</constant> annotation in introspection data. If 492 specified for <constant>SD_BUS_VTABLE_START()</constant>, the annotation is applied to the 493 enclosing interface.</para></listitem> 494 </varlistentry> 495 496 <varlistentry> 497 <term><constant>SD_BUS_VTABLE_HIDDEN</constant></term> 498 499 <listitem><para>Make this vtable entry hidden. It will not be shown in introspection data. 500 If specified for <constant>SD_BUS_VTABLE_START()</constant>, all entries in the array are 501 hidden.</para></listitem> 502 </varlistentry> 503 504 <varlistentry> 505 <term><constant>SD_BUS_VTABLE_METHOD_NO_REPLY</constant></term> 506 507 <listitem><para>Mark this vtable entry as a method that will not return a reply using the 508 <constant>org.freedesktop.DBus.Method.NoReply</constant> annotation in introspection data. 509 </para></listitem> 510 </varlistentry> 511 512 <varlistentry> 513 <term><constant>SD_BUS_VTABLE_PROPERTY_CONST</constant></term> 514 <term><constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant></term> 515 <term><constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant></term> 516 517 <listitem><para>Those three flags correspond to different values of the 518 <constant>org.freedesktop.DBus.Property.EmitsChangedSignal</constant> annotation, which 519 specifies whether the 520 <constant>org.freedesktop.DBus.Properties.PropertiesChanged</constant> signal is emitted 521 whenever the property changes. <constant>SD_BUS_VTABLE_PROPERTY_CONST</constant> 522 corresponds to <constant>const</constant> and means that the property never changes during 523 the lifetime of the object it belongs to, so no signal needs to be emitted. 524 <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant> corresponds to 525 <constant>true</constant> and means that the signal is emitted. 526 <constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant> corresponds to 527 <constant>invalidates</constant> and means that the signal is emitted, but the value is 528 not included in the signal.</para></listitem> 529 </varlistentry> 530 531 <varlistentry> 532 <term><constant>SD_BUS_VTABLE_PROPERTY_EXPLICIT</constant></term> 533 534 <listitem><para>Mark this vtable property entry as requiring explicit request to for the 535 value to be shown (generally because the value is large or slow to calculate). This entry 536 cannot be combined with <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant>, and will 537 not be shown in property listings by default (e.g. <command>busctl introspect</command>). 538 This corresponds to the <constant>org.freedesktop.systemd1.Explicit</constant> annotation 539 in introspection data.</para></listitem> 540 </varlistentry> 541 542 <varlistentry> 543 <term><constant>SD_BUS_VTABLE_SENSITIVE</constant></term> 544 545 <listitem><para>Mark this vtable method entry as processing sensitive data. When set, 546 incoming method call messages and their outgoing reply messages are marked as sensitive using 547 <citerefentry><refentrytitle>sd_bus_message_sensitive</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 548 so that they are erased from memory when freed.</para></listitem> 549 </varlistentry> 550 551 <varlistentry> 552 <term><constant>SD_BUS_VTABLE_ABSOLUTE_OFFSET</constant></term> 553 554 <listitem><para>Mark this vtable method or property entry so that the user data pointer passed to 555 its associated handler functions is determined slightly differently: instead of adding the offset 556 parameter of the entry to the user data pointer specified during vtable registration, the offset is 557 passed directly, converted to a pointer, without taking the user data pointer specified during 558 vtable registration into account.</para></listitem> 559 </varlistentry> 560 561 <varlistentry> 562 <term><constant>SD_BUS_VTABLE_CAPABILITY(<replaceable>capability</replaceable>)</constant></term> 563 564 <listitem><para>Access to this vtable entry will be allowed if the calling process has the 565 capability <replaceable>capability</replaceable>, as described in 566 <citerefentry><refentrytitle>sd_bus_query_sender_privilege</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 567 If used for <constant>SD_BUS_VTABLE_START()</constant>, provides a default for all entries in the 568 array. If not specified, either for an individual entry or the whole array, 569 <constant>CAP_SYS_ADMIN</constant> is checked by default. See <citerefentry 570 project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> 571 for information about capabilities.</para> 572 573 <para>Note that vtable entries may be marked as unprivileged and the whole bus may be marked as 574 trusted, see the discussion of <constant>SD_BUS_VTABLE_UNPRIVILEGED</constant> below.</para> 575 </listitem> 576 </varlistentry> 577 578 <varlistentry> 579 <term><constant>SD_BUS_VTABLE_UNPRIVILEGED</constant></term> 580 581 <listitem><para>Mark this vtable entry as unprivileged. Access to privileged entries is limited to 582 users with appropriate capabilities as described above. In practice many vtable entries are marked 583 as unprivileged, and either are open to everyone, or the decision whether to allow access is taken 584 later, e.g. by delegating to <ulink 585 url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para> 586 587 <para>The whole bus may be marked as trusted, in which case annotations at the entry level are 588 ignored, see 589 <citerefentry><refentrytitle>sd_bus_set_trusted</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 590 </para> 591 592 <para>When <emphasis>not</emphasis> specified, the 593 <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value 594 <literal>true</literal> will be shown in introspection data.</para> 595 596 <para>Note that this page describes checks implemented in the D-Bus client. The D-Bus server has an 597 additional policy that may permit or deny connections, see 598 "CONFIGURATION FILE" in 599 <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>. 600 </para></listitem> 601 </varlistentry> 602 </variablelist> 603 </refsect2> 604 </refsect1> 605 606 <refsect1> 607 <title>Examples</title> 608 609 <example> 610 <title>Create a simple listener on the bus</title> 611 612 <programlisting><xi:include href="vtable-example.c" parse="text" /></programlisting> 613 614 <para>This creates a simple client on the bus (the user bus, when run as normal user). We may 615 use the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> call to 616 acquire the XML description of the interface:</para> 617 618 <programlisting><xi:include href="vtable-example.xml" parse="text" /></programlisting> 619 </example> 620 </refsect1> 621 622 <refsect1> 623 <title>Return Value</title> 624 625 <para>On success, <function>sd_bus_add_object_vtable()</function> and 626 <function>sd_bus_add_fallback_vtable()</function> return a non-negative integer. On 627 failure, they return a negative errno-style error code.</para> 628 629 <refsect2> 630 <title>Errors</title> 631 632 <para>Returned errors may indicate the following problems:</para> 633 634 <variablelist> 635 <varlistentry> 636 <term><constant>-EINVAL</constant></term> 637 638 <listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. A 639 reserved D-Bus interface was passed as the <replaceable>interface</replaceable> parameter. 640 </para></listitem> 641 </varlistentry> 642 643 <varlistentry> 644 <term><constant>-ENOPKG</constant></term> 645 646 <listitem><para>The bus cannot be resolved.</para></listitem> 647 </varlistentry> 648 649 <varlistentry> 650 <term><constant>-ECHILD</constant></term> 651 652 <listitem><para>The bus was created in a different process.</para></listitem> 653 </varlistentry> 654 655 <varlistentry> 656 <term><constant>-ENOMEM</constant></term> 657 658 <listitem><para>Memory allocation failed.</para></listitem> 659 </varlistentry> 660 661 <varlistentry> 662 <term><constant>-EPROTOTYPE</constant></term> 663 664 <listitem><para><function>sd_bus_add_object_vtable()</function> and 665 <function>sd_bus_add_fallback_vtable()</function> have been both called for the same bus 666 object path, which is not allowed.</para></listitem> 667 </varlistentry> 668 669 <varlistentry> 670 <term><constant>-EEXIST</constant></term> 671 672 <listitem><para>This vtable has already been registered for this 673 <replaceable>interface</replaceable> and <replaceable>path</replaceable>. 674 </para></listitem> 675 </varlistentry> 676 </variablelist> 677 </refsect2> 678 </refsect1> 679 680 <xi:include href="libsystemd-pkgconfig.xml" /> 681 682 <refsect1> 683 <title>See Also</title> 684 685 <para> 686 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 687 <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 688 <citerefentry><refentrytitle>sd_bus_emit_properties_changed</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 689 <citerefentry><refentrytitle>sd_bus_emit_object_added</refentrytitle><manvolnum>3</manvolnum></citerefentry> 690 </para> 691 </refsect1> 692</refentry> 693