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-or-later --> 5 6<refentry id="sd_bus_emit_signal" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_bus_emit_signal</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_bus_emit_signal</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 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> 30 31 <refpurpose>Convenience functions for emitting (standard) D-Bus signals</refpurpose> 32 </refnamediv> 33 34 <refsynopsisdiv> 35 <funcsynopsis> 36 <funcsynopsisinfo>#include <systemd/sd-bus-vtable.h></funcsynopsisinfo> 37 38 <funcprototype> 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> 46 </funcprototype> 47 48 <funcprototype> 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> 56 </funcprototype> 57 58 <funcprototype> 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> 64 </funcprototype> 65 66 <funcprototype> 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> 71 </funcprototype> 72 73 <funcprototype> 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> 79 </funcprototype> 80 81 <funcprototype> 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> 86 </funcprototype> 87 88 <funcprototype> 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> 95 </funcprototype> 96 97 <funcprototype> 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> 103 </funcprototype> 104 105 <funcprototype> 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> 109 </funcprototype> 110 111 <funcprototype> 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> 115 </funcprototype> 116 </funcsynopsis> 117 </refsynopsisdiv> 118 119 <refsect1> 120 <title>Description</title> 121 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> 130 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> 144 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> 154 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> 161 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>. 168 </para> 169 </refsect1> 170 171 <refsect1> 172 <title>Return Value</title> 173 174 <para>On success, these functions return a non-negative integer. On failure, they return a 175 negative errno-style error code.</para> 176 177 <refsect2> 178 <title>Errors</title> 179 180 <para>Returned errors may indicate the following problems:</para> 181 182 <variablelist> 183 <varlistentry> 184 <term><constant>-EINVAL</constant></term> 185 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. 188 </para></listitem> 189 </varlistentry> 190 191 <varlistentry> 192 <term><constant>-ENOPKG</constant></term> 193 194 <listitem><para>The bus cannot be resolved.</para></listitem> 195 </varlistentry> 196 197 <varlistentry> 198 <term><constant>-ECHILD</constant></term> 199 200 <listitem><para>The bus was created in a different process.</para></listitem> 201 </varlistentry> 202 203 <varlistentry> 204 <term><constant>-ENOMEM</constant></term> 205 206 <listitem><para>Memory allocation failed.</para></listitem> 207 </varlistentry> 208 209 <varlistentry> 210 <term><constant>-ESRCH</constant></term> 211 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. 217 </para></listitem> 218 </varlistentry> 219 </variablelist> 220 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> 226 </refsect2> 227 </refsect1> 228 229 <xi:include href="libsystemd-pkgconfig.xml" /> 230 231 <refsect1> 232 <title>See Also</title> 233 234 <para> 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> 241 </para> 242 </refsect1> 243</refentry> 244