From 50b88e87c8d1e6e0722740520a148943432b981b Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sat, 28 Mar 2020 22:03:19 +0100 Subject: [PATCH] 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.