1SD_BUS_EMIT_SIGNAL(3) sd_bus_emit_signal SD_BUS_EMIT_SIGNAL(3)
2
6 sd_bus_emit_signal, sd_bus_emit_signalv, sd_bus_emit_signal_to,
7 sd_bus_emit_signal_tov, sd_bus_emit_interfaces_added,
8 sd_bus_emit_interfaces_added_strv, sd_bus_emit_interfaces_removed,
9 sd_bus_emit_interfaces_removed_strv, sd_bus_emit_properties_changed,
10 sd_bus_emit_properties_changed_strv, sd_bus_emit_object_added,
11 sd_bus_emit_object_removed - Convenience functions for emitting
12 (standard) D-Bus signals
13
15 #include <systemd/sd-bus-vtable.h>
16 int sd_bus_emit_signal(sd_bus *bus, const char *path,
18 const char *interface, const char *member,
19 const char *types, ...);
20 int sd_bus_emit_signalv(sd_bus *bus, const char *path,
22 const char *interface, const char *member,
23 const char *types, va_list ap);
24 int sd_bus_emit_signal_to(sd_bus *bus, const char *destination,
26 const char *path, const char *interface,
27 const char *member, const char *types, ...);
28 int sd_bus_emit_signal_tov(sd_bus *bus, const char *destination,
30 const char *path, const char *interface,
31 const char *member, const char *types,
32 va_list ap);
33 int sd_bus_emit_interfaces_added(sd_bus *bus, const char *path,
35 const char *interface, ...);
36 int sd_bus_emit_interfaces_added_strv(sd_bus *bus, const char *path,
38 const char **interfaces);
39 int sd_bus_emit_interfaces_removed(sd_bus *bus, const char *path,
41 const char *interface, ...);
42 int sd_bus_emit_interfaces_removed_strv(sd_bus *bus, const char *path,
44 const char **interfaces);
45 int sd_bus_emit_properties_changed(sd_bus *bus, const char *path,
47 const char *interface,
48 const char *name, ...);
49 int sd_bus_emit_properties_changed_strv(sd_bus *bus, const char *path,
51 const char *interface,
52 const char **names);
53 int sd_bus_emit_object_added(sd_bus *bus, const char *path);
55 int sd_bus_emit_object_removed(sd_bus *bus, const char *path);
57
59 sd_bus_emit_signal() is a convenience function for initializing a bus
60 message object and emitting the corresponding D-Bus signal. It combines
61 the sd_bus_message_new_signal(3), sd_bus_message_append(3) and
62 sd_bus_send(3) functions into a single function call.
63 sd_bus_emit_signalv() is equivalent to sd_bus_message_append(), except
64 that it is called with a "va_list" instead of a variable number of
65 arguments.
66 sd_bus_emit_signal_to() and sd_bus_emit_signal_tov() are identical to
68 sd_bus_emit_signal() and sd_bus_emit_signalv(), except that they can
69 emit the signal to a single destination. Give destination as NULL to
70 broadcast the signal.
71 sd_bus_emit_interfaces_added() and sd_bus_emit_interfaces_removed() are
73 used to implement the InterfacesAdded and InterfacesRemoved signals of
74 the org.freedesktop.DBus.ObjectManager interface. They take a path
75 whose interfaces have been modified as an argument and a variable list
76 of interfaces that have been added or removed, respectively. The final
77 argument passed to sd_bus_emit_interfaces_added() and
78 sd_bus_emit_interfaces_removed() must be NULL. This allows both
79 functions to safely determine the number of passed interface arguments.
80 sd_bus_emit_interfaces_added_strv() and
81 sd_bus_emit_interfaces_removed_strv() are identical to their respective
82 counterparts but both take the list of interfaces as a single argument
83 instead of a variable number of arguments.
84 sd_bus_emit_properties_changed() is used to implement the
86 PropertiesChanged signal of the org.freedesktop.DBus.Properties
87 interface. It takes an object path, interface and a variable list of
88 property names as its arguments. The final argument passed to
89 sd_bus_emit_properties_changed() must be NULL. This allows it to safely
90 determine the number of passed property names.
91 sd_bus_emit_properties_changed_strv() is identical to
92 sd_bus_emit_properties_changed() but takes the list of property names
93 as a single argument instead of a variable number of arguments.
94 sd_bus_emit_object_added() and sd_bus_emit_object_removed() are
96 convenience functions for emitting the InterfacesAdded or
97 InterfacesRemoved signals for all interfaces registered on a specific
98 object path, respectively. This includes any parent fallback vtables if
99 they are not overridden by a more applicable child vtable. It also
100 includes all the standard D-Bus interfaces implemented by sd-bus itself
101 on any registered object.
102 Note that sd_bus_emit_interfaces_added(),
104 sd_bus_emit_interfaces_removed(), sd_bus_emit_object_added() and
105 sd_bus_emit_object_removed() require an object manager to have been
106 registered on the given object path or one of its parent object paths
107 using sd_bus_add_object_manager(3).
108
110 On success, these functions return a non-negative integer. On failure,
111 they return a negative errno-style error code.
112 Errors
114 Returned errors may indicate the following problems:
115 -EINVAL
117 One of the required parameters is NULL or invalid. A reserved D-Bus
118 interface was passed as the interface parameter.
119 -ENOPKG
121 The bus cannot be resolved.
122 -ECHILD
124 The bus was created in a different process, library or module
125 instance.
126 -ENOMEM
128 Memory allocation failed.
129 -ESRCH
131 One of sd_bus_emit_interfaces_added(),
132 sd_bus_emit_interfaces_removed(), sd_bus_emit_object_added() or
133 sd_bus_emit_object_removed() was called on an object without an
134 object manager registered on its own object path or one of its
135 parent object paths.
136 See the man pages of sd_bus_message_new_signal(3),
138 sd_bus_message_append(3) and sd_bus_send(3) for more possible errors.
139
141 Functions described here are available as a shared library, which can
142 be compiled against and linked to with the libsystemd pkg-config(1)
143 file.
144 The code described here uses getenv(3), which is declared to be not
146 multi-thread-safe. This means that the code calling the functions
147 described here must not call setenv(3) from a parallel thread. It is
148 recommended to only do calls to setenv() from an early phase of the
149 program when no other threads have been started.
150
152 sd-bus(3), busctl(1), sd_bus_message_new_signal(3),
153 sd_bus_message_append(3), sd_bus_send(3), sd_bus_call_method(3)
154systemd 254 SD_BUS_EMIT_SIGNAL(3)