man/sd_bus_message_append_basic.xml

   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+ -->
   5
   6 <refentry id="sd_bus_message_append_basic" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_bus_message_append_basic</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_message_append_basic</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_message_append_basic</refname>
  20
  21     <refpurpose>Attach a single field to a message</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <funcsynopsis>
  26       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  27
  28       <funcprototype>
  29         <funcdef>int sd_bus_message_append_basic</funcdef>
  30         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  31         <paramdef>char <parameter>type</parameter></paramdef>
  32         <paramdef>const void *<parameter>p</parameter></paramdef>
  33       </funcprototype>
  34     </funcsynopsis>
  35   </refsynopsisdiv>
  36
  37   <refsect1>
  38     <title>Description</title>
  39
  40     <para><function>sd_bus_message_append_basic()</function> appends a
  41     single field to the message <parameter>m</parameter>. The
  42     parameter <parameter>type</parameter> determines how the pointer
  43     <parameter>p</parameter> is interpreted.
  44     <parameter>type</parameter> must be one of the basic types as
  45     defined by the <ulink
  46     url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
  47     Types</ulink> section of the D-Bus specification, and listed in
  48     the table below.
  49     </para>
  50
  51     <table id='format-specifiers'>
  52       <title>Item type specifiers</title>
  53
  54       <tgroup cols='5'>
  55         <colspec colname='specifier' />
  56         <colspec colname='constant' />
  57         <colspec colname='description' />
  58         <colspec colname='size' />
  59         <colspec colname='ctype' />
  60         <thead>
  61           <row>
  62             <entry>Specifier</entry>
  63             <entry>Constant</entry>
  64             <entry>Description</entry>
  65             <entry>Size</entry>
  66             <entry>Expected C Type</entry>
  67           </row>
  68         </thead>
  69         <tbody>
  70           <row>
  71             <entry><literal>y</literal></entry>
  72             <entry><constant>SD_BUS_TYPE_BYTE</constant></entry>
  73             <entry>unsigned integer</entry>
  74             <entry>1 byte</entry>
  75             <entry>uint8_t</entry>
  76           </row>
  77
  78           <row>
  79             <entry><literal>b</literal></entry>
  80             <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry>
  81             <entry>boolean</entry>
  82             <entry>4 bytes</entry>
  83             <entry>int</entry>
  84           </row>
  85
  86           <row>
  87             <entry><literal>n</literal></entry>
  88             <entry><constant>SD_BUS_TYPE_INT16</constant></entry>
  89             <entry>signed integer</entry>
  90             <entry>2 bytes</entry>
  91             <entry>int16_t</entry>
  92           </row>
  93
  94           <row>
  95             <entry><literal>q</literal></entry>
  96             <entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
  97             <entry>unsigned integer</entry>
  98             <entry>2 bytes</entry>
  99             <entry>uint16_t</entry>
 100           </row>
 101
 102           <row>
 103             <entry><literal>i</literal></entry>
 104             <entry><constant>SD_BUS_TYPE_INT32</constant></entry>
 105             <entry>signed integer</entry>
 106             <entry>4 bytes</entry>
 107             <entry>int32_t</entry>
 108           </row>
 109
 110           <row>
 111             <entry><literal>u</literal></entry>
 112             <entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
 113             <entry>unsigned integer</entry>
 114             <entry>4 bytes</entry>
 115             <entry>uint32_t</entry>
 116           </row>
 117
 118           <row>
 119             <entry><literal>x</literal></entry>
 120             <entry><constant>SD_BUS_TYPE_INT64</constant></entry>
 121             <entry>signed integer</entry>
 122             <entry>8 bytes</entry>
 123             <entry>int64_t</entry>
 124           </row>
 125
 126           <row>
 127             <entry><literal>t</literal></entry>
 128             <entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
 129             <entry>unsigned integer</entry>
 130             <entry>8 bytes</entry>
 131             <entry>uint64_t</entry>
 132           </row>
 133
 134           <row>
 135             <entry><literal>d</literal></entry>
 136             <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry>
 137             <entry>floating-point</entry>
 138             <entry>8 bytes</entry>
 139             <entry>double</entry>
 140           </row>
 141
 142           <row>
 143             <entry><literal>s</literal></entry>
 144             <entry><constant>SD_BUS_TYPE_STRING</constant></entry>
 145             <entry>Unicode string</entry>
 146             <entry>variable</entry>
 147             <entry>char[]</entry>
 148           </row>
 149
 150           <row>
 151             <entry><literal>o</literal></entry>
 152             <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry>
 153             <entry>object path</entry>
 154             <entry>variable</entry>
 155             <entry>char[]</entry>
 156           </row>
 157
 158           <row>
 159             <entry><literal>g</literal></entry>
 160             <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry>
 161             <entry>signature</entry>
 162             <entry>variable</entry>
 163             <entry>char[]</entry>
 164           </row>
 165
 166           <row>
 167             <entry><literal>h</literal></entry>
 168             <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry>
 169             <entry>UNIX file descriptor</entry>
 170             <entry>4 bytes</entry>
 171             <entry>int</entry>
 172           </row>
 173        </tbody>
 174       </tgroup>
 175     </table>
 176
 177     <para>The value of the parameter is copied into a memory area held
 178     by the message object, stays in the possession of the caller and
 179     may hence be freely changed after this call without affecting the
 180     bus message it has been added to. If <parameter>type</parameter>
 181     is <literal>h</literal> (UNIX file descriptor), the descriptor is
 182     duplicated by this call and the passed descriptor stays in
 183     possession of the caller.</para>
 184
 185     <para>For types <literal>s</literal>, <literal>o</literal>, and
 186     <literal>g</literal>, the parameter <parameter>p</parameter> is
 187     interpreted as a pointer to a <constant>NUL</constant>-terminated
 188     character sequence. As a special case, a <constant>NULL</constant>
 189     pointer is interpreted as an empty string. The string should be
 190     valid Unicode string encoded as UTF-8. In case of the two latter
 191     types, the additional requirements for a D-Bus object path or
 192     type signature should be satisfied. Those requirements should be
 193     verified by the recipient of the message.
 194     </para>
 195   </refsect1>
 196
 197   <refsect1>
 198     <title>Return Value</title>
 199
 200     <para>On success, this call returns 0 or a positive integer. On
 201     failure, it returns a negative errno-style error code.</para>
 202
 203     <refsect2 id='errors'>
 204       <title>Errors</title>
 205
 206       <para>Returned errors may indicate the following problems:</para>
 207
 208       <variablelist>
 209
 210         <varlistentry>
 211           <term><constant>-EINVAL</constant></term>
 212
 213           <listitem><para>Specified parameter is invalid.
 214           </para></listitem>
 215         </varlistentry>
 216
 217         <varlistentry>
 218           <term><constant>-EPERM</constant></term>
 219
 220           <listitem><para>Message has been sealed.
 221           </para></listitem>
 222         </varlistentry>
 223
 224         <varlistentry>
 225           <term><constant>-ESTALE</constant></term>
 226
 227           <listitem><para>Message is in invalid state.
 228           </para></listitem>
 229         </varlistentry>
 230
 231         <varlistentry>
 232           <term><constant>-ENXIO</constant></term>
 233
 234           <listitem><para>Message cannot be appended to.
 235           </para></listitem>
 236         </varlistentry>
 237
 238         <varlistentry>
 239           <term><constant>-ENOMEM</constant></term>
 240
 241           <listitem><para>Memory allocation failed.</para></listitem>
 242         </varlistentry>
 243       </variablelist>
 244     </refsect2>
 245   </refsect1>
 246
 247   <xi:include href="libsystemd-pkgconfig.xml" />
 248
 249   <refsect1>
 250     <title>See Also</title>
 251
 252     <para>
 253       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 257       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 258     </para>
 259   </refsect1>
 260
 261 </refentry>