diff --git a/man/rules/meson.build b/man/rules/meson.build index 1667c7de99..a18d83bc1c 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -215,6 +215,18 @@ manpages = [ 'sd_bus_open_user_with_description', 'sd_bus_open_with_description'], ''], + ['sd_bus_emit_signal', + '3', + ['sd_bus_emit_interfaces_added', + 'sd_bus_emit_interfaces_added_strv', + 'sd_bus_emit_interfaces_removed', + 'sd_bus_emit_interfaces_removed_strv', + 'sd_bus_emit_object_added', + 'sd_bus_emit_object_removed', + 'sd_bus_emit_properties_changed', + 'sd_bus_emit_properties_changed_strv', + 'sd_bus_emit_signalv'], + ''], ['sd_bus_enqueue_for_read', '3', [], ''], ['sd_bus_error', '3', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 7b80be85ab..052bf2fbde 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -57,6 +57,16 @@ sd_bus_creds_new_from_pid3, sd_bus_close3, sd_bus_default3, +sd_bus_emit_interfaces_added3, +sd_bus_emit_interfaces_added_strv3, +sd_bus_emit_interfaces_removed3, +sd_bus_emit_interfaces_removed_strv3, +sd_bus_emit_object_added3, +sd_bus_emit_object_removed3, +sd_bus_emit_properties_changed3, +sd_bus_emit_properties_changed_strv3, +sd_bus_emit_signal3, +sd_bus_emit_signalv3, sd-bus-errors3, sd_bus_error3, sd_bus_error_add_map3, diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml index 373609f042..c1e4b5f686 100644 --- a/man/sd_bus_add_object.xml +++ b/man/sd_bus_add_object.xml @@ -550,7 +550,9 @@ sd-bus3, - busctl1 + busctl1, + sd_bus_emit_properties_changed3, + sd_bus_emit_object_added3 diff --git a/man/sd_bus_add_object_manager.xml b/man/sd_bus_add_object_manager.xml index c8bfcdd016..32569788b6 100644 --- a/man/sd_bus_add_object_manager.xml +++ b/man/sd_bus_add_object_manager.xml @@ -111,6 +111,7 @@ sd-bus3, busctl1, sd_bus_add_object_vtable3, + sd_bus_emit_interfaces_added3, sd_bus_slot_unref3 diff --git a/man/sd_bus_call_method.xml b/man/sd_bus_call_method.xml index e1e9ad3b48..6348a4ce77 100644 --- a/man/sd_bus_call_method.xml +++ b/man/sd_bus_call_method.xml @@ -134,6 +134,7 @@ sd_bus_message_append3, sd_bus_call3, sd_bus_set_property3, + sd_bus_emit_signal3 diff --git a/man/sd_bus_emit_signal.xml b/man/sd_bus_emit_signal.xml new file mode 100644 index 0000000000..26ec7d1d70 --- /dev/null +++ b/man/sd_bus_emit_signal.xml @@ -0,0 +1,243 @@ + + + + + + + + sd_bus_emit_signal + systemd + + + + sd_bus_emit_signal + 3 + + + + sd_bus_emit_signal + sd_bus_emit_signalv + sd_bus_emit_interfaces_added + sd_bus_emit_interfaces_added_strv + sd_bus_emit_interfaces_removed + sd_bus_emit_interfaces_removed_strv + sd_bus_emit_properties_changed + sd_bus_emit_properties_changed_strv + sd_bus_emit_object_added + sd_bus_emit_object_removed + + Convenience functions for emitting (standard) D-Bus signals + + + + + #include <systemd/sd-bus-vtable.h> + + + int sd_bus_emit_signal + sd_bus *bus + const char *path + const char *interface + const char *member + const char *types + ... + + + + int sd_bus_emit_signalv + sd_bus *bus + const char *path + const char *interface + const char *member + const char *types + va_list ap + + + + int sd_bus_emit_interfaces_added + sd_bus *bus + const char *path + const char *interface + ... + + + + int sd_bus_emit_interfaces_added_strv + sd_bus *bus + const char *path + const char **interfaces + + + + int sd_bus_emit_interfaces_removed + sd_bus *bus + const char *path + const char *interface + ... + + + + int sd_bus_emit_interfaces_removed_strv + sd_bus *bus + const char *path + const char **interfaces + + + + int sd_bus_emit_properties_changed + sd_bus *bus + const char *path + const char *interface + const char *name + ... + + + + int sd_bus_emit_properties_changed_strv + sd_bus *bus + const char *path + const char *interface + const char **names + + + + int sd_bus_emit_object_added + sd_bus *bus + const char *path + + + + int sd_bus_emit_object_removed + sd_bus *bus + const char *path + + + + + + Description + + sd_bus_emit_signal() is a convenience function for initializing a + bus message object and emitting the corresponding D-Bus signal. It combines the + sd_bus_message_new_signal3, + sd_bus_message_append3 and + sd_bus_send3 + functions into a single function call. sd_bus_emit_signalv() is + equivalent to sd_bus_message_append(), except that it is called with a + va_list instead of a variable number of arguments. + + sd_bus_emit_interfaces_added() and + sd_bus_emit_interfaces_removed() are used to implement the + InterfacesAdded and InterfacesRemoved signals of the + org.freedesktop.DBus.ObjectManager interface. They take a path whose + interfaces have been modified as an argument and a variable list of interfaces that have been + added or removed, respectively. The final argument passed to + sd_bus_emit_interfaces_added() and + sd_bus_emit_interfaces_removed() must be + NULL. This allows both functions to safely determine the number of passed + interface arguments. sd_bus_emit_interfaces_added_strv() and + sd_bus_emit_interfaces_removed_strv() are identical to their respective + counterparts but both take the list of interfaces as a single argument instead of a variable + number of arguments. + + sd_bus_emit_properties_changed() is used to implement the + PropertiesChanged signal of the + org.freedesktop.DBus.Properties interface. It takes an object path, + interface and a variable list of property names as its arguments. The final argument passed to + sd_bus_emit_properties_changed() must be + NULL. This allows it to safely determine the number of passed property + names. sd_bus_emit_properties_changed_strv() is identical to + sd_bus_emit_properties_changed() but takes the list of property names as a + single argument instead of a variable number of arguments. + + sd_bus_emit_object_added() and + sd_bus_emit_object_removed() are convenience functions for emitting the + InterfacesAdded or InterfacesRemoved signals for all + interfaces registered on a specific object path, respectively. This includes any parent fallback + vtables if they are not overridden by a more applicable child vtable. It also includes all the + standard D-Bus interfaces implemented by sd-bus itself on any registered object. + + Note that sd_bus_emit_interfaces_added(), + sd_bus_emit_interfaces_removed(), + sd_bus_emit_object_added() and + sd_bus_emit_object_removed() require an object manager to have been + registered on the given object path or one of its parent object paths using + sd_bus_add_object_manager3. + + + + + Return Value + + On success, these functions 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. + + + + -ESRCH + + One of sd_bus_emit_interfaces_added(), + sd_bus_emit_interfaces_removed(), + sd_bus_emit_object_added() or + sd_bus_emit_object_removed() was called on an object without an + object manager registered on its own object path or one of its parent object paths. + + + + + See the man pages of + sd_bus_message_new_signal3, + sd_bus_message_append3 and + sd_bus_send3 + for more possible errors. + + + + + + + See Also + + + sd-bus3, + busctl1, + sd_bus_message_new_signal3, + sd_bus_message_append3, + sd_bus_send3, + sd_bus_call_method3 + + + diff --git a/man/sd_bus_message_new_signal.xml b/man/sd_bus_message_new_signal.xml index 61619304db..97afcd5c59 100644 --- a/man/sd_bus_message_new_signal.xml +++ b/man/sd_bus_message_new_signal.xml @@ -113,7 +113,8 @@ systemd1, - sd-bus3 + sd-bus3, + sd_bus_emit_signal3