diff --git a/man/rules/meson.build b/man/rules/meson.build index db90073f36..d451ac7bbe 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -134,7 +134,9 @@ manpages = [ 'SD_BUS_VTABLE_END', 'SD_BUS_VTABLE_START', 'SD_BUS_WRITABLE_PROPERTY', - 'sd_bus_add_fallback_vtable'], + 'sd_bus_add_fallback', + 'sd_bus_add_fallback_vtable', + 'sd_bus_add_object'], ''], ['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.xml b/man/sd-bus.xml index 48f4a2a84f..db405e1763 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -41,7 +41,10 @@ See sd_bus_add_match3, +sd_bus_add_object3, sd_bus_add_object_vtable3, +sd_bus_add_fallback3, +sd_bus_add_fallback_vtable3, sd_bus_attach_event3, sd_bus_call3, sd_bus_call_async3, diff --git a/man/sd_bus_add_object_vtable.xml b/man/sd_bus_add_object_vtable.xml index b1cea7d7ac..218a54647b 100644 --- a/man/sd_bus_add_object_vtable.xml +++ b/man/sd_bus_add_object_vtable.xml @@ -19,6 +19,8 @@ sd_bus_add_object_vtable sd_bus_add_fallback_vtable + sd_bus_add_object + sd_bus_add_fallback SD_BUS_VTABLE_START SD_BUS_VTABLE_END SD_BUS_METHOD_WITH_NAMES_OFFSET @@ -97,6 +99,24 @@ void *userdata + + int sd_bus_add_object + sd_bus *bus + sd_bus_slot **slot + const char *path + sd_bus_message_handler_t callback + void *userdata + + + + int sd_bus_add_fallback + sd_bus *bus + sd_bus_slot **slot + const char *path + sd_bus_message_handler_t callback + void *userdata + + SD_BUS_VTABLE_START(flags) @@ -200,7 +220,7 @@ SD_BUS_SIGNAL_WITH_NAMES() or SD_BUS_SIGNAL(), see below. The userdata parameter contains a pointer that will be passed to various callback functions. It may be specified as NULL if no value is - necessary. + necessary. An interface can have any number of vtables attached to it. sd_bus_add_fallback_vtable() is similar to sd_bus_add_object_vtable(), but is used to register "fallback" attributes. @@ -220,7 +240,45 @@ for the callback functions (offset by the offset offsets as specified in the vtable entries). - For both functions, a match slot is created internally. If the output parameter + sd_bus_add_object() attaches a callback directly to the object path + path. An object path can have any number of callbacks attached to it. + Each callback is prepended to the list of callbacks which are always called in order. + sd_bus_add_fallback() is similar to + 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 + 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 + returns zero, an error reply is sent back to the caller indicating no matching object for the + request was found. Note that you can return a positive integer from a callback without + 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. + + 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 + back to the caller as a D-Bus error as if + sd_bus_reply_method_errno3 + was called. Additionally, all callbacks take a sd_bus_error output + parameter that can be used to provide more detailed error information. If + ret_error is set when the callback finishes, the corresponding D-Bus + error is sent back to the caller as if + sd_bus_reply_method_error3 + was called. Any error stored in ret_error takes priority over any + negative values returned by the same callback when determining which error to send back to + the caller. Use + sd_bus_error_set3 + or one of its variants to set ret_error and return a negative integer + from a callback with a single function call. To send an error reply after a callback has already + finished, use + sd_bus_reply_method_errno3 + or one of its variants. + + For all functions, a match slot is created internally. If the output parameter slot is NULL, a "floating" slot object is created, see sd_bus_slot_set_floating3.