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>See Also</title>
176
177    <para>
178      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
179      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
180      <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181      <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182      <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183      <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184      <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
185    </para>
186  </refsect1>
187
188</refentry>
189