sd_bus_emit_properties_changed(3)

1SD_BUS_EMIT_SIGNAL(3)         sd_bus_emit_signal         SD_BUS_EMIT_SIGNAL(3)
2
3
4

NAME

6       sd_bus_emit_signal, sd_bus_emit_signalv, sd_bus_emit_interfaces_added,
7       sd_bus_emit_interfaces_added_strv, sd_bus_emit_interfaces_removed,
8       sd_bus_emit_interfaces_removed_strv, sd_bus_emit_properties_changed,
9       sd_bus_emit_properties_changed_strv, sd_bus_emit_object_added,
10       sd_bus_emit_object_removed - Convenience functions for emitting
11       (standard) D-Bus signals
12

SYNOPSIS

14       #include <systemd/sd-bus-vtable.h>
15
16       int sd_bus_emit_signal(sd_bus *bus, const char *path,
17                              const char *interface, const char *member,
18                              const char *types, ...);
19
20       int sd_bus_emit_signalv(sd_bus *bus, const char *path,
21                               const char *interface, const char *member,
22                               const char *types, va_list ap);
23
24       int sd_bus_emit_interfaces_added(sd_bus *bus, const char *path,
25                                        const char *interface, ...);
26
27       int sd_bus_emit_interfaces_added_strv(sd_bus *bus, const char *path,
28                                             const char **interfaces);
29
30       int sd_bus_emit_interfaces_removed(sd_bus *bus, const char *path,
31                                          const char *interface, ...);
32
33       int sd_bus_emit_interfaces_removed_strv(sd_bus *bus, const char *path,
34                                               const char **interfaces);
35
36       int sd_bus_emit_properties_changed(sd_bus *bus, const char *path,
37                                          const char *interface,
38                                          const char *name, ...);
39
40       int sd_bus_emit_properties_changed_strv(sd_bus *bus, const char *path,
41                                               const char *interface,
42                                               const char **names);
43
44       int sd_bus_emit_object_added(sd_bus *bus, const char *path);
45
46       int sd_bus_emit_object_removed(sd_bus *bus, const char *path);
47

DESCRIPTION

49       sd_bus_emit_signal() is a convenience function for initializing a bus
50       message object and emitting the corresponding D-Bus signal. It combines
51       the sd_bus_message_new_signal(3), sd_bus_message_append(3) and
52       sd_bus_send(3) functions into a single function call.
53       sd_bus_emit_signalv() is equivalent to sd_bus_message_append(), except
54       that it is called with a "va_list" instead of a variable number of
55       arguments.
56
57       sd_bus_emit_interfaces_added() and sd_bus_emit_interfaces_removed() are
58       used to implement the InterfacesAdded and InterfacesRemoved signals of
59       the org.freedesktop.DBus.ObjectManager interface. They take a path
60       whose interfaces have been modified as an argument and a variable list
61       of interfaces that have been added or removed, respectively. The final
62       argument passed to sd_bus_emit_interfaces_added() and
63       sd_bus_emit_interfaces_removed() must be NULL. This allows both
64       functions to safely determine the number of passed interface arguments.
65       sd_bus_emit_interfaces_added_strv() and
66       sd_bus_emit_interfaces_removed_strv() are identical to their respective
67       counterparts but both take the list of interfaces as a single argument
68       instead of a variable number of arguments.
69
70       sd_bus_emit_properties_changed() is used to implement the
71       PropertiesChanged signal of the org.freedesktop.DBus.Properties
72       interface. It takes an object path, interface and a variable list of
73       property names as its arguments. The final argument passed to
74       sd_bus_emit_properties_changed() must be NULL. This allows it to safely
75       determine the number of passed property names.
76       sd_bus_emit_properties_changed_strv() is identical to
77       sd_bus_emit_properties_changed() but takes the list of property names
78       as a single argument instead of a variable number of arguments.
79
80       sd_bus_emit_object_added() and sd_bus_emit_object_removed() are
81       convenience functions for emitting the InterfacesAdded or
82       InterfacesRemoved signals for all interfaces registered on a specific
83       object path, respectively. This includes any parent fallback vtables if
84       they are not overridden by a more applicable child vtable. It also
85       includes all the standard D-Bus interfaces implemented by sd-bus itself
86       on any registered object.
87
88       Note that sd_bus_emit_interfaces_added(),
89       sd_bus_emit_interfaces_removed(), sd_bus_emit_object_added() and
90       sd_bus_emit_object_removed() require an object manager to have been
91       registered on the given object path or one of its parent object paths
92       using sd_bus_add_object_manager(3).
93

RETURN VALUE

95       On success, these functions return a non-negative integer. On failure,
96       they return a negative errno-style error code.
97
98   Errors
99       Returned errors may indicate the following problems:
100
101       -EINVAL
102           One of the required parameters is NULL or invalid. A reserved D-Bus
103           interface was passed as the interface parameter.
104
105       -ENOPKG
106           The bus cannot be resolved.
107
108       -ECHILD
109           The bus was created in a different process.
110
111       -ENOMEM
112           Memory allocation failed.
113
114       -ESRCH
115           One of sd_bus_emit_interfaces_added(),
116           sd_bus_emit_interfaces_removed(), sd_bus_emit_object_added() or
117           sd_bus_emit_object_removed() was called on an object without an
118           object manager registered on its own object path or one of its
119           parent object paths.
120
121       See the man pages of sd_bus_message_new_signal(3),
122       sd_bus_message_append(3) and sd_bus_send(3) for more possible errors.
123

NOTES

125       These APIs are implemented as a shared library, which can be compiled
126       and linked to with the libsystemd pkg-config(1) file.
127

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO