man/sd_bus_message_append_basic.xml

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