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