[thirdparty/systemd.git] / man / sd_bus_message_new.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="sd_bus_message_new" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refentryinfo>
    <title>sd_bus_message_new</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sd_bus_message_new</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sd_bus_message_new</refname>
    <refname>sd_bus_message_ref</refname>
    <refname>sd_bus_message_unref</refname>
    <refname>sd_bus_message_unrefp</refname>
    <refname>SD_BUS_MESSAGE_METHOD_CALL</refname>
    <refname>SD_BUS_MESSAGE_METHOD_RETURN</refname>
    <refname>SD_BUS_MESSAGE_METHOD_ERROR</refname>
    <refname>SD_BUS_MESSAGE_SIGNAL</refname>
    <refname>sd_bus_message_get_bus</refname>

    <refpurpose>Create a new bus message object and create or destroy references to it</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>

      <funcsynopsisinfo><token>enum</token> {
      <constant>SD_BUS_MESSAGE_METHOD_CALL</constant>,
      <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant>,
      <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant>,
      <constant>SD_BUS_MESSAGE_SIGNAL</constant>,
};</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sd_bus_message_new</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
        <paramdef>uint8_t <parameter>type</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus_message *<function>sd_bus_message_ref</function></funcdef>
        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus_message *<function>sd_bus_message_unref</function></funcdef>
        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>void <function>sd_bus_message_unrefp</function></funcdef>
        <paramdef>sd_bus_message **<parameter>mp</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus *<function>sd_bus_message_get_bus</function></funcdef>
        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><function>sd_bus_message_new()</function> creates a new bus message object attached to the
    bus <parameter>bus</parameter> and returns it in the output parameter <parameter>m</parameter>.
    This object is reference-counted, and will be destroyed when all references are gone. Initially,
    the caller of this function owns the sole reference to the message object. Note that the message
    object holds a reference to the bus object, so the bus object will not be destroyed as long as
    the message exists.</para>

    <para>Note: this is a low-level call. In most cases functions like
    <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    and <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    that create a message of a certain type and initialize various fields are easier to use.</para>

    <para>The <parameter>type</parameter> parameter specifies the type of the message.  It must be
    one of <constant>SD_BUS_MESSAGE_METHOD_CALL</constant> — a method call,
    <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant> — a method call reply,
    <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant> — an error reply to a method call,
    <constant>SD_BUS_MESSAGE_SIGNAL</constant> — a broadcast message with no reply.
    </para>

    <para>The flag to allow interactive authorization is initialized based on the current value set
    in the bus object, see
    <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
    This may be changed using
    <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
    </para>

    <para><function>sd_bus_message_ref()</function> increases the internal reference counter of
    <parameter>m</parameter> by one.</para>

    <para><function>sd_bus_message_unref()</function> decreases the internal reference counter of
    <parameter>m</parameter> by one. Once the reference count has dropped to zero, message object is
    destroyed and cannot be used anymore, so further calls to <function>sd_bus_message_ref()</function> or
    <function>sd_bus_message_unref()</function> are illegal.</para>

    <para><function>sd_bus_message_unrefp()</function> is similar to
    <function>sd_bus_message_unref()</function> but takes a pointer to a
    pointer to an <type>sd_bus_message</type> object. This call is useful in
    conjunction with GCC's and LLVM's <ulink
    url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
    Variable Attribute</ulink>. See
    <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    for an example how to use the cleanup attribute.</para>

    <para><function>sd_bus_message_ref()</function> and <function>sd_bus_message_unref()</function>
    execute no operation if the passed in bus message object address is
    <constant>NULL</constant>. <function>sd_bus_message_unrefp()</function> will first dereference
    its argument, which must not be <constant>NULL</constant>, and will execute no operation if
    <emphasis>that</emphasis> is <constant>NULL</constant>.
    </para>

    <para><function>sd_bus_message_get_bus()</function> returns the bus object that message
    <parameter>m</parameter> is attached to.</para>
  </refsect1>

  <refsect1>
    <title>Return Value</title>

    <para>On success, <function>sd_bus_message_new()</function> returns 0 or a positive integer. On
    failure, it returns a negative errno-style error code.</para>

    <para><function>sd_bus_message_ref()</function> always returns the argument.
    </para>

    <para><function>sd_bus_message_unref()</function> always returns
    <constant>NULL</constant>.</para>

    <para><function>sd_bus_message_get_bus()</function> always returns the bus object.</para>

    <refsect2>
      <title>Errors</title>

      <para>Returned errors may indicate the following problems:</para>

      <variablelist>
        <varlistentry>
          <term><constant>-EINVAL</constant></term>

          <listitem><para>Specified <parameter>type</parameter> is invalid.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENOTCONN</constant></term>

          <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
          the bus is not connected.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENOMEM</constant></term>

          <listitem><para>Memory allocation failed.</para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <xi:include href="libsystemd-pkgconfig.xml" />

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>
Commit	Line	Data
206ed9c1	1	<?xml version='1.0'?>
3a54a157	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
206ed9c1	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
db9ecf05	4	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
206ed9c1 ZJS	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>
99052565	26	<refname>sd_bus_message_get_bus</refname>
206ed9c1 ZJS	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 <systemd/sd-bus.h></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>
99052565 ZJS	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>
206ed9c1 ZJS	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
52e30c6f	102	<para><function>sd_bus_message_ref()</function> increases the internal reference counter of
206ed9c1 ZJS	103	<parameter>m</parameter> by one.</para>
206ed9c1 ZJS	104
52e30c6f	105	<para><function>sd_bus_message_unref()</function> decreases the internal reference counter of
206ed9c1	106	<parameter>m</parameter> by one. Once the reference count has dropped to zero, message object is
52e30c6f ZJS	107	destroyed and cannot be used anymore, so further calls to <function>sd_bus_message_ref()</function> or
52e30c6f ZJS	108	<function>sd_bus_message_unref()</function> are illegal.</para>
206ed9c1 ZJS	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>
f280aecd	120	execute no operation if the passed in bus message object address is
206ed9c1 ZJS	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>
99052565 ZJS	125
	126	<para><function>sd_bus_message_get_bus()</function> returns the bus object that message
	127	<parameter>m</parameter> is attached to.</para>
206ed9c1 ZJS	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>
99052565 ZJS	141
99052565 ZJS	142	<para><function>sd_bus_message_get_bus()</function> always returns the bus object.</para>
206ed9c1	143
b1de39de ZJS	144	<refsect2>
b1de39de ZJS	145	<title>Errors</title>
206ed9c1	146
b1de39de	147	<para>Returned errors may indicate the following problems:</para>
206ed9c1	148
b1de39de ZJS	149	<variablelist>
	150	<varlistentry>
	151	<term><constant>-EINVAL</constant></term>
206ed9c1	152
b1de39de ZJS	153	<listitem><para>Specified <parameter>type</parameter> is invalid.</para></listitem>
b1de39de ZJS	154	</varlistentry>
206ed9c1	155
b1de39de ZJS	156	<varlistentry>
b1de39de ZJS	157	<term><constant>-ENOTCONN</constant></term>
206ed9c1	158
b1de39de ZJS	159	<listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
	160	the bus is not connected.</para></listitem>
	161	</varlistentry>
206ed9c1	162
b1de39de ZJS	163	<varlistentry>
b1de39de ZJS	164	<term><constant>-ENOMEM</constant></term>
206ed9c1	165
b1de39de ZJS	166	<listitem><para>Memory allocation failed.</para></listitem>
	167	</varlistentry>
	168	</variablelist>
	169	</refsect2>
206ed9c1 ZJS	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>