From 9b62e232ea9c5f6d70df38bc0ccac4f7eec15e06 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 30 Mar 2020 21:11:42 +0200 Subject: [PATCH] sd-bus: Add note about sd_bus_reply_method_return to SD_BUS_METHOD docs --- man/rules/meson.build | 4 +- ...bject_vtable.xml => sd_bus_add_object.xml} | 51 ++++++++++--------- 2 files changed, 29 insertions(+), 26 deletions(-) rename man/{sd_bus_add_object_vtable.xml => sd_bus_add_object.xml} (97%) diff --git a/man/rules/meson.build b/man/rules/meson.build index d451ac7bbec..9cdfe5d2919 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -121,7 +121,7 @@ manpages = [ 'sd_bus_match_signal', 'sd_bus_match_signal_async'], ''], - ['sd_bus_add_object_vtable', + ['sd_bus_add_object', '3', ['SD_BUS_METHOD', 'SD_BUS_METHOD_WITH_NAMES', @@ -136,7 +136,7 @@ manpages = [ 'SD_BUS_WRITABLE_PROPERTY', 'sd_bus_add_fallback', 'sd_bus_add_fallback_vtable', - 'sd_bus_add_object'], + 'sd_bus_add_object_vtable'], ''], ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''], ['sd_bus_call', '3', ['sd_bus_call_async'], ''], diff --git a/man/sd_bus_add_object_vtable.xml b/man/sd_bus_add_object.xml similarity index 97% rename from man/sd_bus_add_object_vtable.xml rename to man/sd_bus_add_object.xml index 218a54647b5..2abe2342f0a 100644 --- a/man/sd_bus_add_object_vtable.xml +++ b/man/sd_bus_add_object.xml @@ -3,24 +3,24 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - sd_bus_add_object_vtable + sd_bus_add_object systemd - sd_bus_add_object_vtable + sd_bus_add_object 3 - sd_bus_add_object_vtable - sd_bus_add_fallback_vtable sd_bus_add_object sd_bus_add_fallback + sd_bus_add_object_vtable + sd_bus_add_fallback_vtable SD_BUS_VTABLE_START SD_BUS_VTABLE_END SD_BUS_METHOD_WITH_NAMES_OFFSET @@ -79,41 +79,41 @@ - int sd_bus_add_object_vtable + int sd_bus_add_object sd_bus *bus sd_bus_slot **slot const char *path - const char *interface - const sd_bus_vtable *vtable + sd_bus_message_handler_t callback void *userdata - int sd_bus_add_fallback_vtable + int sd_bus_add_fallback sd_bus *bus sd_bus_slot **slot - const char *prefix - const char *interface - const sd_bus_vtable *vtable - sd_bus_object_find_t find + const char *path + sd_bus_message_handler_t callback void *userdata - int sd_bus_add_object + int sd_bus_add_object_vtable sd_bus *bus sd_bus_slot **slot const char *path - sd_bus_message_handler_t callback + const char *interface + const sd_bus_vtable *vtable void *userdata - int sd_bus_add_fallback + int sd_bus_add_fallback_vtable sd_bus *bus sd_bus_slot **slot - const char *path - sd_bus_message_handler_t callback + const char *prefix + const char *interface + const sd_bus_vtable *vtable + sd_bus_object_find_t find void *userdata @@ -247,8 +247,8 @@ sd_bus_add_object() but applies to fallback paths instead. When a request is received, any associated callbacks are called sequentially until a - callback returns a non-zero integer. Return zero from a callback to defer handling of the - request to the next callback. Callbacks are called in the following order: first, callbacks + callback returns a non-zero integer. Return zero from a callback to give other callbacks the + chance to process the request. Callbacks are called in the following order: first, callbacks attached directly to the request object path are called, followed by any D-Bus method callbacks attached to the request object path, interface and member. Finally, the property callbacks attached to the request object path, interface and member are called. If the final callback @@ -257,7 +257,7 @@ immediately sending a reply. This informs sd-bus this callback will take responsibility for replying to the request without forcing the callback to produce a reply immediately. This allows a callback to perform any number of asynchronous operations required to construct a reply. Note - that if producing a reply takes too long, the method call will timeout at the caller. + that if producing a reply takes too long, the method call will time out at the caller. If a callback was invoked to handle a request that expects a reply and the callback returns a negative value, the value is interpreted as a negative errno-style error code and sent @@ -317,9 +317,12 @@ 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. - in_names and out_names should be - created using the SD_BUS_PARAM() macro, see below. Parameter + 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 + out_names should be created using the + SD_BUS_PARAM() macro, see below. Parameter flags is a combination of flags, see below. SD_BUS_METHOD_WITH_NAMES(), -- 2.39.2