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

SD_BUS_NAMES_WITH_ARGS is a less error-prone way of specifying D-Bus
method arguments.

1 files changed, 93 insertions, 14 deletions

diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml
index a747df62ca..60f04187f8 100644
--- a/man/sd_bus_add_object.xml
+++ b/man/sd_bus_add_object.xml
@@ -133,6 +133,25 @@
         <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>signature</replaceable>,
@@ -175,6 +194,13 @@
         </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>,
         <replaceable>signature</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>
@@ -316,6 +346,40 @@
         </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>
           <term><constant>SD_BUS_METHOD_WITH_OFFSET()</constant></term>
@@ -325,28 +389,38 @@
           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>