From 50b88e87c8d1e6e0722740520a148943432b981b Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sat, 28 Mar 2020 22:03:19 +0100 Subject: [PATCH 1/4] sd-bus: Wrap add_object_vtable docs at 100 columns --- man/sd_bus_add_object_vtable.xml | 182 ++++++++++++++++--------------- 1 file changed, 95 insertions(+), 87 deletions(-) diff --git a/man/sd_bus_add_object_vtable.xml b/man/sd_bus_add_object_vtable.xml index 9d7e30a504..06f414485f 100644 --- a/man/sd_bus_add_object_vtable.xml +++ b/man/sd_bus_add_object_vtable.xml @@ -188,40 +188,44 @@ Description - sd_bus_add_object_vtable() is used to declare attributes for the path object - path path connected to the bus connection bus under the - interface interface. The table vtable may contain property - declarations using SD_BUS_PROPERTY() or - SD_BUS_WRITABLE_PROPERTY(), method declarations using - SD_BUS_METHOD(), SD_BUS_METHOD_WITH_NAMES(), + sd_bus_add_object_vtable() is used to declare attributes for the path + object path path connected to the bus connection + bus under the interface interface. The table + vtable may contain property declarations using + SD_BUS_PROPERTY() or SD_BUS_WRITABLE_PROPERTY(), + method declarations using SD_BUS_METHOD(), + SD_BUS_METHOD_WITH_NAMES(), SD_BUS_METHOD_WITH_OFFSET(), or SD_BUS_METHOD_WITH_NAMES_OFFSET(), and signal declarations using - 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. + 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. sd_bus_add_fallback_vtable() is similar to - sd_bus_add_object_vtable(), but is used to register "fallback" attributes. When - looking for an attribute declaration, bus object paths registered with - sd_bus_add_object_vtable() are checked first. If no match is found, the fallback - vtables are checked for each prefix of the bus object path, i.e. with the last slash-separated components - successively removed. This allows the vtable to be used for an arbitrary number of dynamically created - objects. + sd_bus_add_object_vtable(), but is used to register "fallback" attributes. + When looking for an attribute declaration, bus object paths registered with + sd_bus_add_object_vtable() are checked first. If no match is found, the + fallback vtables are checked for each prefix of the bus object path, i.e. with the last + slash-separated components successively removed. This allows the vtable to be used for an + arbitrary number of dynamically created objects. - Parameter find is a function which is used to locate the target object - based on the bus object path path. It must return 1 and - set the ret_found output parameter if the object is found, return - 0 if the object was not found, and return a negative errno-style error code or - initialize the error structure ret_error on error. The pointer passed in - ret_found will be used as the userdata parameter for the - callback functions (offset by the offset offsets as specified in the vtable - entries). + Parameter find is a function which is used to locate the target + object based on the bus object path path. It must return + 1 and set the ret_found output parameter if the + object is found, return 0 if the object was not found, and return a + negative errno-style error code or initialize the error structure + ret_error on error. The pointer passed in + ret_found will be used as the userdata parameter + 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 - slot is NULL, a "floating" slot object is created, see + slot is NULL, a "floating" slot object is + created, see sd_bus_slot_set_floating3. - Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot object - should be dropped when the vtable is not needed anymore, see + Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot + object should be dropped when the vtable is not needed anymore, see sd_bus_slot_unref3. @@ -245,23 +249,25 @@ SD_BUS_METHOD_WITH_OFFSET() SD_BUS_METHOD() - Declare a D-Bus method with the name member, 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. in_names and out_names should be + Declare a D-Bus method with the name member, + 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. + 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(), - 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. + 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. @@ -285,29 +291,31 @@ SD_BUS_WRITABLE_PROPERTY() SD_BUS_PROPERTY() - Declare a D-Bus property with the name member and value - signature signature. Parameters get and - set are the getter and setter methods. They are called with a pointer - that is the userdata parameter passed to the registration function - offset by offset bytes. This may be used pass pointers to different - fields in the same data structure to different setters and getters in the same vtable. Parameter - flags is a combination of flags, see below. + Declare a D-Bus property with the name member + and value signature signature. Parameters + get and set are the getter and + setter methods. They are called with a pointer that is the + userdata parameter passed to the registration function offset + by offset bytes. This may be used pass pointers to different + fields in the same data structure to different setters and getters in the same vtable. + Parameter flags is a combination of flags, see below. - The setter and getter methods may be omitted (specified as NULL), if the - property has one of the basic types or as in case of read-only properties. In - those cases, the userdata and offset - parameters must together point to valid variable of the corresponding type. A default setter and - getters will be provided, which simply copy the argument between this variable and the message. + The setter and getter methods may be omitted (specified as + NULL), if the property has one of the basic types or + as in case of read-only properties. In those cases, the + userdata and offset parameters must + together point to valid variable of the corresponding type. A default setter and getters + will be provided, which simply copy the argument between this variable and the message. - SD_BUS_PROPERTY() is used to define a read-only property. - + SD_BUS_PROPERTY() is used to define a read-only property. + SD_BUS_PARAM() - Parameter names should be wrapped in this macro, see the example below. - + Parameter names should be wrapped in this macro, see the example below. + @@ -324,7 +332,7 @@ SD_BUS_VTABLE_DEPRECATED Mark this vtable entry as deprecated using the - org.freedesktop.DBus.Deprecated annotation in introspection data. If + org.freedesktop.DBus.Deprecated annotation in introspection data. If specified for SD_BUS_VTABLE_START(), the annotation is applied to the enclosing interface. @@ -332,10 +340,9 @@ SD_BUS_VTABLE_HIDDEN - Make this vtable entry hidden. It will not be shown in introspection data. If - specified for SD_BUS_VTABLE_START(), all entries in the array are hidden. - - + Make this vtable entry hidden. It will not be shown in introspection data. + If specified for SD_BUS_VTABLE_START(), all entries in the array are + hidden. @@ -343,8 +350,7 @@ Mark this vtable entry as unprivileged. If not specified, the org.freedesktop.systemd1.Privileged annotation with value - true will be shown in introspection data. - + true will be shown in introspection data. @@ -361,27 +367,28 @@ SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION Those three flags correspond to different values of the - org.freedesktop.DBus.Property.EmitsChangedSignal annotation, which specifies - whether the org.freedesktop.DBus.Properties.PropertiesChanged signal is - emitted whenever the property changes. SD_BUS_VTABLE_PROPERTY_CONST corresponds to - const and means that the property never changes during the lifetime of the - object it belongs to, so no signal needs to be emitted. - SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE corresponds to true and means - that the signal is emitted. SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION corresponds to - invalidates and means that the signal is emitted, but the value is not included - in the signal. - + org.freedesktop.DBus.Property.EmitsChangedSignal annotation, which + specifies whether the + org.freedesktop.DBus.Properties.PropertiesChanged signal is emitted + whenever the property changes. SD_BUS_VTABLE_PROPERTY_CONST + corresponds to const and means that the property never changes during + the lifetime of the object it belongs to, so no signal needs to be emitted. + SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE corresponds to + true and means that the signal is emitted. + SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION corresponds to + invalidates and means that the signal is emitted, but the value is + not included in the signal. SD_BUS_VTABLE_PROPERTY_EXPLICIT - Mark this vtable property entry as requiring explicit request to for the value to - be shown (generally because the value is large or slow to calculate). This entry cannot be combined - with SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE, and will not be shown in property listings by - default (e.g. busctl introspect). This corresponds to the - org.freedesktop.systemd1.Explicit annotation in introspection data. - + Mark this vtable property entry as requiring explicit request to for the + value to be shown (generally because the value is large or slow to calculate). This entry + cannot be combined with SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE, and will + not be shown in property listings by default (e.g. busctl introspect). + This corresponds to the org.freedesktop.systemd1.Explicit annotation + in introspection data. @@ -395,9 +402,9 @@ - This creates a simple client on the bus (the user bus, when run as normal user). - We may use the D-Bus org.freedesktop.DBus.Introspectable.Introspect - call to acquire the XML description of the interface: + This creates a simple client on the bus (the user bus, when run as normal user). We may + use the D-Bus org.freedesktop.DBus.Introspectable.Introspect call to + acquire the XML description of the interface: @@ -407,8 +414,8 @@ Return Value On success, sd_bus_add_object_vtable and - sd_bus_add_fallback_vtable calls return 0 or a positive integer. On failure, they - return a negative errno-style error code. + sd_bus_add_fallback_vtable calls return 0 or a positive integer. On + failure, they return a negative errno-style error code. Errors @@ -419,8 +426,9 @@ -EINVAL - One of the required parameters is NULL or invalid. A reserved - D-Bus interface was passed as the interface parameter. + One of the required parameters is NULL or invalid. A + reserved D-Bus interface was passed as the interface parameter. + @@ -445,8 +453,8 @@ -EPROTOTYPE sd_bus_add_object_vtable and - sd_bus_add_fallback_vtable have been both called - for the same bus object path, which is not allowed. + sd_bus_add_fallback_vtable have been both called for the same bus + object path, which is not allowed. From 6ba8071ca11ae8b50137a79a89fdbb3a4c718b08 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sat, 28 Mar 2020 22:22:58 +0100 Subject: [PATCH 2/4] sd-bus: Fix typos in sd_bus_add_object_vtable docs --- man/sd_bus_add_object_vtable.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/man/sd_bus_add_object_vtable.xml b/man/sd_bus_add_object_vtable.xml index 06f414485f..b1cea7d7ac 100644 --- a/man/sd_bus_add_object_vtable.xml +++ b/man/sd_bus_add_object_vtable.xml @@ -188,7 +188,7 @@ Description - sd_bus_add_object_vtable() is used to declare attributes for the path + sd_bus_add_object_vtable() is used to declare attributes for the object path path connected to the bus connection bus under the interface interface. The table vtable may contain property declarations using @@ -301,10 +301,10 @@ Parameter flags is a combination of flags, see below. The setter and getter methods may be omitted (specified as - NULL), if the property has one of the basic types or + NULL), if the property is one of the basic types or as in case of read-only properties. In those cases, the userdata and offset parameters must - together point to valid variable of the corresponding type. A default setter and getters + together point to a valid variable of the corresponding type. A default setter and getter will be provided, which simply copy the argument between this variable and the message. From fc91667d773e425fed9648e400d97b6bea72f6c3 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 30 Mar 2020 20:53:24 +0200 Subject: [PATCH 3/4] sd-bus: Add sd_bus_add_object and callback docs --- man/rules/meson.build | 4 ++- man/sd-bus.xml | 3 ++ man/sd_bus_add_object_vtable.xml | 62 ++++++++++++++++++++++++++++++-- 3 files changed, 66 insertions(+), 3 deletions(-) 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. From 9b62e232ea9c5f6d70df38bc0ccac4f7eec15e06 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 30 Mar 2020 21:11:42 +0200 Subject: [PATCH 4/4] 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} | 61 ++++++++++--------- 2 files changed, 34 insertions(+), 31 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 d451ac7bbe..9cdfe5d291 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 218a54647b..2abe2342f0 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 @@ -78,6 +78,24 @@ sd_bus_error *ret_error + + 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 + + int sd_bus_add_object_vtable sd_bus *bus @@ -99,24 +117,6 @@ 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) @@ -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(),