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.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
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_interfaces_added
</refname>
23 <refname>sd_bus_emit_interfaces_added_strv
</refname>
24 <refname>sd_bus_emit_interfaces_removed
</refname>
25 <refname>sd_bus_emit_interfaces_removed_strv
</refname>
26 <refname>sd_bus_emit_properties_changed
</refname>
27 <refname>sd_bus_emit_properties_changed_strv
</refname>
28 <refname>sd_bus_emit_object_added
</refname>
29 <refname>sd_bus_emit_object_removed
</refname>
31 <refpurpose>Convenience functions for emitting (standard) D-Bus signals
</refpurpose>
36 <funcsynopsisinfo>#include
<systemd/sd-bus-vtable.h
></funcsynopsisinfo>
39 <funcdef>int
<function>sd_bus_emit_signal
</function></funcdef>
40 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
41 <paramdef>const char *
<parameter>path
</parameter></paramdef>
42 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
43 <paramdef>const char *
<parameter>member
</parameter></paramdef>
44 <paramdef>const char *
<parameter>types
</parameter></paramdef>
45 <paramdef>...
</paramdef>
49 <funcdef>int
<function>sd_bus_emit_signalv
</function></funcdef>
50 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
51 <paramdef>const char *
<parameter>path
</parameter></paramdef>
52 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
53 <paramdef>const char *
<parameter>member
</parameter></paramdef>
54 <paramdef>const char *
<parameter>types
</parameter></paramdef>
55 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
59 <funcdef>int
<function>sd_bus_emit_interfaces_added
</function></funcdef>
60 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
61 <paramdef>const char *
<parameter>path
</parameter></paramdef>
62 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
63 <paramdef>...
</paramdef>
67 <funcdef>int
<function>sd_bus_emit_interfaces_added_strv
</function></funcdef>
68 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
69 <paramdef>const char *
<parameter>path
</parameter></paramdef>
70 <paramdef>const char **
<parameter>interfaces
</parameter></paramdef>
74 <funcdef>int
<function>sd_bus_emit_interfaces_removed
</function></funcdef>
75 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
76 <paramdef>const char *
<parameter>path
</parameter></paramdef>
77 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
78 <paramdef>...
</paramdef>
82 <funcdef>int
<function>sd_bus_emit_interfaces_removed_strv
</function></funcdef>
83 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
84 <paramdef>const char *
<parameter>path
</parameter></paramdef>
85 <paramdef>const char **
<parameter>interfaces
</parameter></paramdef>
89 <funcdef>int
<function>sd_bus_emit_properties_changed
</function></funcdef>
90 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
91 <paramdef>const char *
<parameter>path
</parameter></paramdef>
92 <paramdef>const char *
<parameter>interface
</parameter></paramdef>
93 <paramdef>const char *
<parameter>name
</parameter></paramdef>
94 <paramdef>...
</paramdef>
98 <funcdef>int
<function>sd_bus_emit_properties_changed_strv
</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>const char **
<parameter>names
</parameter></paramdef>
106 <funcdef>int
<function>sd_bus_emit_object_added
</function></funcdef>
107 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
108 <paramdef>const char *
<parameter>path
</parameter></paramdef>
112 <funcdef>int
<function>sd_bus_emit_object_removed
</function></funcdef>
113 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
114 <paramdef>const char *
<parameter>path
</parameter></paramdef>
120 <title>Description
</title>
122 <para><function>sd_bus_emit_signal()
</function> is a convenience function for initializing a
123 bus message object and emitting the corresponding D-Bus signal. It combines the
124 <citerefentry><refentrytitle>sd_bus_message_new_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
125 <citerefentry><refentrytitle>sd_bus_message_append
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
126 <citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
127 functions into a single function call.
<function>sd_bus_emit_signalv()
</function> is
128 equivalent to
<function>sd_bus_message_append()
</function>, except that it is called with a
129 <literal>va_list
</literal> instead of a variable number of arguments.
</para>
131 <para><function>sd_bus_emit_interfaces_added()
</function> and
132 <function>sd_bus_emit_interfaces_removed()
</function> are used to implement the
133 <function>InterfacesAdded
</function> and
<function>InterfacesRemoved
</function> signals of the
134 <constant>org.freedesktop.DBus.ObjectManager
</constant> interface. They take a path whose
135 interfaces have been modified as an argument and a variable list of interfaces that have been
136 added or removed, respectively. The final argument passed to
137 <function>sd_bus_emit_interfaces_added()
</function> and
138 <function>sd_bus_emit_interfaces_removed()
</function> <emphasis>must
</emphasis> be
139 <constant>NULL
</constant>. This allows both functions to safely determine the number of passed
140 interface arguments.
<function>sd_bus_emit_interfaces_added_strv()
</function> and
141 <function>sd_bus_emit_interfaces_removed_strv()
</function> are identical to their respective
142 counterparts but both take the list of interfaces as a single argument instead of a variable
143 number of arguments.
</para>
145 <para><function>sd_bus_emit_properties_changed()
</function> is used to implement the
146 <function>PropertiesChanged
</function> signal of the
147 <constant>org.freedesktop.DBus.Properties
</constant> interface. It takes an object path,
148 interface and a variable list of property names as its arguments. The final argument passed to
149 <function>sd_bus_emit_properties_changed()
</function> <emphasis>must
</emphasis> be
150 <constant>NULL
</constant>. This allows it to safely determine the number of passed property
151 names.
<function>sd_bus_emit_properties_changed_strv()
</function> is identical to
152 <function>sd_bus_emit_properties_changed()
</function> but takes the list of property names as a
153 single argument instead of a variable number of arguments.
</para>
155 <para><function>sd_bus_emit_object_added()
</function> and
156 <function>sd_bus_emit_object_removed()
</function> are convenience functions for emitting the
157 <function>InterfacesAdded
</function> or
<function>InterfacesRemoved
</function> signals for all
158 interfaces registered on a specific object path, respectively. This includes any parent fallback
159 vtables if they are not overridden by a more applicable child vtable. It also includes all the
160 standard D-Bus interfaces implemented by sd-bus itself on any registered object.
</para>
162 <para>Note that
<function>sd_bus_emit_interfaces_added()
</function>,
163 <function>sd_bus_emit_interfaces_removed()
</function>,
164 <function>sd_bus_emit_object_added()
</function> and
165 <function>sd_bus_emit_object_removed()
</function> require an object manager to have been
166 registered on the given object path or one of its parent object paths using
167 <citerefentry><refentrytitle>sd_bus_add_object_manager
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
172 <title>Return Value
</title>
174 <para>On success, these functions return a non-negative integer. On failure, they return a
175 negative errno-style error code.
</para>
178 <title>Errors
</title>
180 <para>Returned errors may indicate the following problems:
</para>
184 <term><constant>-EINVAL
</constant></term>
186 <listitem><para>One of the required parameters is
<constant>NULL
</constant> or invalid. A
187 reserved D-Bus interface was passed as the
<replaceable>interface
</replaceable> parameter.
192 <term><constant>-ENOPKG
</constant></term>
194 <listitem><para>The bus cannot be resolved.
</para></listitem>
198 <term><constant>-ECHILD
</constant></term>
200 <listitem><para>The bus was created in a different process.
</para></listitem>
204 <term><constant>-ENOMEM
</constant></term>
206 <listitem><para>Memory allocation failed.
</para></listitem>
210 <term><constant>-ESRCH
</constant></term>
212 <listitem><para>One of
<function>sd_bus_emit_interfaces_added()
</function>,
213 <function>sd_bus_emit_interfaces_removed()
</function>,
214 <function>sd_bus_emit_object_added()
</function> or
215 <function>sd_bus_emit_object_removed()
</function> was called on an object without an
216 object manager registered on its own object path or one of its parent object paths.
221 <para>See the man pages of
222 <citerefentry><refentrytitle>sd_bus_message_new_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
223 <citerefentry><refentrytitle>sd_bus_message_append
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
224 <citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
225 for more possible errors.
</para>
229 <xi:include href=
"libsystemd-pkgconfig.xml" />
232 <title>See Also
</title>
235 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
236 <citerefentry><refentrytitle>busctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
237 <citerefentry><refentrytitle>sd_bus_message_new_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
238 <citerefentry><refentrytitle>sd_bus_message_append
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
239 <citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
240 <citerefentry><refentrytitle>sd_bus_call_method
</refentrytitle><manvolnum>3</manvolnum></citerefentry>