man/sd_bus_message_new.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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_message_new" xmlns:xi="http://www.w3.org/2001/XInclude">
   7   <refentryinfo>
   8     <title>sd_bus_message_new</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>sd_bus_message_new</refentrytitle>
  14     <manvolnum>3</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>sd_bus_message_new</refname>
  19     <refname>sd_bus_message_ref</refname>
  20     <refname>sd_bus_message_unref</refname>
  21     <refname>sd_bus_message_unrefp</refname>
  22     <refname>SD_BUS_MESSAGE_METHOD_CALL</refname>
  23     <refname>SD_BUS_MESSAGE_METHOD_RETURN</refname>
  24     <refname>SD_BUS_MESSAGE_METHOD_ERROR</refname>
  25     <refname>SD_BUS_MESSAGE_SIGNAL</refname>
  26     <refname>sd_bus_message_get_bus</refname>
  27
  28     <refpurpose>Create a new bus message object and create or destroy references to it</refpurpose>
  29   </refnamediv>
  30
  31   <refsynopsisdiv>
  32     <funcsynopsis>
  33       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  34
  35       <funcsynopsisinfo><token>enum</token> {
  36       <constant>SD_BUS_MESSAGE_METHOD_CALL</constant>,
  37       <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant>,
  38       <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant>,
  39       <constant>SD_BUS_MESSAGE_SIGNAL</constant>,
  40 };</funcsynopsisinfo>
  41
  42       <funcprototype>
  43         <funcdef>int <function>sd_bus_message_new</function></funcdef>
  44         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  45         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
  46         <paramdef>uint8_t <parameter>type</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>sd_bus_message *<function>sd_bus_message_ref</function></funcdef>
  51         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  55         <funcdef>sd_bus_message *<function>sd_bus_message_unref</function></funcdef>
  56         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  57       </funcprototype>
  58
  59       <funcprototype>
  60         <funcdef>void <function>sd_bus_message_unrefp</function></funcdef>
  61         <paramdef>sd_bus_message **<parameter>mp</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>sd_bus *<function>sd_bus_message_get_bus</function></funcdef>
  66         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  67       </funcprototype>
  68     </funcsynopsis>
  69   </refsynopsisdiv>
  70
  71   <refsect1>
  72     <title>Description</title>
  73
  74     <para><function>sd_bus_message_new()</function> creates a new bus message object attached to the
  75     bus <parameter>bus</parameter> and returns it in the output parameter <parameter>m</parameter>.
  76     This object is reference-counted, and will be destroyed when all references are gone. Initially,
  77     the caller of this function owns the sole reference to the message object. Note that the message
  78     object holds a reference to the bus object, so the bus object will not be destroyed as long as
  79     the message exists.</para>
  80
  81     <para>Note: this is a low-level call. In most cases functions like
  82     <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  83     <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  84     <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  85     and <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  86     that create a message of a certain type and initialize various fields are easier to use.</para>
  87
  88     <para>The <parameter>type</parameter> parameter specifies the type of the message.  It must be
  89     one of <constant>SD_BUS_MESSAGE_METHOD_CALL</constant> — a method call,
  90     <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant> — a method call reply,
  91     <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant> — an error reply to a method call,
  92     <constant>SD_BUS_MESSAGE_SIGNAL</constant> — a broadcast message with no reply.
  93     </para>
  94
  95     <para>The flag to allow interactive authorization is initialized based on the current value set
  96     in the bus object, see
  97     <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  98     This may be changed using
  99     <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 100     </para>
 101
 102     <para><function>sd_bus_message_ref()</function> increases the internal reference counter of
 103     <parameter>m</parameter> by one.</para>
 104
 105     <para><function>sd_bus_message_unref()</function> decreases the internal reference counter of
 106     <parameter>m</parameter> by one. Once the reference count has dropped to zero, message object is
 107     destroyed and cannot be used anymore, so further calls to <function>sd_bus_message_ref()</function> or
 108     <function>sd_bus_message_unref()</function> are illegal.</para>
 109
 110     <para><function>sd_bus_message_unrefp()</function> is similar to
 111     <function>sd_bus_message_unref()</function> but takes a pointer to a
 112     pointer to an <type>sd_bus_message</type> object. This call is useful in
 113     conjunction with GCC's and LLVM's <ulink
 114     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 115     Variable Attribute</ulink>. See
 116     <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 117     for an example how to use the cleanup attribute.</para>
 118
 119     <para><function>sd_bus_message_ref()</function> and <function>sd_bus_message_unref()</function>
 120     execute no operation if the passed in bus message object address is
 121     <constant>NULL</constant>. <function>sd_bus_message_unrefp()</function> will first dereference
 122     its argument, which must not be <constant>NULL</constant>, and will execute no operation if
 123     <emphasis>that</emphasis> is <constant>NULL</constant>.
 124     </para>
 125
 126     <para><function>sd_bus_message_get_bus()</function> returns the bus object that message
 127     <parameter>m</parameter> is attached to.</para>
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Return Value</title>
 132
 133     <para>On success, <function>sd_bus_message_new()</function> returns 0 or a positive integer. On
 134     failure, it returns a negative errno-style error code.</para>
 135
 136     <para><function>sd_bus_message_ref()</function> always returns the argument.
 137     </para>
 138
 139     <para><function>sd_bus_message_unref()</function> always returns
 140     <constant>NULL</constant>.</para>
 141
 142     <para><function>sd_bus_message_get_bus()</function> always returns the bus object.</para>
 143
 144     <refsect2>
 145       <title>Errors</title>
 146
 147       <para>Returned errors may indicate the following problems:</para>
 148
 149       <variablelist>
 150         <varlistentry>
 151           <term><constant>-EINVAL</constant></term>
 152
 153           <listitem><para>Specified <parameter>type</parameter> is invalid.</para></listitem>
 154         </varlistentry>
 155
 156         <varlistentry>
 157           <term><constant>-ENOTCONN</constant></term>
 158
 159           <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
 160           the bus is not connected.</para></listitem>
 161         </varlistentry>
 162
 163         <varlistentry>
 164           <term><constant>-ENOMEM</constant></term>
 165
 166           <listitem><para>Memory allocation failed.</para></listitem>
 167         </varlistentry>
 168       </variablelist>
 169     </refsect2>
 170   </refsect1>
 171
 172   <xi:include href="libsystemd-pkgconfig.xml" />
 173
 174   <refsect1>
 175     <title>History</title>
 176     <para><function>sd_bus_message_new()</function>,
 177     <function>sd_bus_message_ref()</function>,
 178     <function>sd_bus_message_unref()</function>,
 179     <function>sd_bus_message_unrefp()</function>, and
 180     <function>sd_bus_message_get_bus()</function> were added in version 240.</para>
 181   </refsect1>
 182
 183   <refsect1>
 184     <title>See Also</title>
 185
 186     <para>
 187       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 191       <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192       <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 194     </para>
 195   </refsect1>
 196
 197 </refentry>