2020-04-19 21:32:54 +03:00
<?xml version='1.0'?> <!-- * - nxml - * -->
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2020-04-19 21:32:54 +03:00
<refentry id= "sd_bus_emit_signal"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo >
<title > sd_bus_emit_signal</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > sd_bus_emit_signal</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_bus_emit_signal</refname>
<refname > sd_bus_emit_signalv</refname>
2022-10-31 23:11:48 +03:00
<refname > sd_bus_emit_signal_to</refname>
<refname > sd_bus_emit_signal_tov</refname>
2020-04-19 21:32:54 +03:00
<refname > sd_bus_emit_interfaces_added</refname>
<refname > sd_bus_emit_interfaces_added_strv</refname>
<refname > sd_bus_emit_interfaces_removed</refname>
<refname > sd_bus_emit_interfaces_removed_strv</refname>
<refname > sd_bus_emit_properties_changed</refname>
<refname > sd_bus_emit_properties_changed_strv</refname>
<refname > sd_bus_emit_object_added</refname>
<refname > sd_bus_emit_object_removed</refname>
<refpurpose > Convenience functions for emitting (standard) D-Bus signals</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-bus-vtable.h> </funcsynopsisinfo>
<funcprototype >
<funcdef > int <function > sd_bus_emit_signal</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
<paramdef > const char *<parameter > types</parameter> </paramdef>
<paramdef > ...</paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_signalv</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
<paramdef > const char *<parameter > types</parameter> </paramdef>
<paramdef > va_list <parameter > ap</parameter> </paramdef>
</funcprototype>
2022-10-31 23:11:48 +03:00
<funcprototype >
<funcdef > int <function > sd_bus_emit_signal_to</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > destination</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
<paramdef > const char *<parameter > types</parameter> </paramdef>
<paramdef > ...</paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_signal_tov</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > destination</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
<paramdef > const char *<parameter > types</parameter> </paramdef>
<paramdef > va_list <parameter > ap</parameter> </paramdef>
</funcprototype>
2020-04-19 21:32:54 +03:00
<funcprototype >
<funcdef > int <function > sd_bus_emit_interfaces_added</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > ...</paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_interfaces_added_strv</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char **<parameter > interfaces</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_interfaces_removed</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > ...</paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_interfaces_removed_strv</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char **<parameter > interfaces</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_properties_changed</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > name</parameter> </paramdef>
<paramdef > ...</paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_properties_changed_strv</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char **<parameter > names</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_object_added</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_emit_object_removed</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > <function > sd_bus_emit_signal()</function> is a convenience function for initializing a
bus message object and emitting the corresponding D-Bus signal. It combines the
<citerefentry > <refentrytitle > sd_bus_message_new_signal</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_bus_message_append</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> and
<citerefentry > <refentrytitle > sd_bus_send</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
functions into a single function call. <function > sd_bus_emit_signalv()</function> is
equivalent to <function > sd_bus_message_append()</function> , except that it is called with a
<literal > va_list</literal> instead of a variable number of arguments.</para>
2022-10-31 23:11:48 +03:00
<para > <function > sd_bus_emit_signal_to()</function> and <function > sd_bus_emit_signal_tov()</function> are
identical to <function > sd_bus_emit_signal()</function> and <function > sd_bus_emit_signalv()</function> , except
that they can emit the signal to a single destination. Give <parameter > destination</parameter> as
<constant > NULL</constant> to broadcast the signal.</para>
2020-04-19 21:32:54 +03:00
<para > <function > sd_bus_emit_interfaces_added()</function> and
<function > sd_bus_emit_interfaces_removed()</function> are used to implement the
<function > InterfacesAdded</function> and <function > InterfacesRemoved</function> signals of the
<constant > org.freedesktop.DBus.ObjectManager</constant> 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
<function > sd_bus_emit_interfaces_added()</function> and
<function > sd_bus_emit_interfaces_removed()</function> <emphasis > must</emphasis> be
<constant > NULL</constant> . This allows both functions to safely determine the number of passed
interface arguments. <function > sd_bus_emit_interfaces_added_strv()</function> and
<function > sd_bus_emit_interfaces_removed_strv()</function> are identical to their respective
counterparts but both take the list of interfaces as a single argument instead of a variable
number of arguments.</para>
<para > <function > sd_bus_emit_properties_changed()</function> is used to implement the
<function > PropertiesChanged</function> signal of the
<constant > org.freedesktop.DBus.Properties</constant> interface. It takes an object path,
interface and a variable list of property names as its arguments. The final argument passed to
<function > sd_bus_emit_properties_changed()</function> <emphasis > must</emphasis> be
<constant > NULL</constant> . This allows it to safely determine the number of passed property
names. <function > sd_bus_emit_properties_changed_strv()</function> is identical to
<function > sd_bus_emit_properties_changed()</function> but takes the list of property names as a
single argument instead of a variable number of arguments.</para>
<para > <function > sd_bus_emit_object_added()</function> and
<function > sd_bus_emit_object_removed()</function> are convenience functions for emitting the
<function > InterfacesAdded</function> or <function > InterfacesRemoved</function> 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.</para>
<para > Note that <function > sd_bus_emit_interfaces_added()</function> ,
<function > sd_bus_emit_interfaces_removed()</function> ,
<function > sd_bus_emit_object_added()</function> and
<function > sd_bus_emit_object_removed()</function> require an object manager to have been
registered on the given object path or one of its parent object paths using
<citerefentry > <refentrytitle > sd_bus_add_object_manager</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> .
</para>
</refsect1>
<refsect1 >
<title > Return Value</title>
<para > On success, these functions return a non-negative integer. On failure, they return a
negative errno-style error code.</para>
<refsect2 >
<title > Errors</title>
<para > Returned errors may indicate the following problems:</para>
<variablelist >
<varlistentry >
<term > <constant > -EINVAL</constant> </term>
<listitem > <para > One of the required parameters is <constant > NULL</constant> or invalid. A
reserved D-Bus interface was passed as the <replaceable > interface</replaceable> parameter.
2024-04-18 03:45:51 +03:00
</para> </listitem>
2020-04-19 21:32:54 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -ENOPKG</constant> </term>
2024-04-18 03:45:51 +03:00
<listitem > <para > The bus cannot be resolved.</para> </listitem>
2020-04-19 21:32:54 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -ECHILD</constant> </term>
2024-04-18 03:45:51 +03:00
<listitem > <para > The bus was created in a different process, library or module instance.</para> </listitem>
2020-04-19 21:32:54 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -ENOMEM</constant> </term>
2024-04-18 03:45:51 +03:00
<listitem > <para > Memory allocation failed.</para> </listitem>
2020-04-19 21:32:54 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -ESRCH</constant> </term>
<listitem > <para > One of <function > sd_bus_emit_interfaces_added()</function> ,
<function > sd_bus_emit_interfaces_removed()</function> ,
<function > sd_bus_emit_object_added()</function> or
<function > sd_bus_emit_object_removed()</function> was called on an object without an
object manager registered on its own object path or one of its parent object paths.
2024-04-18 03:45:51 +03:00
</para> </listitem>
2020-04-19 21:32:54 +03:00
</varlistentry>
</variablelist>
<para > See the man pages of
<citerefentry > <refentrytitle > sd_bus_message_new_signal</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_bus_message_append</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> and
<citerefentry > <refentrytitle > sd_bus_send</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
for more possible errors.</para>
</refsect2>
</refsect1>
<xi:include href= "libsystemd-pkgconfig.xml" />
2023-09-04 15:46:35 +03:00
<refsect1 >
<title > History</title>
2023-09-18 19:44:26 +03:00
<para > <function > sd_bus_emit_signal()</function> ,
<function > sd_bus_emit_interfaces_added()</function> ,
<function > sd_bus_emit_interfaces_added_strv()</function> ,
<function > sd_bus_emit_interfaces_removed()</function> ,
<function > sd_bus_emit_interfaces_removed_strv()</function> ,
<function > sd_bus_emit_properties_changed()</function> ,
2024-04-18 03:45:51 +03:00
<function > sd_bus_emit_properties_changed_strv()</function> , were added in version 221.</para>
<para > <function > sd_bus_emit_object_added()</function> , and
<function > sd_bus_emit_object_removed()</function> were added in version 222.</para>
<para > <function > sd_bus_emit_signalv()</function> was added in version 246.</para>
2023-09-18 19:44:26 +03:00
<para > <function > sd_bus_emit_signal_to()</function> and
<function > sd_bus_emit_signal_tov()</function> were added in version 253.</para>
2023-09-04 15:46:35 +03:00
</refsect1>
2020-04-19 21:32:54 +03:00
<refsect1 >
<title > See Also</title>
2023-12-22 21:09:32 +03:00
<para > <simplelist type= "inline" >
<member > <citerefentry > <refentrytitle > sd-bus</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > busctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_message_new_signal</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_message_append</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_send</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_call_method</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
</simplelist> </para>
2020-04-19 21:32:54 +03:00
</refsect1>
</refentry>