From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_bus_add_object.xml | 692 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 692 insertions(+) create mode 100644 man/sd_bus_add_object.xml (limited to 'man/sd_bus_add_object.xml') diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml new file mode 100644 index 0000000..991f3a8 --- /dev/null +++ b/man/sd_bus_add_object.xml @@ -0,0 +1,692 @@ + + + + + + + + sd_bus_add_object + systemd + + + + 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_add_filter + SD_BUS_VTABLE_CAPABILITY + SD_BUS_VTABLE_START + SD_BUS_VTABLE_END + SD_BUS_METHOD_WITH_NAMES_OFFSET + SD_BUS_METHOD_WITH_NAMES + SD_BUS_METHOD_WITH_OFFSET + SD_BUS_METHOD + SD_BUS_SIGNAL_WITH_NAMES + SD_BUS_SIGNAL + SD_BUS_WRITABLE_PROPERTY + SD_BUS_PROPERTY + SD_BUS_PARAM + + Declare properties and methods for a D-Bus path + + + + + #include <systemd/sd-bus-vtable.h> + + + + + typedef int (*sd_bus_property_get_t) + sd_bus *bus + const char *path + const char *interface + const char *property + sd_bus_message *reply + void *userdata + sd_bus_error *ret_error + + + + typedef int (*sd_bus_property_set_t) + sd_bus *bus + const char *path + const char *interface + const char *property + sd_bus_message *value + void *userdata + sd_bus_error *ret_error + + + + typedef int (*sd_bus_object_find_t) + const char *path + const char *interface + void *userdata + void **ret_found + 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 + sd_bus_slot **slot + const char *path + const char *interface + const sd_bus_vtable *vtable + void *userdata + + + + int sd_bus_add_fallback_vtable + sd_bus *bus + sd_bus_slot **slot + const char *prefix + const char *interface + const sd_bus_vtable *vtable + sd_bus_object_find_t find + void *userdata + + + + int sd_bus_add_filter + sd_bus *bus + sd_bus_slot **slot + sd_bus_message_handler_t callback + void *userdata + + + + SD_BUS_VTABLE_CAPABILITY(capability) + + + + SD_BUS_VTABLE_START(flags) + + + SD_BUS_VTABLE_END + + + SD_BUS_METHOD_WITH_ARGS_OFFSET(member, + args, + result, + handler, + offset, + flags) + + + + SD_BUS_METHOD_WITH_ARGS(member, + args, + result, + handler, + flags) + + + + SD_BUS_METHOD_WITH_NAMES_OFFSET(member, + signature, + in_names, + result, + out_names, + handler, + offset, + flags) + + + + SD_BUS_METHOD_WITH_NAMES(member, + signature, + in_names, + result, + out_names, + handler, + flags) + + + + SD_BUS_METHOD_WITH_OFFSET(member, + signature, + result, + handler, + offset, + flags) + + + + SD_BUS_METHOD(member, + signature, + result, + handler, + flags) + + + + SD_BUS_SIGNAL_WITH_ARGS(member, + args, + flags) + + + + SD_BUS_SIGNAL_WITH_NAMES(member, + signature, + names, + flags) + + + + SD_BUS_SIGNAL(member, + signature, + flags) + + + + SD_BUS_WRITABLE_PROPERTY(member, + signature, + get, + set, + offset, + flags) + + + + SD_BUS_PROPERTY(member, + signature, + get, + offset, + flags) + + + + SD_BUS_PARAM(name) + + + SD_BUS_ARGS(...) + + + SD_BUS_RESULT(...) + + + SD_BUS_NO_ARGS + + + SD_BUS_NO_RESULT + + + + + + Description + + 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. 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. + + 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). + + 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. + + sd_bus_add_filter() installs a callback that is invoked for each + incoming D-Bus message. Filters can be used to handle logic common to all messages received by + a service (e.g. authentication or authorization). + + 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, global + callbacks installed with sd_bus_add_filter() are called. Second, 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 method 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. + However, if producing a reply takes too long, the method call will time out at the caller. This is + only available to methods and not properties. + + 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 + sd_bus_slot_unref3. + + + + The <structname>sd_bus_vtable</structname> array + + The array consists of the structures of type sd_bus_vtable, but it + should never be filled in manually, but through one of the following macros: + + + + SD_BUS_VTABLE_START(flags) + SD_BUS_VTABLE_END + + Those must always be the first and last element. The + flags parameter can be used to set attributes that apply to the whole + array; see the "Flags" section below. + + + + SD_BUS_METHOD_WITH_ARGS_OFFSET() + SD_BUS_METHOD_WITH_ARGS() + + Declare a D-Bus method with the name member, + arguments args and result result. + args expects a sequence of argument type/name pairs wrapped in the + SD_BUS_ARGS() macro. The elements at even indices in this list describe the + types of the method's arguments. The method's parameter signature is the concatenation of all the + string literals at even indices in args. If a method has no parameters, + pass SD_BUS_NO_ARGS to args. The elements at uneven + indices describe the names of the method's arguments. result expects a + sequence of type/name pairs wrapped in the SD_BUS_RESULT() macro in the same + format as SD_BUS_ARGS(). The method's result signature is the concatenation of + all the string literals at even indices in result. If a method has no + result, pass SD_BUS_NO_RESULT to result. Note that + argument types are expected to be quoted string literals and argument names are expected to be + unquoted string literals. See below for a complete example. + + 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. Parameter flags is a + combination of flags, see below. + + SD_BUS_METHOD_WITH_ARGS() is a shorthand for calling + SD_BUS_METHOD_WITH_ARGS_OFFSET() with an offset of zero. + + + + + SD_BUS_METHOD_WITH_NAMES_OFFSET() + SD_BUS_METHOD_WITH_NAMES() + 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. in_names and + out_names should be created using the + SD_BUS_PARAM() macro, see below. In all other regards, this macro behaves + exactly the same as SD_BUS_METHOD_WITH_ARGS_OFFSET(). + + 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. + + Prefer using SD_BUS_METHOD_WITH_ARGS_OFFSET() and + SD_BUS_METHOD_WITH_ARGS() over these macros as they allow specifying argument + types and names next to each other which is less error-prone than first specifying all argument + types followed by specifying all argument names. + + + + + SD_BUS_SIGNAL_WITH_ARGS() + + Declare a D-Bus signal with the name member and + arguments args. args expects a sequence of + argument type/name pairs wrapped in the SD_BUS_ARGS() macro. The elements at + even indices in this list describe the types of the signal's arguments. The signal's parameter + signature is the concatenation of all the string literals at even indices in + args. If a signal has no parameters, pass + SD_BUS_NO_ARGS to args. The elements at uneven + indices describe the names of the signal's arguments. Parameter flags is + a combination of flags. See below for a complete example. + + + + SD_BUS_SIGNAL_WITH_NAMES() + SD_BUS_SIGNAL() + + Declare a D-Bus signal with the name member, + parameter signature signature, and argument names + names. names should be + created using the SD_BUS_PARAM() macro, see below. + Parameter flags is a combination of flags, see below. + + + SD_BUS_SIGNAL() is equivalent to + SD_BUS_SIGNAL_WITH_NAMES() with the names parameter + unset (i.e. no parameter names). + + Prefer using SD_BUS_SIGNAL_WITH_ARGS() over these macros as it allows + specifying argument types and names next to each other which is less error-prone than first + specifying all argument types followed by specifying all argument names. + + + + + 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. + + 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_PARAM() + Parameter names should be wrapped in this macro, see the example below. + + + + + + + Flags + + The flags parameter is used to specify a combination of + D-Bus annotations. + + + + + SD_BUS_VTABLE_DEPRECATED + + Mark this vtable entry as deprecated using the + org.freedesktop.DBus.Deprecated annotation in introspection data. If + specified for SD_BUS_VTABLE_START(), the annotation is applied to the + enclosing interface. + + + + 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. + + + + SD_BUS_VTABLE_METHOD_NO_REPLY + + Mark this vtable entry as a method that will not return a reply using the + org.freedesktop.DBus.Method.NoReply annotation in introspection data. + + + + + SD_BUS_VTABLE_PROPERTY_CONST + SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE + 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. + + + + 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. + + + + SD_BUS_VTABLE_SENSITIVE + + Mark this vtable method entry as processing sensitive data. When set, + incoming method call messages and their outgoing reply messages are marked as sensitive using + sd_bus_message_sensitive3, + so that they are erased from memory when freed. + + + + SD_BUS_VTABLE_ABSOLUTE_OFFSET + + Mark this vtable method or property entry so that the user data pointer passed to + its associated handler functions is determined slightly differently: instead of adding the offset + parameter of the entry to the user data pointer specified during vtable registration, the offset is + passed directly, converted to a pointer, without taking the user data pointer specified during + vtable registration into account. + + + + SD_BUS_VTABLE_CAPABILITY(capability) + + Access to this vtable entry will be allowed if the calling process has the + capability capability, as described in + sd_bus_query_sender_privilege3. + If used for SD_BUS_VTABLE_START(), provides a default for all entries in the + array. If not specified, either for an individual entry or the whole array, + CAP_SYS_ADMIN is checked by default. See capabilities7 + for information about capabilities. + + Note that vtable entries may be marked as unprivileged and the whole bus may be marked as + trusted, see the discussion of SD_BUS_VTABLE_UNPRIVILEGED below. + + + + + SD_BUS_VTABLE_UNPRIVILEGED + + Mark this vtable entry as unprivileged. Access to privileged entries is limited to + users with appropriate capabilities as described above. In practice many vtable entries are marked + as unprivileged, and either are open to everyone, or the decision whether to allow access is taken + later, e.g. by delegating to polkit. + + The whole bus may be marked as trusted, in which case annotations at the entry level are + ignored, see + sd_bus_set_trusted3. + + + When not specified, the + org.freedesktop.systemd1.Privileged annotation with value + true will be shown in introspection data. + + Note that this page describes checks implemented in the D-Bus client. The D-Bus server has an + additional policy that may permit or deny connections, see + "CONFIGURATION FILE" in + dbus-daemon1. + + + + + + + + Examples + + + Create a simple listener on the bus + + + + 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: + + + + + + + Return Value + + On success, sd_bus_add_object_vtable() and + sd_bus_add_fallback_vtable() return a non-negative integer. On + failure, they return a negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + One of the required parameters is NULL or invalid. A + reserved D-Bus interface was passed as the interface parameter. + + + + + -ENOPKG + + The bus cannot be resolved. + + + + -ECHILD + + The bus was created in a different process. + + + + -ENOMEM + + Memory allocation failed. + + + + -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. + + + + -EEXIST + + This vtable has already been registered for this + interface and path. + + + + + + + + + + See Also + + + sd-bus3, + busctl1, + sd_bus_emit_properties_changed3, + sd_bus_emit_object_added3 + + + -- cgit v1.2.3