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