From eff7c2d3c905dec9ea4e1d5e53a0efd6af7d3d26 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Tue, 28 Apr 2020 19:04:33 +0200 Subject: 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. --- man/sd_bus_add_object.xml | 107 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 93 insertions(+), 14 deletions(-) (limited to 'man/sd_bus_add_object.xml') 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 @@ -132,6 +132,25 @@ SD_BUS_VTABLE_END + + SD_BUS_METHOD_WITH_ARGS_OFFSET( + member, + args, + result, + handler, + offset, + flags) + + + + SD_BUS_METHOD_WITH_ARGS( + member, + args, + result, + handler, + flags) + + SD_BUS_METHOD_WITH_NAMES_OFFSET( member, @@ -174,6 +193,13 @@ flags) + + SD_BUS_SIGNAL_WITH_ARGS( + member, + args, + flags) + + SD_BUS_SIGNAL_WITH_NAMES( member, @@ -210,6 +236,10 @@ SD_BUS_PARAM(name) + SD_BUS_ARGS(...) + SD_BUS_RESULT(...) + SD_BUS_NO_ARGS + SD_BUS_NO_RESULT @@ -315,6 +345,40 @@ Those must always be the first and last element. + + SD_BUS_METHOD_WITH_ARGS_OFFSET() + SD_BUS_METHOD_WITH_ARGS() + + Declare a D-Bus method with the name member, + arguments args and result result. + args expects a sequence of argument type/name pairs wrapped in the + SD_BUS_ARGS() 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 args. If a method has no parameters, + pass SD_BUS_NO_ARGS to args. The elements at uneven + indices describe the names of the method's arguments. result expects a + sequence of type/name pairs wrapped in the SD_BUS_RESULT() macro in the same + format as SD_BUS_ARGS(). The method's result signature is the concatenation of + all the string literals at even indices in result. If a method has no + result, pass SD_BUS_NO_RESULT to result. 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. + + The handler function handler must be of type + sd_bus_message_handler_t. It will be called to handle the incoming messages + that call this method. It receives a pointer that is the userdata + parameter passed to the registration function offset by offset 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 handler, call + sd_bus_reply_method_return3 + with the message the callback was invoked with. Parameter flags is a + combination of flags, see below. + + SD_BUS_METHOD_WITH_ARGS() is a shorthand for calling + SD_BUS_METHOD_WITH_ARGS_OFFSET() with an offset of zero. + + + SD_BUS_METHOD_WITH_NAMES_OFFSET() SD_BUS_METHOD_WITH_NAMES() @@ -325,27 +389,37 @@ parameter signature signature, result signature result. Parameters in_names and out_names specify the argument names of the input and output - arguments in the function signature. The handler function - handler must be of type - sd_bus_message_handler_t. It will be called to handle the incoming - messages that call this method. It receives a pointer that is the - userdata parameter passed to the registration function offset - by offset 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 handler, call - sd_bus_reply_method_return3 - with the message the callback was invoked with. in_names and + arguments in the function signature. in_names and out_names should be created using the - SD_BUS_PARAM() macro, see below. Parameter - flags is a combination of flags, see below. + SD_BUS_PARAM() macro, see below. In all other regards, this macro behaves + exactly the same as SD_BUS_METHOD_WITH_ARGS_OFFSET(). SD_BUS_METHOD_WITH_NAMES(), SD_BUS_METHOD_WITH_OFFSET(), and SD_BUS_METHOD() are variants which specify zero offset (userdata parameter is passed with no change), leave the names unset (i.e. no parameter names), or both. + + Prefer using SD_BUS_METHOD_WITH_ARGS_OFFSET() and + SD_BUS_METHOD_WITH_ARGS() 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. + + SD_BUS_SIGNAL_WITH_ARGS() + + >Declare a D-Bus signal with the name member and + arguments args. args expects a sequence of + argument type/name pairs wrapped in the SD_BUS_ARGS() 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 + args. If a signal has no parameters, pass + SD_BUS_NO_ARGS to args. The elements at uneven + indices describe the names of the signal's arguments. Parameter flags is + a combination of flags. See below for a complete example. + + SD_BUS_SIGNAL_WITH_NAMES() SD_BUS_SIGNAL() @@ -357,8 +431,13 @@ Parameter flags is a combination of flags, see below. - Equivalent to SD_BUS_SIGNAL_WITH_NAMES() with the - names parameter unset (i.e. no parameter names). + SD_BUS_SIGNAL() is equivalent to + SD_BUS_SIGNAL_WITH_NAMES() with the names parameter + unset (i.e. no parameter names). + + Prefer using SD_BUS_SIGNAL_WITH_ARGS() 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. -- cgit v1.2.1