man/sd_bus_message_new.xml

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