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+ -->
6 <refentry id=
"sd_bus_message_new" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
8 <title>sd_bus_message_new
</title>
9 <productname>systemd
</productname>
13 <refentrytitle>sd_bus_message_new
</refentrytitle>
14 <manvolnum>3</manvolnum>
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>
28 <refpurpose>Create a new bus message object and create or destroy references to it
</refpurpose>
33 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
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>,
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>
50 <funcdef>sd_bus_message *
<function>sd_bus_message_ref
</function></funcdef>
51 <paramdef>sd_bus_message *
<parameter>m
</parameter></paramdef>
55 <funcdef>sd_bus_message *
<function>sd_bus_message_unref
</function></funcdef>
56 <paramdef>sd_bus_message *
<parameter>m
</parameter></paramdef>
60 <funcdef>void
<function>sd_bus_message_unrefp
</function></funcdef>
61 <paramdef>sd_bus_message **
<parameter>mp
</parameter></paramdef>
65 <funcdef>sd_bus *
<function>sd_bus_message_get_bus
</function></funcdef>
66 <paramdef>sd_bus_message *
<parameter>m
</parameter></paramdef>
72 <title>Description
</title>
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>
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>
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.
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>.
102 <para><function>sd_bus_message_ref()
</function> increases the reference counter of
103 <parameter>m
</parameter> by one.
</para>
105 <para><function>sd_bus_message_unref()
</function> decreases the 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
108 <function>sd_bus_message_ref()
</function> or
<function>sd_bus_message_unref()
</function> are
111 <para><function>sd_bus_message_unrefp()
</function> is similar to
112 <function>sd_bus_message_unref()
</function> but takes a pointer to a
113 pointer to an
<type>sd_bus_message
</type> object. This call is useful in
114 conjunction with GCC's and LLVM's
<ulink
115 url=
"https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
116 Variable Attribute
</ulink>. See
117 <citerefentry><refentrytitle>sd_bus_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
118 for an example how to use the cleanup attribute.
</para>
120 <para><function>sd_bus_message_ref()
</function> and
<function>sd_bus_message_unref()
</function>
121 execute no operation if the passed in bus object address is
122 <constant>NULL
</constant>.
<function>sd_bus_message_unrefp()
</function> will first dereference
123 its argument, which must not be
<constant>NULL
</constant>, and will execute no operation if
124 <emphasis>that
</emphasis> is
<constant>NULL
</constant>.
127 <para><function>sd_bus_message_get_bus()
</function> returns the bus object that message
128 <parameter>m
</parameter> is attached to.
</para>
132 <title>Return Value
</title>
134 <para>On success,
<function>sd_bus_message_new()
</function> returns
0 or a positive integer. On
135 failure, it returns a negative errno-style error code.
</para>
137 <para><function>sd_bus_message_ref()
</function> always returns the argument.
140 <para><function>sd_bus_message_unref()
</function> always returns
141 <constant>NULL
</constant>.
</para>
143 <para><function>sd_bus_message_get_bus()
</function> always returns the bus object.
</para>
146 <title>Errors
</title>
148 <para>Returned errors may indicate the following problems:
</para>
152 <term><constant>-EINVAL
</constant></term>
154 <listitem><para>Specified
<parameter>type
</parameter> is invalid.
</para></listitem>
158 <term><constant>-ENOTCONN
</constant></term>
160 <listitem><para>The bus parameter
<parameter>bus
</parameter> is
<constant>NULL
</constant> or
161 the bus is not connected.
</para></listitem>
165 <term><constant>-ENOMEM
</constant></term>
167 <listitem><para>Memory allocation failed.
</para></listitem>
173 <xi:include href=
"libsystemd-pkgconfig.xml" />
176 <title>See Also
</title>
179 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
180 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181 <citerefentry><refentrytitle>sd_bus_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182 <citerefentry><refentrytitle>sd_bus_message_new_method_call
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>sd_bus_message_new_method_error
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>sd_bus_message_new_method_return
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>sd_bus_message_new_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>