1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd_bus_emit_signal"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd_bus_emit_signal
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd_bus_emit_signal
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd_bus_emit_signal
</refname>
21 <refname>sd_bus_emit_signalv
</refname>
22 <refname>sd_bus_emit_signal_to
</refname>
23 <refname>sd_bus_emit_signal_tov
</refname>
24 <refname>sd_bus_emit_interfaces_added
</refname>
25 <refname>sd_bus_emit_interfaces_added_strv
</refname>
26 <refname>sd_bus_emit_interfaces_removed
</refname>
27 <refname>sd_bus_emit_interfaces_removed_strv
</refname>
28 <refname>sd_bus_emit_properties_changed
</refname>
29 <refname>sd_bus_emit_properties_changed_strv
</refname>
30 <refname>sd_bus_emit_object_added
</refname>
31 <refname>sd_bus_emit_object_removed
</refname>
33 <refpurpose>Convenience functions for emitting (standard) D-Bus signals
</refpurpose>
38 <funcsynopsisinfo>#include
<systemd/sd-bus-vtable.h
></funcsynopsisinfo>
41 <funcdef>int
<function>sd_bus_emit_signal
</function></funcdef>
42 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
43 <paramdef>const char *
<parameter>path
</parameter></paramdef>
44 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
45 <paramdef>const char *
<parameter>member
</parameter></paramdef>
46 <paramdef>const char *
<parameter>types
</parameter></paramdef>
47 <paramdef>...
</paramdef>
51 <funcdef>int
<function>sd_bus_emit_signalv
</function></funcdef>
52 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
53 <paramdef>const char *
<parameter>path
</parameter></paramdef>
54 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
55 <paramdef>const char *
<parameter>member
</parameter></paramdef>
56 <paramdef>const char *
<parameter>types
</parameter></paramdef>
57 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
61 <funcdef>int
<function>sd_bus_emit_signal_to
</function></funcdef>
62 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
63 <paramdef>const char *
<parameter>destination
</parameter></paramdef>
64 <paramdef>const char *
<parameter>path
</parameter></paramdef>
65 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
66 <paramdef>const char *
<parameter>member
</parameter></paramdef>
67 <paramdef>const char *
<parameter>types
</parameter></paramdef>
68 <paramdef>...
</paramdef>
72 <funcdef>int
<function>sd_bus_emit_signal_tov
</function></funcdef>
73 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
74 <paramdef>const char *
<parameter>destination
</parameter></paramdef>
75 <paramdef>const char *
<parameter>path
</parameter></paramdef>
76 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
77 <paramdef>const char *
<parameter>member
</parameter></paramdef>
78 <paramdef>const char *
<parameter>types
</parameter></paramdef>
79 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
83 <funcdef>int
<function>sd_bus_emit_interfaces_added
</function></funcdef>
84 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
85 <paramdef>const char *
<parameter>path
</parameter></paramdef>
86 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
87 <paramdef>...
</paramdef>
91 <funcdef>int
<function>sd_bus_emit_interfaces_added_strv
</function></funcdef>
92 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
93 <paramdef>const char *
<parameter>path
</parameter></paramdef>
94 <paramdef>const char **
<parameter>interfaces
</parameter></paramdef>
98 <funcdef>int
<function>sd_bus_emit_interfaces_removed
</function></funcdef>
99 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
100 <paramdef>const char *
<parameter>path
</parameter></paramdef>
101 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
102 <paramdef>...
</paramdef>
106 <funcdef>int
<function>sd_bus_emit_interfaces_removed_strv
</function></funcdef>
107 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
108 <paramdef>const char *
<parameter>path
</parameter></paramdef>
109 <paramdef>const char **
<parameter>interfaces
</parameter></paramdef>
113 <funcdef>int
<function>sd_bus_emit_properties_changed
</function></funcdef>
114 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
115 <paramdef>const char *
<parameter>path
</parameter></paramdef>
116 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
117 <paramdef>const char *
<parameter>name
</parameter></paramdef>
118 <paramdef>...
</paramdef>
122 <funcdef>int
<function>sd_bus_emit_properties_changed_strv
</function></funcdef>
123 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
124 <paramdef>const char *
<parameter>path
</parameter></paramdef>
125 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
126 <paramdef>const char **
<parameter>names
</parameter></paramdef>
130 <funcdef>int
<function>sd_bus_emit_object_added
</function></funcdef>
131 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
132 <paramdef>const char *
<parameter>path
</parameter></paramdef>
136 <funcdef>int
<function>sd_bus_emit_object_removed
</function></funcdef>
137 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
138 <paramdef>const char *
<parameter>path
</parameter></paramdef>
144 <title>Description
</title>
146 <para><function>sd_bus_emit_signal()
</function> is a convenience function for initializing a
147 bus message object and emitting the corresponding D-Bus signal. It combines the
148 <citerefentry><refentrytitle>sd_bus_message_new_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
149 <citerefentry><refentrytitle>sd_bus_message_append
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
150 <citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
151 functions into a single function call.
<function>sd_bus_emit_signalv()
</function> is
152 equivalent to
<function>sd_bus_message_append()
</function>, except that it is called with a
153 <literal>va_list
</literal> instead of a variable number of arguments.
</para>
155 <para><function>sd_bus_emit_signal_to()
</function> and
<function>sd_bus_emit_signal_tov()
</function> are
156 identical to
<function>sd_bus_emit_signal()
</function> and
<function>sd_bus_emit_signalv()
</function>, except
157 that they can emit the signal to a single destination. Give
<parameter>destination
</parameter> as
158 <constant>NULL
</constant> to broadcast the signal.
</para>
160 <para><function>sd_bus_emit_interfaces_added()
</function> and
161 <function>sd_bus_emit_interfaces_removed()
</function> are used to implement the
162 <function>InterfacesAdded
</function> and
<function>InterfacesRemoved
</function> signals of the
163 <constant>org.freedesktop.DBus.ObjectManager
</constant> interface. They take a path whose
164 interfaces have been modified as an argument and a variable list of interfaces that have been
165 added or removed, respectively. The final argument passed to
166 <function>sd_bus_emit_interfaces_added()
</function> and
167 <function>sd_bus_emit_interfaces_removed()
</function> <emphasis>must
</emphasis> be
168 <constant>NULL
</constant>. This allows both functions to safely determine the number of passed
169 interface arguments.
<function>sd_bus_emit_interfaces_added_strv()
</function> and
170 <function>sd_bus_emit_interfaces_removed_strv()
</function> are identical to their respective
171 counterparts but both take the list of interfaces as a single argument instead of a variable
172 number of arguments.
</para>
174 <para><function>sd_bus_emit_properties_changed()
</function> is used to implement the
175 <function>PropertiesChanged
</function> signal of the
176 <constant>org.freedesktop.DBus.Properties
</constant> interface. It takes an object path,
177 interface and a variable list of property names as its arguments. The final argument passed to
178 <function>sd_bus_emit_properties_changed()
</function> <emphasis>must
</emphasis> be
179 <constant>NULL
</constant>. This allows it to safely determine the number of passed property
180 names.
<function>sd_bus_emit_properties_changed_strv()
</function> is identical to
181 <function>sd_bus_emit_properties_changed()
</function> but takes the list of property names as a
182 single argument instead of a variable number of arguments.
</para>
184 <para><function>sd_bus_emit_object_added()
</function> and
185 <function>sd_bus_emit_object_removed()
</function> are convenience functions for emitting the
186 <function>InterfacesAdded
</function> or
<function>InterfacesRemoved
</function> signals for all
187 interfaces registered on a specific object path, respectively. This includes any parent fallback
188 vtables if they are not overridden by a more applicable child vtable. It also includes all the
189 standard D-Bus interfaces implemented by sd-bus itself on any registered object.
</para>
191 <para>Note that
<function>sd_bus_emit_interfaces_added()
</function>,
192 <function>sd_bus_emit_interfaces_removed()
</function>,
193 <function>sd_bus_emit_object_added()
</function> and
194 <function>sd_bus_emit_object_removed()
</function> require an object manager to have been
195 registered on the given object path or one of its parent object paths using
196 <citerefentry><refentrytitle>sd_bus_add_object_manager
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
201 <title>Return Value
</title>
203 <para>On success, these functions return a non-negative integer. On failure, they return a
204 negative errno-style error code.
</para>
207 <title>Errors
</title>
209 <para>Returned errors may indicate the following problems:
</para>
213 <term><constant>-EINVAL
</constant></term>
215 <listitem><para>One of the required parameters is
<constant>NULL
</constant> or invalid. A
216 reserved D-Bus interface was passed as the
<replaceable>interface
</replaceable> parameter.
221 <term><constant>-ENOPKG
</constant></term>
223 <listitem><para>The bus cannot be resolved.
</para></listitem>
227 <term><constant>-ECHILD
</constant></term>
229 <listitem><para>The bus was created in a different process, library or module instance.
</para></listitem>
233 <term><constant>-ENOMEM
</constant></term>
235 <listitem><para>Memory allocation failed.
</para></listitem>
239 <term><constant>-ESRCH
</constant></term>
241 <listitem><para>One of
<function>sd_bus_emit_interfaces_added()
</function>,
242 <function>sd_bus_emit_interfaces_removed()
</function>,
243 <function>sd_bus_emit_object_added()
</function> or
244 <function>sd_bus_emit_object_removed()
</function> was called on an object without an
245 object manager registered on its own object path or one of its parent object paths.
250 <para>See the man pages of
251 <citerefentry><refentrytitle>sd_bus_message_new_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
252 <citerefentry><refentrytitle>sd_bus_message_append
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
253 <citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
254 for more possible errors.
</para>
258 <xi:include href=
"libsystemd-pkgconfig.xml" />
261 <title>History
</title>
262 <para><function>sd_bus_emit_signal()
</function>,
263 <function>sd_bus_emit_interfaces_added()
</function>,
264 <function>sd_bus_emit_interfaces_added_strv()
</function>,
265 <function>sd_bus_emit_interfaces_removed()
</function>,
266 <function>sd_bus_emit_interfaces_removed_strv()
</function>,
267 <function>sd_bus_emit_properties_changed()
</function>,
268 <function>sd_bus_emit_properties_changed_strv()
</function>, were added in version
221.
</para>
269 <para><function>sd_bus_emit_object_added()
</function>, and
270 <function>sd_bus_emit_object_removed()
</function> were added in version
222.
</para>
271 <para><function>sd_bus_emit_signalv()
</function> was added in version
246.
</para>
272 <para><function>sd_bus_emit_signal_to()
</function> and
273 <function>sd_bus_emit_signal_tov()
</function> were added in version
253.
</para>
277 <title>See Also
</title>
279 <para><simplelist type=
"inline">
280 <member><citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
281 <member><citerefentry><refentrytitle>busctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
282 <member><citerefentry><refentrytitle>sd_bus_message_new_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
283 <member><citerefentry><refentrytitle>sd_bus_message_append
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
284 <member><citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
285 <member><citerefentry><refentrytitle>sd_bus_call_method
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>