<funcsynopsis>
<funcsynopsisinfo>#include <systemd/sd-bus-vtable.h></funcsynopsisinfo>
- <funcprototype>
- <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
- <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
- <paramdef>void *<parameter>userdata</parameter></paramdef>
- <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
- </funcprototype>
+ <xi:include href="sd_bus_add_match.xml" xpointer="sd_bus_message_handler_t"/>
<funcprototype>
<funcdef>typedef int (*<function>sd_bus_property_get_t</function>)</funcdef>
<para>
<constant>SD_BUS_VTABLE_END</constant>
</para>
+ <para>
+ <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET(
+ <replaceable>member</replaceable>,
+ <replaceable>args</replaceable>,
+ <replaceable>result</replaceable>,
+ <replaceable>handler</replaceable>,
+ <replaceable>offset</replaceable>,
+ <replaceable>flags</replaceable>)
+ </constant>
+ </para>
+ <para>
+ <constant>SD_BUS_METHOD_WITH_ARGS(
+ <replaceable>member</replaceable>,
+ <replaceable>args</replaceable>,
+ <replaceable>result</replaceable>,
+ <replaceable>handler</replaceable>,
+ <replaceable>flags</replaceable>)
+ </constant>
+ </para>
<para>
<constant>SD_BUS_METHOD_WITH_NAMES_OFFSET(
<replaceable>member</replaceable>,
<replaceable>flags</replaceable>)
</constant>
</para>
+ <para>
+ <constant>SD_BUS_SIGNAL_WITH_ARGS(
+ <replaceable>member</replaceable>,
+ <replaceable>args</replaceable>,
+ <replaceable>flags</replaceable>)
+ </constant>
+ </para>
<para>
<constant>SD_BUS_SIGNAL_WITH_NAMES(
<replaceable>member</replaceable>,
</para>
<para>
<constant>SD_BUS_PARAM(<replaceable>name</replaceable>)</constant>
+ <constant>SD_BUS_ARGS(<replaceable>...</replaceable>)</constant>
+ <constant>SD_BUS_RESULT(<replaceable>...</replaceable>)</constant>
+ <constant>SD_BUS_NO_ARGS</constant>
+ <constant>SD_BUS_NO_RESULT</constant>
</para>
</funcsynopsis>
</refsynopsisdiv>
<listitem><para>Those must always be the first and last element.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant></term>
+ <term><constant>SD_BUS_METHOD_WITH_ARGS()</constant></term>
+
+ <listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>,
+ arguments <replaceable>args</replaceable> and result <replaceable>result</replaceable>.
+ <replaceable>args</replaceable> expects a sequence of argument type/name pairs wrapped in the
+ <constant>SD_BUS_ARGS()</constant> macro. The elements at even indices in this list describe the
+ types of the method's arguments. The method's parameter signature is the concatenation of all the
+ string literals at even indices in <replaceable>args</replaceable>. If a method has no parameters,
+ pass <constant>SD_BUS_NO_ARGS</constant> to <replaceable>args</replaceable>. The elements at uneven
+ indices describe the names of the method's arguments. <replaceable>result</replaceable> expects a
+ sequence of type/name pairs wrapped in the <constant>SD_BUS_RESULT()</constant> macro in the same
+ format as <constant>SD_BUS_ARGS()</constant>. The method's result signature is the concatenation of
+ all the string literals at even indices in <replaceable>result</replaceable>. If a method has no
+ result, pass <constant>SD_BUS_NO_RESULT</constant> to <replaceable>result</replaceable>. Note that
+ argument types are expected to be quoted string literals and argument names are expected to be
+ unquoted string literals. See below for a complete example.</para>
+
+ <para>The handler function <replaceable>handler</replaceable> must be of type
+ <function>sd_bus_message_handler_t</function>. It will be called to handle the incoming messages
+ that call this method. It receives a pointer that is the <replaceable>userdata</replaceable>
+ parameter passed to the registration function offset by <replaceable>offset</replaceable> bytes.
+ This may be used to pass pointers to different fields in the same data structure to different
+ methods in the same vtable. To send a reply from <parameter>handler</parameter>, call
+ <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ with the message the callback was invoked with. Parameter <replaceable>flags</replaceable> is a
+ combination of flags, see below.</para>
+
+ <constant>SD_BUS_METHOD_WITH_ARGS()</constant> is a shorthand for calling
+ <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant> with an offset of zero.
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant></term>
<term><constant>SD_BUS_METHOD_WITH_NAMES()</constant></term>
parameter signature <replaceable>signature</replaceable>, result signature
<replaceable>result</replaceable>. Parameters <replaceable>in_names</replaceable> and
<replaceable>out_names</replaceable> specify the argument names of the input and output
- arguments in the function signature. The handler function
- <replaceable>handler</replaceable> must be of type
- <function>sd_bus_message_handler_t</function>. It will be called to handle the incoming
- messages that call this method. It receives a pointer that is the
- <replaceable>userdata</replaceable> parameter passed to the registration function offset
- by <replaceable>offset</replaceable> bytes. This may be used to pass pointers to different
- fields in the same data structure to different methods in the same vtable. To send a reply
- from <parameter>handler</parameter>, call
- <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- with the message the callback was invoked with. <replaceable>in_names</replaceable> and
+ arguments in the function signature. <replaceable>in_names</replaceable> and
<replaceable>out_names</replaceable> should be created using the
- <constant>SD_BUS_PARAM()</constant> macro, see below. Parameter
- <replaceable>flags</replaceable> is a combination of flags, see below.</para>
+ <constant>SD_BUS_PARAM()</constant> macro, see below. In all other regards, this macro behaves
+ exactly the same as <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant>.</para>
<para><constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
<constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant>
are variants which specify zero offset (<replaceable>userdata</replaceable> parameter is
passed with no change), leave the names unset (i.e. no parameter names), or both.</para>
+
+ <para>Prefer using <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant> and
+ <constant>SD_BUS_METHOD_WITH_ARGS()</constant> over these macros as they allow specifying argument
+ types and names next to each other which is less error-prone than first specifying all argument
+ types followed by specifying all argument names.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><constant>SD_BUS_SIGNAL_WITH_ARGS()</constant></term>
+
+ <listitem><para>>Declare a D-Bus signal with the name <replaceable>member</replaceable> and
+ arguments <replaceable>args</replaceable>. <replaceable>args</replaceable> expects a sequence of
+ argument type/name pairs wrapped in the <constant>SD_BUS_ARGS()</constant> macro. The elements at
+ even indices in this list describe the types of the signal's arguments. The signal's parameter
+ signature is the concatenation of all the string literals at even indices in
+ <replaceable>args</replaceable>. If a signal has no parameters, pass
+ <constant>SD_BUS_NO_ARGS</constant> to <replaceable>args</replaceable>. The elements at uneven
+ indices describe the names of the signal's arguments. Parameter <replaceable>flags</replaceable> is
+ a combination of flags. See below for a complete example.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><constant>SD_BUS_SIGNAL_WITH_NAMES()</constant></term>
<term><constant>SD_BUS_SIGNAL()</constant></term>
Parameter <replaceable>flags</replaceable> is a combination of flags, see below.
</para>
- <para>Equivalent to <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> with the
- <replaceable>names</replaceable> parameter unset (i.e. no parameter names).</para>
+ <para><constant>SD_BUS_SIGNAL()</constant> is equivalent to
+ <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> with the <replaceable>names</replaceable> parameter
+ unset (i.e. no parameter names).</para>
+
+ <para>Prefer using <constant>SD_BUS_SIGNAL_WITH_ARGS()</constant> over these macros as it allows
+ specifying argument types and names next to each other which is less error-prone than first
+ specifying all argument types followed by specifying all argument names.</para>
</listitem>
</varlistentry>
This corresponds to the <constant>org.freedesktop.systemd1.Explicit</constant> annotation
in introspection data.</para></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><constant>SD_BUS_VTABLE_SENSITIVE</constant></term>
+
+ <listitem><para>Mark this vtable method entry as processing sensitive data. When set,
+ incoming method call messages and their outgoing reply messages are marked as sensitive using
+ <citerefentry><refentrytitle>sd_bus_message_sensitive</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ so that they are erased from memory when freed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>SD_BUS_VTABLE_ABSOLUTE_OFFSET</constant></term>
+
+ <listitem><para>Mark this vtable method or property entry so that the user data pointer passed to
+ its associated handler functions is determined slightly differently: instead of adding the offset
+ parameter of the entry to the user data pointer specified during vtable registration, the offset is
+ passed directly, converted to a pointer, without taking the user data pointer specified during
+ vtable registration into account.</para></listitem>
+ </varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Return Value</title>
- <para>On success, <function>sd_bus_add_object_vtable</function> and
- <function>sd_bus_add_fallback_vtable</function> calls return 0 or a positive integer. On
+ <para>On success, <function>sd_bus_add_object_vtable()</function> and
+ <function>sd_bus_add_fallback_vtable()</function> return a non-negative integer. On
failure, they return a negative errno-style error code.</para>
<refsect2>
projects / thirdparty / systemd.git / blobdiff