[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+ -->

<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 reference counter of
    <parameter>m</parameter> by one.</para>

    <para><function>sd_bus_message_unref()</function> decreases the 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 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 ZJS	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>
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
	102	<para><function>sd_bus_message_ref()</function> increases the reference counter of
	103	<parameter>m</parameter> by one.</para>
	104
	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
	109	illegal.</para>
	110
	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>
	119
	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>.
	125	</para>
99052565 ZJS	126
	127	<para><function>sd_bus_message_get_bus()</function> returns the bus object that message
	128	<parameter>m</parameter> is attached to.</para>
206ed9c1 ZJS	129	</refsect1>
	130
	131	<refsect1>
	132	<title>Return Value</title>
	133
	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>
	136
	137	<para><function>sd_bus_message_ref()</function> always returns the argument.
	138	</para>
	139
	140	<para><function>sd_bus_message_unref()</function> always returns
	141	<constant>NULL</constant>.</para>
99052565 ZJS	142
99052565 ZJS	143	<para><function>sd_bus_message_get_bus()</function> always returns the bus object.</para>
206ed9c1	144
b1de39de ZJS	145	<refsect2>
b1de39de ZJS	146	<title>Errors</title>
206ed9c1	147
b1de39de	148	<para>Returned errors may indicate the following problems:</para>
206ed9c1	149
b1de39de ZJS	150	<variablelist>
	151	<varlistentry>
	152	<term><constant>-EINVAL</constant></term>
206ed9c1	153
b1de39de ZJS	154	<listitem><para>Specified <parameter>type</parameter> is invalid.</para></listitem>
b1de39de ZJS	155	</varlistentry>
206ed9c1	156
b1de39de ZJS	157	<varlistentry>
b1de39de ZJS	158	<term><constant>-ENOTCONN</constant></term>
206ed9c1	159
b1de39de ZJS	160	<listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
	161	the bus is not connected.</para></listitem>
	162	</varlistentry>
206ed9c1	163
b1de39de ZJS	164	<varlistentry>
b1de39de ZJS	165	<term><constant>-ENOMEM</constant></term>
206ed9c1	166
b1de39de ZJS	167	<listitem><para>Memory allocation failed.</para></listitem>
	168	</varlistentry>
	169	</variablelist>
	170	</refsect2>
206ed9c1 ZJS	171	</refsect1>
	172
	173	<xi:include href="libsystemd-pkgconfig.xml" />
	174
	175	<refsect1>
	176	<title>See Also</title>
	177
	178	<para>
	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>
	186	</para>
	187	</refsect1>
	188
	189	</refentry>