diff --git a/man/rules/meson.build b/man/rules/meson.build index ee8c236744..5620ba1e5b 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', @@ -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_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.xml b/man/sd-bus.xml index c649bc46fe..a5f493b2ce 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.xml similarity index 59% rename from man/sd_bus_add_object_vtable.xml rename to man/sd_bus_add_object.xml index 9d7e30a504..2abe2342f0 100644 --- a/man/sd_bus_add_object_vtable.xml +++ b/man/sd_bus_add_object.xml @@ -3,20 +3,22 @@ "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 + sd_bus_add_fallback sd_bus_add_object_vtable sd_bus_add_fallback_vtable SD_BUS_VTABLE_START @@ -76,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 @@ -188,40 +208,82 @@ 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 + 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. 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. 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 + 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 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 + 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 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 + 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. - 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 +307,28 @@ 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 - created using the SD_BUS_PARAM() macro, see below. Parameter + 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. 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(), - 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 +352,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 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 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. - 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 +393,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 +401,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 +411,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 +428,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 +463,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 +475,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 +487,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 +514,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.