SymbX/systemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sd-bus: Add a nicer way of specifying sd-bus vtable method arguments

Browse Source 
SD_BUS_NAMES_WITH_ARGS is a less error-prone way of specifying D-Bus
method arguments.
This commit is contained in:
Daan De Meyer
2020-05-06 10:22:54 +02:00
committed by Lennart Poettering
parent 7f3a5eb70e
commit eff7c2d3c9
5 changed files with 391 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/sd_bus_add_object.xml
+93 -14
View File
@@ -132,6 +132,25 @@
<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>,
@@ -174,6 +193,13 @@
<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>,
@@ -210,6 +236,10 @@
</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>
@@ -315,6 +345,40 @@
<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>
@@ -325,27 +389,37 @@
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>
@@ -357,8 +431,13 @@
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>
man/vtable-example.c
+24
View File
@@ -27,6 +27,30 @@ static const sd_bus_vtable vtable[] = {
"s", SD_BUS_PARAM(returnstring),
method, offsetof(object, number),
SD_BUS_VTABLE_DEPRECATED),
SD_BUS_METHOD_WITH_ARGS_OFFSET(
"Method3",
SD_BUS_ARGS("s", string, "o", path),
SD_BUS_RESULT("s", returnstring),
method, offsetof(object, number),
SD_BUS_VTABLE_UNPRIVILEGED),
SD_BUS_METHOD_WITH_ARGS(
"Method4",
SD_BUS_NO_ARGS,
SD_BUS_NO_RESULT,
method,
SD_BUS_VTABLE_UNPRIVILEGED),
SD_BUS_SIGNAL(
"Signal1",
"so",
0),
SD_BUS_SIGNAL_WITH_NAMES(
"Signal2",
"so", SD_BUS_PARAM(string) SD_BUS_PARAM(path),
0),
SD_BUS_SIGNAL_WITH_ARGS(
"Signal3",
SD_BUS_ARGS("s", string, "o", path),
0),
SD_BUS_WRITABLE_PROPERTY(
"AutomaticStringProperty", "s", NULL, NULL,
offsetof(object, name),