man/sd_bus_message_new_signal.xml

   1 <?xml version='1.0'?>
   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 -->
   5
   6 <refentry id="sd_bus_message_new_signal"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_message_new_signal</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_message_new_signal</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_message_new_signal</refname>
  21     <refname>sd_bus_message_new_signal_to</refname>
  22
  23     <refpurpose>Create a signal message</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  29
  30       <funcprototype>
  31         <funcdef>int sd_bus_message_new_signal</funcdef>
  32         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  33         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
  34         <paramdef>const char *<parameter>path</parameter></paramdef>
  35         <paramdef>const char *<parameter>interface</parameter></paramdef>
  36         <paramdef>const char *<parameter>member</parameter></paramdef>
  37       </funcprototype>
  38
  39       <funcprototype>
  40         <funcdef>int sd_bus_message_new_signal_to</funcdef>
  41         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  42         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
  43         <paramdef>const char *<parameter>destination</parameter></paramdef>
  44         <paramdef>const char *<parameter>path</parameter></paramdef>
  45         <paramdef>const char *<parameter>interface</parameter></paramdef>
  46         <paramdef>const char *<parameter>member</parameter></paramdef>
  47       </funcprototype>
  48     </funcsynopsis>
  49   </refsynopsisdiv>
  50
  51   <refsect1>
  52     <title>Description</title>
  53
  54     <para>The <function>sd_bus_message_new_signal()</function> function creates a new bus message
  55     object that encapsulates a D-Bus signal, and returns it in the <parameter>m</parameter> output
  56     parameter. The signal will be sent to path <parameter>path</parameter>, on the interface
  57     <parameter>interface</parameter>, member <parameter>member</parameter>. When this message is
  58     sent, no reply is expected. See
  59     <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  60     for a short description of the meaning of the <parameter>path</parameter>,
  61     <parameter>interface</parameter>, and <parameter>member</parameter> parameters.
  62     </para>
  63
  64     <para><function>sd_bus_message_new_signal_to()</function> is a shorthand for creating a new bus message
  65     to a specific destination. It's behavior is similar to calling
  66     <function>sd_bus_message_new_signal()</function> followed by calling
  67     <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  68     </para>
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>Return Value</title>
  73
  74     <para>This function returns 0 if the message object was successfully created, and a negative
  75     errno-style error code otherwise.</para>
  76
  77     <refsect2>
  78       <title>Errors</title>
  79
  80       <para>Returned errors may indicate the following problems:</para>
  81
  82       <variablelist>
  83         <varlistentry>
  84           <term><constant>-EINVAL</constant></term>
  85
  86           <listitem><para>The output parameter <parameter>m</parameter> is
  87           <constant>NULL</constant>.</para>
  88
  89           <para>The <parameter>path</parameter> parameter is not a valid D-Bus path
  90           (<literal>/an/object/path</literal>), the <parameter>interface</parameter> parameter is not
  91           a valid D-Bus interface name (<literal>an.interface.name</literal>), or the
  92           <parameter>member</parameter> parameter is not a valid D-Bus member
  93           (<literal>Name</literal>).</para></listitem>
  94         </varlistentry>
  95
  96         <varlistentry>
  97           <term><constant>-ENOTCONN</constant></term>
  98
  99           <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
 100           the bus is not connected.</para></listitem>
 101         </varlistentry>
 102
 103         <varlistentry>
 104           <term><constant>-ENOMEM</constant></term>
 105
 106           <listitem><para>Memory allocation failed.</para></listitem>
 107         </varlistentry>
 108       </variablelist>
 109     </refsect2>
 110   </refsect1>
 111
 112   <xi:include href="libsystemd-pkgconfig.xml" />
 113
 114   <refsect1>
 115     <title>Examples</title>
 116
 117     <example>
 118       <title>Send a simple signal</title>
 119
 120       <programlisting><xi:include href="send-unit-files-changed.c" parse="text" /></programlisting>
 121
 122       <para>This function in systemd sources is used to emit the
 123       <literal>UnitFilesChanged</literal> signal when the unit files have been changed.
 124       </para>
 125     </example>
 126   </refsect1>
 127
 128   <refsect1>
 129     <title>See Also</title>
 130
 131     <para><simplelist type="inline">
 132       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 133       <member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 134       <member><citerefentry><refentrytitle>sd_bus_emit_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 135       <member><citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 136     </simplelist></para>
 137   </refsect1>
 138
 139 </refentry>